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

# US Global Mail API

> Official documentation for the USGM API — REST endpoints, SDKs (TypeScript, Python, PHP, Go), an MCP server, and guides for your US Global Mail mailbox.

The USGM API lets you manage a US Global Mail mailbox from your own code: list and organize
scanned mail, request scans, manage folders, view shipments, manage shipping and deposit
addresses, and manage bank accounts for check deposits. It's a REST API over HTTPS with predictable, resource-oriented URLs, JSON request and
response bodies, and standard HTTP status codes.

#### [Quickstart](/guides/getting-started/quickstart)

Make your first authenticated request in a couple of minutes.

#### [API Reference](/api/api-reference)

Every endpoint, parameter, and response — with an interactive explorer.

#### [SDKs](/sdks/client-libraries/overview)

Official TypeScript, Python, PHP, and Go client libraries.

#### [Webhooks](/guides/core-concepts/webhooks)

Get a callback when mail arrives, instead of polling.

#### [MCP server](/mcp/mcp-server)

Let an AI agent manage the mailbox on your behalf.

## Base URL

All requests go to the gateway over HTTPS. The path always includes the API version (`/v1`).

| Environment | Base URL                               | Keys           |
| ----------- | -------------------------------------- | -------------- |
| Production  | `https://api.usglobalmail.com`         | `usgmk_live_…` |
| Sandbox     | `https://api-sandbox.usglobalmail.com` | `usgmk_test_…` |

```bash
curl https://api.usglobalmail.com/v1/mails \
  -H "Authorization: Bearer usgmk_live_…"
```

> **Note**
>
> The sandbox is a full copy of the API that never touches live mail. Develop against it with a
> `usgmk_test_…` key, then swap in a `usgmk_live_…` key and the production base URL to go live.

## Conventions

* **Authentication** — every request needs your API key as a bearer token. See [Authentication](/guides/core-concepts/authentication).
* **JSON** — request and response bodies are JSON; timestamps are ISO-8601 (`2026-07-13T14:32:00Z`).
* **Ids** — resource ids are strings. Mail items and folders use numeric strings; everything else uses UUIDs.
* **Pagination** — list endpoints return `{ data, next_cursor, total_count }`. See [Pagination](/guides/core-concepts/pagination).
* **Errors** — non-2xx responses are RFC 9457 `application/problem+json`. See [Errors](/guides/core-concepts/errors).
* **Rate limits** — requests are throttled at the edge, keyed by API key. See [Rate limits](/guides/core-concepts/rate-limits).
* **Webhooks** — get a signed callback when mail arrives or a request changes, instead of polling. See [Webhooks](/guides/core-concepts/webhooks).
* **Status** — live uptime and incidents are at [status.usglobalmail.com](https://status.usglobalmail.com). See [System status](/guides/core-concepts/system-status).