Autenticação

#Chave de API

Toda requisição precisa de uma chave de API no cabeçalho Authorization, no formato Bearer:

Authorization: Bearer ps_4Fq9xLmT2vKp8sWd1Yc5Hf3Lz9Ag6Ej0Qm8rBnX

As chaves começam com ps_. Crie em Chaves de API no painel, ou pela API com POST /api-keys. O token completo aparece uma única vez, na criação: a Postal guarda só o hash e os primeiros caracteres (token_start), para você reconhecer a chave na lista.

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);

#Permissões

Criar chaves só de envio ou restritas a um domínio depende do plano (restricted_api_keys); o número de chaves também (api_keys). Veja Limites.

Use chaves só de envio nos sistemas que apenas disparam e-mails ou eventos (o checkout, o WordPress, o ERP) e reserve as de acesso total para automações de infraestrutura. Se uma chave de envio vazar, ela não muda sua configuração nem lê seus contatos, domínios ou os e-mails de outras chaves: só vê o que ela mesma enviou e os limites do plano.

#Erros de autenticação

#Idioma das mensagens e origem das mudanças

Duas escolhas opcionais por requisição:

• Accept-Language: pt-BR (ou en) escolhe o idioma da message dos erros e dos outros textos que a API escreve para a sua requisição (veja a tabela abaixo). Sem o cabeçalho, vem em inglês. O name é sempre o mesmo.
• X-Postal-Source: erp dá um rótulo às mudanças que a chave faz nos contatos. O rótulo aparece em source nos webhooks de contato e em last_change_source do contato, e permite que um webhook ignore o que o próprio sistema fez.

O idioma de cada texto que a Postal escreve depende de para quem ele é:

#Boas práticas

• Guarde a chave em variável de ambiente ou num cofre de segredos, nunca no código. Não use a chave no navegador ou em apps: qualquer pessoa poderia copiá-la. Chame a API a partir do seu servidor.
• Use uma chave por sistema e por ambiente. Assim, dá para revogar uma sem derrubar as outras e ver nos logs quem fez cada requisição.
• Se uma chave vazar, exclua-a na hora (DELETE /api-keys/{id}) e crie outra.
• Para dar a um assistente de IA acesso à conta, prefira o OAuth do servidor MCP, que limita o acesso a um time e a escopos e se revoga sem trocar chave.