Começando

Autenticação

Toda requisição usa uma chave de API no cabeçalho Authorization. As chaves podem ter acesso total ou só de envio, e ser restritas a um domínio.

#Chave de API

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

Cabeçalho

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.

GET /domains

cURL

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

Node.js

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

const data = await response.json();

Python

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

PHP

$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

Permissão	O que pode fazer
`full_access` Acesso total	Toda a API: envio, domínios, templates, webhooks, logs, chaves…
`sending_access` Só envio	Apenas `POST /emails`, `POST /emails/batch`, `POST /events` e o SMTP. Pode ser restrita a um domínio (`domain_id`): aí só envia com remetentes desse domínio.

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 lê seus dados nem muda sua configuração.

#Erros de autenticação

Status	Nome	Quando acontece
`401`	`missing_api_key`	Faltou o cabeçalho `Authorization`.
`403`	`invalid_api_key`	A chave não existe, foi excluída ou não começa com `ps_`.
`401`	`restricted_api_key`	Uma chave só de envio tentou usar outro endpoint.
`403`	`restricted_api_key`	Uma chave restrita a um domínio tentou enviar de outro domínio.

#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.