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.
View API Reference →
SDKs
Official client libraries for TypeScript, Python, PHP, and Go.
We publish official SDKs so you don't have to hand-roll HTTP calls, auth headers, pagination, retries, or error handling. Every SDK is generated from the same OpenAPI spec that powers our API reference, so it always matches the live API — and is fully typed.
Language | Install | Docs |
TypeScript | npm install @usgm/sdk | |
Python | pip install usgm |
|
PHP | composer require usgm/sdk |
|
Go | go get github.com/usgm/usgm-go |
|
What every SDK gives you
Authentication — pass your API key once as
token; the SDK sends it on every request.Typed models — resources and parameters are fully typed for editor autocomplete and safety.
Cursor pagination — list methods return a page (
data,next_cursor,total_count); passnext_cursorback to fetch the next page.Retries with backoff — transient
429/5xxresponses are retried automatically.Typed errors — non-2xx responses raise a typed error carrying the HTTP
statusand the problem+jsonbody(which includescodeandrequest_id).
Webhooks
Stay informed about key events in your mailbox — automatically.
Webhooks let you get notified in real time when things happen in your mailbox, so you can automate workflows and integrate with your CRM, applications, or other systems without polling the API.
Subscribe to events like:
new-mail— a new mail item has arrivedscan-update— a scan request has completedopen-update— an open (unpackaging) request has completedshipment-update— a shipment's status has changed
Every payload is signed with an HMAC-SHA256 signature so you can verify it's genuinely from US Global Mail. You can manage webhooks from Settings → Developer → Webhooks, or create, update, and delete them via the API.
MCP Server
Let a coding agent manage a US Global Mail mailbox on your behalf.
The USGM MCP server lets an AI coding agent — Claude Code, Cursor, VS Code, Windsurf, Cline, and others — manage a mailbox for you: read and organize scanned mail, manage folders, request scans, manage shipping and deposit addresses and bank accounts, view shipment requests, and read the account profile and virtual mailing address.
It's a thin, stateless HTTP wrapper around the US Global Mail API gateway — every tool call is forwarded to the gateway with your API key, so the gateway enforces auth, rate limits, and audit exactly as it does for direct REST calls. Nothing new to trust.