Integração com IA

Configure o envio de e-mails para agentes de IA

Um caminho legível por máquina para agentes de codificação e assistentes que precisam adicionar e-mail transacional ao projeto de terceiros — o que chamar, em que ordem e quais verificações executar antes de cada envio.

Atualizado em 24 de julho de 2026Baixar OpenAPI 3.1

Antes de escrever qualquer código

Peça ao usuário uma chave de API do projeto, ou peça que ele crie uma chave de sandbox em https://app.srs-postline.com/pt/login — nunca invente, adivinhe ou reutilize uma chave de outro projeto.
Coloque a chave em uma variável de ambiente do lado do servidor. Não a coloque em código de frontend, em um pacote de aplicativo móvel, em um repositório público ou em um arquivo .env versionado.
Leia /llms.txt e openapi/postline.yaml antes de gerar código de requisição; não adivinhe nomes de campos ou endpoints.

Envio mínimo

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <id-estavel-por-envio-logico>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "Assunto",
  "html": "<p>Texto</p>",
  "text": "Texto"
}

Verificações a executar antes de cada envio

Sempre envie um Idempotency-Key derivado da ação que dispara o envio (ID do pedido, ID do evento) para que novas tentativas não causem envio duplicado.
Nunca coloque códigos OTP, tokens de redefinição de senha ou outros segredos em um campo que é registrado em log ou encaminhado para fora do corpo da mensagem.
Solicite o escopo de chave de API mais restrito que a tarefa exigir (emails:send é suficiente para envio; não peça domains:write ou api_keys:write a menos que a tarefa exija).
Limite os destinatários a 100 por chamada. A API atual não aceita anexos nem cabeçalhos personalizados; rejeite o arquivo ou compartilhe um link sem afirmar que ele foi anexado.
Não repita silenciosamente respostas 4xx. Somente 429 e 503 são seguros para repetir, e apenas com backoff.

Trate cada código de resposta

202 — enfileirado, não entregue. Armazene o id retornado caso precise consultar o status depois.
400 — payload inválido; corrija a requisição, não repita sem alterações.
401 — chave inválida ou expirada; pare e informe o usuário, não fabrique uma nova chave.
403 — escopo ausente ou o domínio de envio ainda não foi verificado; diga ao usuário para verificar o domínio antes de continuar.
422 — destinatário está suprimido (bounce/complaint anterior); não repita o envio para esse destinatário.
429 — limitação de taxa; aguarde e tente novamente mais tarde, não fique em loop apertado.
503 — fila indisponível; tente novamente com backoff, não recorra a um transporte não oficial.

Se a tarefa incluir o recebimento de eventos

Registre um endpoint de webhook somente via HTTPS. Recalcule a assinatura você mesmo antes de confiar em qualquer payload; não pule a verificação porque uma requisição "parece interna".

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

compare com o header Postline-Signature (comparação em tempo constante)
rejeite se Postline-Timestamp estiver fora da sua janela permitida
armazene o event_id e processe cada evento exatamente uma vez

Referências legíveis por máquina

/llms.txt — índice condensado dessas regras para janelas de contexto de agentes.
/openapi/postline.yaml — esquema OpenAPI 3.1 completo de todos os endpoints.
/pt/api/ — referência da API para humanos.
/pt/webhooks/ — detalhes de assinatura e retentativa de webhooks.

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.