USGM Public API
Programmatic access to your US Global Mail mailbox — mail items, scans, shipments, folders, and addresses.
The USGM Public API lets you manage a US Global Mail mailbox from your own code: list and organize scanned mail, request scans, manage folders, view shipments, and manage shipping and deposit addresses. 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.
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 }. 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.
- Status — live uptime and incidents are at status.usglobalmail.com. See System status.