Authentication and API keys

Kinds of key

Every request authenticates with an API key. Only an Owner or Admin on your team can create or revoke one. Each kind of key opens only the endpoints below; any other endpoint refuses it with the same 401 it gives a wrong or revoked key.

Give an AI client only an integration key or a Formulas only key, never a Full access key: a Full access key sends recipients, which mails cards and charges your team.

Send a key

• The Dynamic Audience API (POST /api/v1/recipients) takes the key in the Authorization: Bearer header (preferred), in an X-API-Key header, or in an api_key field in the JSON body for senders that cannot set headers.
• The Integrations push API and the MCP servers take the key in the Authorization: Bearer header only.
• Never put a key in a URL or a query string.

Keep keys in your own systems: an environment variable or a secrets manager, never your source code. The samples in these docs read POSTAGED_SEND_KEY for a Full access key, POSTAGED_API_KEY for an integration key, and POSTAGED_FORMULAS_KEY for a Formulas only key.

Rotate a key

1. Create the new key.
2. Switch your system to it.
3. Revoke the old key.

A team holds at most 10 active Full access and Formulas only keys, and each integration at most 2 active keys of its own. Integration keys don't count toward the team's 10. Revoke a key you no longer use to make room for a new one.

Revoke a key

Revocation is immediate. Revoke a Full access or Formulas only key in Settings > API & Webhooks, and an integration key on that integration's page. As the revoke dialog says: "Any system using this key will stop working immediately. Mail already queued will still send."