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.

2026-10-13Baixar OpenAPI 3.1

Autenticação

Envie uma chave srs_live_ com escopo emitida pelo painel como token Bearer. Cada chave tem seus próprios scopes (emails:send, webhooks:write …); chaves revogadas ou expiradas são rejeitadas com 401.

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	Endereços dos destinatários; to + cc + bcc não podem passar de 100 no total.	`["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…`
`cc / bcc`	`string[]`	Não	Cópia e cópia oculta (contam no limite de 100).	`["team@example.com"]`
`reply_to`	`string[]`	Não	Até 10 endereços de resposta.	`["support@example.com"]`
`send_at`	`string · date-time`	Não	Agenda o envio em até 30 dias (RFC 3339).	`2026-11-06T09:00:00Z`
`tags`	`object`	Não	Até 20 tags chave/valor.	`{"type":"receipt"}`
`headers`	`object`	Não	Até 8: In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post.	`{"References":"<…>"}`
`template / variables`	`string / object`	Não	ID de modelo publicado; assunto e corpo a partir de variables.	`"order-ready"`

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

POST/v1/emails/batchaté 100 mensagens por solicitação

GET/v1/emailslista mensagens recentes

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

DELETE/v1/emails/{id}/schedulecancela um envio agendado

GET/POST/v1/domainslista ou adiciona domínios de envio

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

POST/v1/suppressionssuprime um destinatário

GET/DELETE/v1/suppressions/{email}consulta ou remove uma supressão

GET/POST/v1/webhookslista ou cria endpoints de webhook

DELETE/v1/webhooks/{id}exclui um endpoint

GET/v1/webhooks/{id}/deliveriesregistro de tentativas de entrega

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replayreenvia uma entrega

GET/POST/v1/templateslista ou cria modelos

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

Limites atuais do serviço

A API REST rejeita anexos. Aceita apenas os cabeçalhos personalizados In-Reply-To, References, List-Unsubscribe e List-Unsubscribe-Post (até 8). O correio hospedado é separado: o cliente web aceita 20 anexos, 25 MiB no total; o cliente desktop publicado limita o envio a 10 MiB. HTTP 202 e email.accepted indicam aceitação para processamento; a aceitação SMTP não garante entrega nem chegada à caixa de entrada.

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.