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