List | USGM Public API

{
  "data": [
    {
      "id": "1023456789",
      "is_read": false,
      "mail_status": "inbox",
      "mail_type": "letter",
      "folder_id": "42",
      "sender_name": "Acme Corp",
      "recipient_name": "John Doe",
      "arrival_date": "2024-01-15T09:30:00Z",
      "envelope_image_url": "https://usglobalmail.com/images/envelopes/1023456789.jpg",
      "quarantine_reason": null,
      "scan": {
        "uuid": "a3f1c9e2-7b4d-4f8a-9c2e-1d2f3b4a5c6d",
        "status": "COMPLETED",
        "category": "SCAN_REQUEST",
        "label": "Bank Statement"
      }
    }
  ],
  "next_cursor": "eyJjdXJzb3IiOiIxMDI0NTY3ODkiLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTAxVDA4OjAwOjAwWiJ9"
}

Authentication

AuthorizationBearer

Your API key, sent as Authorization: Bearer usgmk_live_....

Query parameters

limitintegerOptional<=9007199254740991Defaults to 25

Page size, capped at 100.

cursorstringOptional>=1 character

Opaque page cursor — the next_cursor of the previous response. Omit for the first page.

statuslist of enumsOptional

Allowed values:

mail_typelist of enumsOptional

folder_idintegerOptional<=9007199254740991

searchstringOptional1-100 characters

scan_statuslist of enumsOptional

Filter by the item’s scan state; none selects items with no scan.

sortenumOptional

Allowed values:

arrivedenumOptional

Allowed values:

is_readenumOptional

Allowed values:

Response

datalist of objects

next_cursorstring or null

Pass as ?cursor= to fetch the next page. Null on the last page.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

$	curl https://api.usglobalmail.com/v1/mails \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json"