> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Quickstart

## 1. Get an API key

Create an API key in your [USGM dashboard](https://inbox.usglobalmail.com/app/settings/developer/api-keys). Use a `usgmk_test_…` key
against the sandbox while you build; switch to a `usgmk_live_…` key when you go to production.

> **Warning**
>
> 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`**

```bash title="curl"
curl https://api.usglobalmail.com/v1/mails \
  -H "Authorization: Bearer $USGM_API_KEY"
```

**`TypeScript`**

```typescript title="TypeScript"
import { UsgmClient } from "@usgm/sdk";

const usgm = new UsgmClient({ apiKey: process.env.USGM_API_KEY });

const page = await usgm.mails.list();
console.log(page.data);
```

**`Python`**

```python title="Python"
from usgm import Usgm

usgm = Usgm(api_key=os.environ["USGM_API_KEY"])

page = usgm.mails.list()
print(page.data)
```

A successful response is a page of mail items:

```json
{
  "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](/guides/core-concepts/pagination).
* **Check for errors** — any non-2xx response is a `problem+json` body with a `code` and a `request_id`. See [Errors](/guides/core-concepts/errors).

#### Explore the endpoints

Browse the full surface in the [API Reference](/api) and try calls right in the browser.

#### Install an SDK

Skip the HTTP plumbing with an [official SDK](/sdks/client-libraries/overview) for TypeScript, Python, PHP, or Go.

#### Stop polling

Subscribe to [webhooks](/guides/core-concepts/webhooks) to get a signed callback the moment mail
arrives, instead of listing on a timer.

#### Automate with an agent

Connect the [MCP server](/mcp/mcp-server) to let a coding agent drive the mailbox.