US Global Mail API
Programmatic access to your US Global Mail mailbox — mail items, scans, shipments, folders and more.
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.
Make your first authenticated request in a couple of minutes.
Every endpoint, parameter, and response — with an interactive explorer.
Official TypeScript, Python, PHP, and Go client libraries.
Get a callback when mail arrives, instead of polling.
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).
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.
- 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. - Errors — non-2xx responses are RFC 9457
application/problem+json. See Errors. - Rate limits — requests are throttled at the edge, keyed by API key. See Rate limits.
- Webhooks — get a signed callback when mail arrives or a request changes, instead of polling. See Webhooks.
- Status — live uptime and incidents are at status.usglobalmail.com. See System status.