Enviar

Enviar e-mail

Um POST em /v1/messages com JSON. O corpo precisa de destinatário, assunto e pelo menos um de html ou text.

Dois caminhos para enviar

API RESTvocê está aqui

Para código que você escreve.

Devolve o id da mensagem na hora e aceita idempotência, duas coisas que o SMTP não tem.

Gateway SMTP

Para software que não é seu e só fala SMTP.

Logto, Postfix, msmtp, sendmail, ou o backend de e-mail padrão do Laravel, do Django e do WordPress.

Os dois usam a mesma chave de API, respeitam os mesmos limites do plano e aparecem no mesmo painel, com a mesma linha do tempo de eventos. O que sai por SMTP vem marcado com via=smtp.

O caminho da mensagem

Quatro partes participam de um envio, e cada uma responde por um trecho. Quando uma mensagem não chega, a primeira pergunta é em qual faixa ela parou: o que você controla, o que nós controlamos, e o que nenhum dos dois controla.

Quem responde por cada trecho

Você

Até a chamada sair do seu servidor.

Publica o DNS
Os registros que provam o domínio e assinam a mensagem. Sem eles, o envio é recusado.
Monta a chamada
Destinatário, assunto e html ou text.
Guarda a chave
Ela aparece uma vez. Perdida, cria-se outra.

JetSend

Da chamada até a AWS aceitar, e o registro do que voltar.

Valida e aceita
Confere a chave, o domínio e a lista de bloqueio. Devolve um id.
Entrega à AWS
Na região de São Paulo, com a reputação isolada por conta.
Registra o desfecho
Entregue, devolvida ou reclamada, no painel e no seu webhook.

AWS SES

Do aceite até o servidor do destinatário responder.

Faz a entrega
Conversa com o servidor do outro lado e aguarda a resposta dele.
Devolve o evento
Aceite, devolução ou reclamação, que é o que vira o seu registro.

Destinatário

Fora do alcance de todos os anteriores.

Aceita ou recusa
Caixa cheia, endereço inexistente e regra de spam própria decidem aqui.
Marca como spam
Vira reclamação, e é o evento mais caro para a reputação do seu domínio.

O caminho acima termina no destinatário. O que acontece depois, e como você fica sabendo, está em Webhooks e eventos.

Exemplo completo

shell

curl -X POST https://api.jetsend.com.br/v1/messages \  -H "Authorization: Bearer $JETSEND_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "from": "faturas@suaempresa.com.br",    "fromName": "Sua Empresa",    "to": "cliente@exemplo.com",    "replyTo": "financeiro@suaempresa.com.br",    "subject": "Sua fatura de setembro",    "html": "<p>Segue a fatura.</p>",    "text": "Segue a fatura."  }'

Campos

Campo	Tipo	Observação
`to`	string	Obrigatório. Um endereço.
`subject`	string	Obrigatório, até 998 caracteres.
`html` / `text`	string	Pelo menos um dos dois. Pode mandar os dois.
`from`	string	Precisa pertencer a um domínio verificado seu. Sem ele, usamos o remetente padrão da conta.
`fromName`	string	Nome de exibição, até 120 caracteres. Não aceita quebra de linha, aspas, barra invertida nem `< >`.
`replyTo`	string	Para onde vai a resposta, se for diferente do remetente.
`cc` / `bcc`	array	Até 50 endereços em cada.
`headers`	objeto	Cabeçalhos seus. Os reservados são recusados, ver abaixo.
`idempotencyKey`	string	Até 255 caracteres. Ver abaixo.
`enableTracking`	boolean	Ligado por padrão. `false` desliga abertura e clique nesta mensagem.

Cabeçalhos reservados

headers não aceita From, Sender, Reply-To, To, Cc, Bcc, Subject, Date, Message-ID, Return-Path, DKIM-Signature nem Received. Cada um deles tem campo próprio, ou é assinatura que o provedor precisa controlar. A rota recusa em vez de ignorar em silêncio: cabeçalho aceito e descartado é pior, porque o envio parece ter funcionado.

Não mandar duas vezes

Se a sua chamada cair na rede depois que a API já aceitou, repetir a requisição manda o e-mail de novo. O campo idempotencyKey resolve: com a mesma chave, a segunda chamada devolve a mesma mensagem em vez de criar outra.

json

{  "to": "cliente@exemplo.com",  "subject": "Pagamento confirmado",  "html": "<p>Recebemos seu pagamento.</p>",  "idempotencyKey": "pagamento-8421"}

Use um identificador do seu domínio de negócio, como o id do pedido ou do pagamento, e não um valor aleatório novo a cada tentativa.

Listar o que saiu

shell

curl "https://api.jetsend.com.br/v1/messages?limit=20" \  -H "Authorization: Bearer $JETSEND_API_KEY"

Devolve as mensagens da conta, da mais recente para a mais antiga, com id, destinatário, assunto e status.

Erros

Código	O que houve
`400`	Corpo inválido. A resposta diz qual campo e por quê.
`401`	Chave ausente, malformada ou revogada.
`402`	Cota do plano estourada, ou assinatura em aberto.
`403`	Papel sem permissão de envio, ou chave de envio chamando outra rota.
`413`	`html` ou `text` acima do teto de bytes.
`422`	O `from` não pertence a um domínio verificado seu.

Para exercitar o seu tratamento de devolução e de reclamação sem sujar a sua reputação, use os apelidos de teste.