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": "12345",
5
      "folder_id": "67890",
6
      "sender_name": "Internal Revenue Service",
7
      "mail_type": "letter",
8
      "mail_status": "inbox",
9
      "recipient_name": "John Doe",
10
      "is_read": false,
11
      "arrival_date": "2026-07-11T16:04:00Z",
12
      "envelope_image_url": "https://usgm-fe-media-prod.s3.us-east-1.amazonaws.com/sample_mail.jpg"
13
    }
14
  ],
15
  "next_cursor": "eyJvIjoyNX0",
16
  "total_count": 143
17
}

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.