# US Global Mail API Documentation

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

## Instructions for AI Agents

- For clean Markdown of any page, append `.md` to the page URL
- For section-specific indexes, append `/llms.txt` to any section URL
- For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server

## Docs

- [US Global Mail API](https://docs.usglobalmail.com/guides/getting-started/introduction.md): Official documentation for the USGM API — REST endpoints, SDKs (TypeScript, Python, PHP, Go), an MCP server, and guides for your US Global Mail mailbox.
- [Quickstart](https://docs.usglobalmail.com/guides/getting-started/quickstart.md): Make your first authenticated request in a couple of minutes.
- [Sandbox](https://docs.usglobalmail.com/guides/getting-started/sandbox.md): Simulate the warehouse operator actions you can't trigger yourself, so you can test your integration end-to-end while you build.
- [Authentication](https://docs.usglobalmail.com/guides/core-concepts/authentication.md): Every request is authenticated with an API key sent as a bearer token.
- [Pagination](https://docs.usglobalmail.com/guides/core-concepts/pagination.md): List endpoints return a page of results and an opaque cursor for the next page.
- [Errors](https://docs.usglobalmail.com/guides/core-concepts/errors.md): Every non-2xx response is an RFC 9457 problem+json document.
- [Rate limits](https://docs.usglobalmail.com/guides/core-concepts/rate-limits.md): Requests are throttled at the edge, keyed by API key.
- [Webhooks](https://docs.usglobalmail.com/guides/core-concepts/webhooks.md): Get a callback the moment mail arrives — or a scan, open request, or shipment changes — instead of polling.
- [System status](https://docs.usglobalmail.com/guides/core-concepts/system-status.md): Check whether the USGM API, MCP server, USGM Core or other system modules are operating normally.
- [Resource models](https://docs.usglobalmail.com/guides/core-concepts/resource-models.md): The objects the API returns, and how they relate.
- [Problem types](https://docs.usglobalmail.com/api/problems/overview.md): Every error the API can return, by RFC 9457 problem type.
- [Bad request](https://docs.usglobalmail.com/api/problems/bad_request.md): HTTP 400 — The request was malformed.
- [Unauthorized](https://docs.usglobalmail.com/api/problems/unauthorized.md): HTTP 401 — Authentication is required or the API key is invalid.
- [Forbidden](https://docs.usglobalmail.com/api/problems/forbidden.md): HTTP 403 — You are not permitted to perform this action.
- [Not found](https://docs.usglobalmail.com/api/problems/not_found.md): HTTP 404 — The requested resource was not found.
- [Method not allowed](https://docs.usglobalmail.com/api/problems/method_not_allowed.md): HTTP 405 — The HTTP method is not allowed here.
- [Conflict](https://docs.usglobalmail.com/api/problems/conflict.md): HTTP 409 — The request conflicts with the current state of the resource.
- [Unsupported media type](https://docs.usglobalmail.com/api/problems/unsupported_media_type.md): HTTP 415 — The request media type is not supported.
- [Validation error](https://docs.usglobalmail.com/api/problems/validation_error.md): HTTP 422 — Your request parameters did not validate.
- [Rate limited](https://docs.usglobalmail.com/api/problems/rate_limited.md): HTTP 429 — Rate limit exceeded.
- [Internal error](https://docs.usglobalmail.com/api/problems/internal_error.md): HTTP 500 — An unexpected error occurred.
- [Bad gateway](https://docs.usglobalmail.com/api/problems/bad_gateway.md): HTTP 502 — An upstream service returned an invalid response.
- [Service unavailable](https://docs.usglobalmail.com/api/problems/service_unavailable.md): HTTP 503 — The service is temporarily unavailable.
- [Gateway timeout](https://docs.usglobalmail.com/api/problems/gateway_timeout.md): HTTP 504 — An upstream service timed out.
- [SDKs](https://docs.usglobalmail.com/sdks/client-libraries/overview.md): Official client libraries for TypeScript, Python, PHP, and Go.
- [TypeScript SDK](https://docs.usglobalmail.com/sdks/client-libraries/type-script.md): A fully-typed client for Node.js and the browser.
- [Python SDK](https://docs.usglobalmail.com/sdks/client-libraries/python.md): A fully-typed client with sync and async support.
- [PHP SDK](https://docs.usglobalmail.com/sdks/client-libraries/php.md): A fully-typed client for modern PHP.
- [Go SDK](https://docs.usglobalmail.com/sdks/client-libraries/go.md): A fully-typed, idiomatic client for Go.
- [MCP server](https://docs.usglobalmail.com/mcp/mcp-server.md): Let a coding agent manage a US Global Mail mailbox on the customer's behalf.
- [Changelog](https://docs.usglobalmail.com/changelog/llms.txt)

## API Docs

- API Reference > Mails [List mail items](https://docs.usglobalmail.com/api/api-reference/mails/list.md)
- API Reference > Mails [Get single mail](https://docs.usglobalmail.com/api/api-reference/mails/get.md)
- API Reference > Mails [Update mail item](https://docs.usglobalmail.com/api/api-reference/mails/update.md)
- API Reference > Mails [Archive mail item](https://docs.usglobalmail.com/api/api-reference/mails/archive.md)
- API Reference > Mails [Unarchive mail item](https://docs.usglobalmail.com/api/api-reference/mails/unarchive.md)
- API Reference > Mails [Discard mail item](https://docs.usglobalmail.com/api/api-reference/mails/discard.md)
- API Reference > Mails [Undiscard mail item](https://docs.usglobalmail.com/api/api-reference/mails/undiscard.md)
- API Reference > Scans [List scans](https://docs.usglobalmail.com/api/api-reference/scans/list.md)
- API Reference > Scans [Create scan request](https://docs.usglobalmail.com/api/api-reference/scans/create.md)
- API Reference > Scans [Get single scan](https://docs.usglobalmail.com/api/api-reference/scans/get.md)
- API Reference > Scans [Delete scan](https://docs.usglobalmail.com/api/api-reference/scans/delete.md)
- API Reference > Scans [Get scan file](https://docs.usglobalmail.com/api/api-reference/scans/file.md)
- API Reference > Scans [Get scan summary](https://docs.usglobalmail.com/api/api-reference/scans/summary.md)
- API Reference > Scans [Cancel scan request](https://docs.usglobalmail.com/api/api-reference/scans/cancel.md)
- API Reference > Shipments [List shipments](https://docs.usglobalmail.com/api/api-reference/shipments/list.md)
- API Reference > Shipments [Get single shipment](https://docs.usglobalmail.com/api/api-reference/shipments/get.md)
- API Reference > Folders [List folders](https://docs.usglobalmail.com/api/api-reference/folders/list.md)
- API Reference > Folders [Create folder](https://docs.usglobalmail.com/api/api-reference/folders/create.md)
- API Reference > Folders [Get single folder](https://docs.usglobalmail.com/api/api-reference/folders/get.md)
- API Reference > Folders [Delete folder](https://docs.usglobalmail.com/api/api-reference/folders/delete.md)
- API Reference > Folders [Update folder](https://docs.usglobalmail.com/api/api-reference/folders/update.md)
- API Reference > Addresses [List addresses](https://docs.usglobalmail.com/api/api-reference/addresses/list.md)
- API Reference > Addresses [Add address](https://docs.usglobalmail.com/api/api-reference/addresses/create.md)
- API Reference > Addresses [Get default](https://docs.usglobalmail.com/api/api-reference/addresses/getdefault.md)
- API Reference > Addresses [Get single address](https://docs.usglobalmail.com/api/api-reference/addresses/get.md)
- API Reference > Addresses [Delete address](https://docs.usglobalmail.com/api/api-reference/addresses/delete.md)
- API Reference > Addresses [Update address](https://docs.usglobalmail.com/api/api-reference/addresses/update.md)
- API Reference > Addresses [Set default](https://docs.usglobalmail.com/api/api-reference/addresses/setdefault.md)
- API Reference > Bank Accounts [List bank accounts](https://docs.usglobalmail.com/api/api-reference/bank-accounts/bank-accounts-list.md)
- API Reference > Bank Accounts [Add bank account](https://docs.usglobalmail.com/api/api-reference/bank-accounts/bank-accounts-create.md)
- API Reference > Bank Accounts [Get single bank account](https://docs.usglobalmail.com/api/api-reference/bank-accounts/bank-accounts-get.md)
- API Reference > Bank Accounts [Delete bank account](https://docs.usglobalmail.com/api/api-reference/bank-accounts/bank-accounts-delete.md)
- API Reference > Bank Accounts [Update bank account](https://docs.usglobalmail.com/api/api-reference/bank-accounts/bank-accounts-update.md)
- API Reference > Account [Get account](https://docs.usglobalmail.com/api/api-reference/account/get.md)
- API Reference > Account [Mailing address](https://docs.usglobalmail.com/api/api-reference/account/mailingaddress.md)
- API Reference > Sandbox [Seed mailbox](https://docs.usglobalmail.com/api/api-reference/sandbox/seed.md)
- API Reference > Sandbox [Seed mail](https://docs.usglobalmail.com/api/api-reference/sandbox/seedmail.md)
- API Reference > Sandbox [Complete scan](https://docs.usglobalmail.com/api/api-reference/sandbox/completescan.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.usglobalmail.com/openapi.json)
- [OpenAPI YAML](https://docs.usglobalmail.com/openapi.yaml)