Quickstart

1. Get an API key

Create an API key in your USGM dashboard. Use a usgmk_test_… key against the sandbox while you build; switch to a usgmk_live_… key when you go to production.

2. Make a request

Every request sends your key as a bearer token. List the mail in your mailbox:

$
curl https://api.usglobalmail.com/v1/mails \
>
  -H "Authorization: Bearer $USGM_API_KEY"

A successful response is a page of mail items:

1
{
2
  "data": [
3
    {
4
      "id": "80421",
5
      "sender": "Internal Revenue Service",
6
      "type": "letter",
7
      "is_read": false,
8
      "received_at": "2026-07-11T16:04:00Z"
9
    }
10
  ],
11
  "next_cursor": "eyJvIjoyNX0"
12
}

3. Handle the response

• Page through results with next_cursor — pass it back as ?cursor= until it’s null. See Pagination.
• Check for errors — any non-2xx response is a problem+json body with a code and a request_id. See Errors.