Core concepts

Authentication

Every request is authenticated with an API key sent as a bearer token.

The API authenticates requests with an API key. Send it in the Authorization header as a bearer token on every request:

$curl https://api.usglobalmail.com/v1/mails \
>  -H "Authorization: Bearer usgmk_live_…"

A missing or invalid key returns 401 Unauthorized as application/problem+json.

Key types

PrefixEnvironmentBase URL
usgmk_live_…Productionhttps://api.usglobalmail.com
usgmk_test_…Sandboxhttps://api-sandbox.usglobalmail.com

A live key only works against production; a test key only works against the sandbox. Sending a test key to production (or vice-versa) is rejected as 401.

Managing keys

Create, view, and rotate keys in your USGM dashboard. Each key acts on one customer’s mailbox — everything the key can do runs as that customer.

Store keys in environment variables or a secrets manager, never in source control or client-side code. If a key leaks, rotate it immediately — a rotated key stops working right away.

Best practices

  • One key per integration. Use a dedicated key per app or agent so you can rotate one without disrupting the others.
  • Prefer the sandbox while building. Point at https://api-sandbox.usglobalmail.com with a usgmk_test_… key until you’re ready to handle live mail.
  • Rotate on a schedule and on any suspected exposure.