API authentication and API keys

#API key

Every request needs an API key in the Authorization header, using the Bearer scheme:

Authorization: Bearer ps_4Fq9xLmT2vKp8sWd1Yc5Hf3Lz9Ag6Ej0Qm8rBnX

Keys start with ps_. Create one under API keys in the dashboard, or through the API with POST /api-keys. The full token is shown only once, when you create it: Postal stores just the hash and the first characters (token_start), so you can recognize the key in the list.

curl https://api.postal.so/domains \
  -H "Authorization: Bearer $POSTAL_API_KEY"

const response = await fetch('https://api.postal.so/domains', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.postal.so/domains",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('domains', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

#Permissions

Creating sending-only or domain-restricted keys depends on the plan (restricted_api_keys), and so does the number of keys (api_keys). See Limits.

Use sending-only keys in systems that just trigger emails or events (the checkout, WordPress, the ERP) and keep full-access keys for infrastructure automation. If a sending-only key leaks, it cannot change your settings or read your contacts, domains or the emails of other keys: it only sees what it sent itself and the plan limits.

#Authentication errors

#Message language and source of changes

Two optional choices per request:

• Accept-Language: pt-BR (or en) picks the language of the message in errors and of the other texts the API writes for your request (see the table below). Without the header it comes in English. The name is always the same.
• X-Postal-Source: erp labels the changes the key makes to contacts. The label appears in source in the contact webhooks and in the contact's last_change_source, and lets a webhook skip what your own system did.

The language of each text Postal writes depends on who it is for:

#Best practices

• Keep the key in an environment variable or a secrets vault, never in code. Do not use the key in a browser or a mobile app: anyone could copy it. Call the API from your server.
• Use one key per system and per environment. That way you can revoke one without breaking the others and see in the logs who made each request.
• If a key leaks, delete it right away (DELETE /api-keys/{id}) and create another.
• To give an AI assistant access to your account, prefer OAuth on the MCP server, which limits access to one team and to scopes and can be revoked without changing a key.