Referência da API

API REST de e-mail transacional

A API aceita requisições autenticadas, verifica o escopo do projeto e o estado do domínio, checa a suppression e, então, enfileira as mensagens aceitas.

Atualizado em 24 de julho de 2026Baixar OpenAPI 3.1

Autenticação

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"
}

Enviar um e-mail

POST /v1/emails
Authorization: Bearer srs_live_…
Idempotency-Key: reset-4821
Content-Type: application/json

Recursos principais

POST/v1/emailsenfileira uma mensagem

GET/v1/emails/{id}consulta o estado da mensagem

POST/v1/domainsadiciona um domínio de envio

POST/v1/domains/{id}/verifyexecuta as verificações de DNS

GET/POST/DELETE/v1/suppressionsgerencia destinatários suprimidos

GET/POST/DELETE/v1/webhooksgerencia endpoints de eventos

Modelo de resposta

202 significa enfileirado, não entregue na caixa de entrada. 403 pode indicar escopo ausente ou domínio não verificado. 422 bloqueia um destinatário suprimido. 429 indica limitação de taxa (rate limiting).

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.