Documentação

Comece com segurança no Postline

Verificação de domínio, acesso à API, envio em sandbox, suppression e eventos de entrega.

Atualizado em 24 de julho de 2026Abrir referência da API

Checklist de produção

Verifique a propriedade do domínio From.
Publique o registro DKIM fornecido e autorize a infraestrutura de return-path através do SPF.
Configure o alinhamento DMARC e analise o resultado antes de habilitar o envio em produção.
Use uma chave de teste com escopo limitado em sandbox e uma chave live separada em produção.
Processe os webhooks de bounce e complaint de forma idempotente e respeite as decisões de suppression.

POST /v1/emails

Solicitação / Resposta

curl --request POST 'https://api.srs-postline.com/v1/emails' \
  --header 'Authorization: Bearer srs_live_...' \
  --header 'Idempotency-Key: order_4821' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "Postline <info@example.com>",
    "to": ["user@example.net"],
    "subject": "Your order is ready",
    "html": "<p>Order #4821 is ready.</p>",
    "text": "Order #4821 is ready."
  }'

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "msg_01JPOSTLINEEXAMPLE",
  "status": "queued",
  "created_at": "2026-08-22T12:00:00Z"
}

Parâmetros de entrada

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`Authorization`	`header · string`	Sim	Chave de API com escopo emitida pelo painel como token Bearer.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	Não	Identificador estável para um envio lógico; altamente recomendado.	`order_4821`
`from`	`string`	Sim	Nome e endereço do remetente em um domínio verificado.	`Postline <info@example.com>`
`to`	`string[]`	Sim	De um a 100 endereços de e-mail de destinatários.	`["user@example.net"]`
`subject`	`string`	Sim	Assunto da mensagem.	`Seu pedido está pronto`
`html`	`string`	Não	Corpo HTML. É obrigatório enviar html ou text.	`<p>…</p>`
`text`	`string`	Não	Corpo em texto simples. É obrigatório enviar text ou html.	`Pedido #4821…`

Códigos de resposta

Status	HTTP	Descrição
`202`	Accepted	A mensagem entrou na fila; isso ainda não significa entrega na caixa de entrada.
`400`	Bad Request	JSON inválido ou campos não compatíveis.
`401`	Unauthorized	A chave de API é inválida, expirou ou foi revogada.
`403`	Forbidden	Falta o scope ou o domínio do remetente não está verificado.
`422`	Unprocessable Entity	O destinatário está na lista de supressão.
`429`	Too Many Requests	O limite de solicitações do projeto foi excedido.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "recipient suppressed"
}

Terminologia de autenticação

O Postline assina as mensagens com DKIM. O SPF é uma política de autorização publicada no DNS. O DMARC avalia o alinhamento entre o domínio From visível e uma identidade SPF ou DKIM autenticada; SPF e DMARC não funcionam como assinaturas da mensagem.

O TLS protege os dados em trânsito entre os saltos compatíveis. O e-mail comum não possui criptografia de ponta a ponta, e o provedor do destinatário pode processar o conteúdo da mensagem.

Resultados de entrega

A aceitação de uma mensagem pelo servidor do destinatário não comprova a entrega na caixa de entrada. Trate accepted, deferred, hard bounce, soft bounce, complaint, suppressed, spam placement e inbox placement como resultados distintos.

Modelo de acesso atual

As chaves atuais usam srs_live_. Antes de verificar o domínio From, o remetente sandbox compartilhado só envia a membros do projeto. Depois valem cotas, suppression, limites de destinatários e controles de abuso. 202 significa enfileirado, não entregue.

Recursos de integração

Use o guia prático para pessoas e agentes de IA; o OpenAPI é a fonte de verdade dos campos.