postal
Pedir acesso
Começando

Documentação da API

Envie e receba e-mails, gerencie domínios e acompanhe cada entrega com uma API REST simples, em português e com dados no Brasil.

#Visão geral

A API da Postal é uma API REST com JSON. Você envia e-mails transacionais, recebe mensagens nas suas inboxes, gerencia domínios, templates, webhooks e a lista de supressão, cuida da audiência de marketing (contatos, segmentos, tópicos e formulários de inscrição), envia campanhas, monta automações a partir de eventos do seu produto e consulta logs e métricas, tudo com uma chave de API. Quem prefere SMTP usa a mesma chave em smtp.postal.so.

#URL base

Todas as requisições vão para:

URL base
https://api.postal.so

Use sempre HTTPS. O corpo das requisições e das respostas é JSON (Content-Type: application/json), em UTF-8. A exceção é o upload de imagens, em multipart/form-data, e as mensagens originais (/raw), em texto puro.

#Sua primeira requisição

Com uma chave em POSTAL_API_KEY e um domínio verificado, um envio é só isto:

POST /emails

cURL

curl -X POST https://api.postal.so/emails \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Loja Exemplo <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Seu pedido #10482 saiu para entrega",
    "html": "<p>O pedido <b>#10482</b> está a caminho.</p>"
  }'

Node.js

const response = await fetch('https://api.postal.so/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'Loja Exemplo <[email protected]>',
    to: ['[email protected]'],
    subject: 'Seu pedido #10482 saiu para entrega',
    html: '<p>O pedido <b>#10482</b> está a caminho.</p>',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/emails",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "from": "Loja Exemplo <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Seu pedido #10482 saiu para entrega",
        "html": "<p>O pedido <b>#10482</b> está a caminho.</p>",
    },
    timeout=10,
)

data = response.json()

PHP

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

$response = $client->post('emails', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'from' => 'Loja Exemplo <[email protected]>',
        'to' => ['[email protected]'],
        'subject' => 'Seu pedido #10482 saiu para entrega',
        'html' => '<p>O pedido <b>#10482</b> está a caminho.</p>',
    ],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b"
}

O passo a passo completo, com o cadastro do domínio e da chave, está em Primeiros passos.

#Convenções

  • IDs são UUIDs ordenados pelo tempo, como 019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b.
  • Datas vêm em ISO 8601, em UTC (2026-10-24T13:02:11.000000Z). Nas que você envia, inclua o fuso, como 2026-10-25T09:00:00-03:00.
  • Objetos trazem o campo object (email, domain, list…), que diz o que é a resposta.
  • Listas usam paginação por cursor, com has_more.
  • Exclusões respondem {"object": "…", "id": "…", "deleted": true}.
  • Erros seguem sempre o formato {"statusCode", "name", "message"}. Veja Erros.
  • As mensagens de erro e os nomes de campos são em inglês, para facilitar a busca e a integração.

#Recursos da API

A referência está agrupada por recurso. Cada endpoint traz os parâmetros, exemplos em cURL, Node.js, Python e PHP, a resposta e os erros possíveis.

#Retenção de dados

E-mails enviados (com conteúdo, anexos e eventos), entregas de webhooks e logs da API ficam guardados por 30 dias. Depois disso, são apagados automaticamente. Se você precisa de histórico mais longo, guarde os eventos que recebe pelos webhooks ou use as exportações.