Skip to navigation
Getting started

Quickstart

Make your first authenticated request in a couple of minutes.

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.

Treat the key like a password — anyone with it can act on your mailbox. Never commit it or put it in client-side code. Store it in an environment variable and rotate it if it leaks.

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:

{
  "data": [
    {
      "id": "12345",
      "folder_id": "67890",
      "sender_name": "Internal Revenue Service",
      "mail_type": "letter",
      "mail_status": "inbox",
      "recipient_name": "John Doe",
      "is_read": false,
      "arrival_date": "2026-07-11T16:04:00Z",
      "envelope_image_url": "https://usgm-fe-media-prod.s3.us-east-1.amazonaws.com/sample_mail.jpg"
    }
  ],
  "next_cursor": "eyJvIjoyNX0",
  "total_count": 143
}

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.
1

Explore the endpoints

Browse the full surface in the API Reference and try calls right in the browser.

2

Install an SDK

Skip the HTTP plumbing with an official SDK for TypeScript, Python, PHP, or Go.

3

Stop polling

Subscribe to webhooks to get a signed callback the moment mail arrives, instead of listing on a timer.

4

Automate with an agent

Connect the MCP server to let a coding agent drive the mailbox.