Migrar o envio de e-mail de outro provedor
Se o seu sistema já envia e-mail por um provedor, a troca é de nomes de campo: a forma
do pedido é a mesma — um POST com JSON, autenticado por chave no cabeçalho.
Esta página é a tabela de equivalência. O caminho completo, com a conta de envio e o que fazer depois do envio, está em Referência → Mensagens.
O formato, lado a lado
Seção intitulada “O formato, lado a lado”| Endereço | POST https://api.iporto.com.br/api/external/v1/messages |
| Autenticação | Authorization: Bearer <sua chave> |
| Corpo | JSON |
| Resposta | 202 com a mensagem aceita |
O mais parecido: os nomes quase coincidem.
| Resend | iPORTO | Nota |
|---|---|---|
from |
from |
igual, inclusive Nome <endereco> |
to |
to |
sempre lista aqui, mesmo com um destinatário |
subject |
subject |
igual |
html · text |
html · text |
igual |
cc · bcc · reply_to |
cc · bcc · reply_to |
sempre listas aqui |
headers |
headers |
igual, objeto chave-valor |
attachments[].filename |
attachments[].filename |
igual |
attachments[].content |
attachments[].content |
base64 nos dois |
attachments[].path |
attachments[].url |
só o nome muda |
tags[{name, value}] |
tags[] |
aqui é lista de texto, sem par nome-valor |
scheduled_at |
— | não há agendamento |
id da resposta |
message.tracking_code |
ver A resposta |
Antes:
{ "subject": "Seu pedido 1234", "html": "<p>Confirmado.</p>", "tags": [{ "name": "tipo", "value": "transacional" }]}Depois:
{ "subject": "Seu pedido 1234", "html": "<p>Confirmado.</p>", "tags": ["tipo:transacional"]}SendGrid
Seção intitulada “SendGrid”A diferença grande é o personalizations: aqui o pedido é plano.
| SendGrid | iPORTO | Nota |
|---|---|---|
from.email + from.name |
from |
um campo só: Nome <endereco> |
personalizations[0].to[].email |
to |
lista de endereços, sem personalizations |
personalizations[0].cc · bcc |
cc · bcc |
no nível de cima |
subject |
subject |
igual |
content[{type: "text/html"}].value |
html |
campo direto |
content[{type: "text/plain"}].value |
text |
campo direto |
reply_to.email |
reply_to |
lista |
headers |
headers |
igual |
attachments[].content · filename · type |
attachments[].content · filename · content_type |
type vira content_type |
categories[] |
tags[] |
igual na prática |
custom_args |
tags[] |
não há campo de metadado livre; o que precisa voltar vira etiqueta |
send_at |
— | não há agendamento |
template_id + dynamic_template_data |
— | não há template; monte o HTML no seu lado |
tracking_settings.open_tracking · click_tracking |
tracking.opens · tracking.clicks |
booleanos; exigem o rastreamento do domínio verificado — ver Medição de abertura e clique |
X-Message-Id do cabeçalho |
message.tracking_code |
ver A resposta |
Antes:
{ "subject": "Seu pedido 1234", "content": [{ "type": "text/html", "value": "<p>Confirmado.</p>" }], "categories": ["transacional"]}Depois:
{ "subject": "Seu pedido 1234", "html": "<p>Confirmado.</p>", "tags": ["transacional"]}Amazon SES
Seção intitulada “Amazon SES”| Amazon SES (API v2) | iPORTO | Nota |
|---|---|---|
FromEmailAddress |
from |
igual, aceita Nome <endereco> |
Destination.ToAddresses |
to |
igual |
Destination.CcAddresses · BccAddresses |
cc · bcc |
igual |
ReplyToAddresses |
reply_to |
igual |
Content.Simple.Subject.Data |
subject |
campo direto |
Content.Simple.Body.Html.Data |
html |
campo direto |
Content.Simple.Body.Text.Data |
text |
campo direto |
Content.Raw.Data (MIME montado à mão) |
attachments[] |
não é preciso montar MIME: anexo é campo |
EmailTags[{Name, Value}] |
tags[] |
lista de texto |
ConfigurationSetName |
— | não há conjunto de configuração |
MessageId da resposta |
message.tracking_code |
ver A resposta |
Antes:
{ "Content": { "Simple": { "Subject": { "Data": "Seu pedido 1234" }, "Body": { "Html": { "Data": "<p>Confirmado.</p>" } } } }}Depois:
{ "subject": "Seu pedido 1234", "html": "<p>Confirmado.</p>"}Postmark
Seção intitulada “Postmark”| Postmark | iPORTO | Nota |
|---|---|---|
From |
from |
igual |
To (texto, separado por vírgula) |
to |
lista, não texto com vírgula |
Cc · Bcc |
cc · bcc |
listas |
ReplyTo |
reply_to |
lista |
Subject |
subject |
igual |
HtmlBody |
html |
só o nome muda |
TextBody |
text |
só o nome muda |
Headers[{Name, Value}] |
headers |
aqui é objeto chave-valor |
Attachments[{Name, Content, ContentType}] |
attachments[{filename, content, content_type}] |
só os nomes mudam |
Tag (uma só) |
tags[] |
aqui são até 10 |
Metadata |
tags[] |
não há campo de metadado livre |
TrackOpens · TrackLinks |
tracking.opens · tracking.clicks |
booleanos; o clique vale só para o HTML — ver Medição de abertura e clique |
MessageStream |
— | não há stream; a separação é por etiqueta |
MessageID da resposta |
message.tracking_code |
ver A resposta |
Mailgun
Seção intitulada “Mailgun”| Mailgun | iPORTO | Nota |
|---|---|---|
corpo multipart ou x-www-form-urlencoded |
JSON | é a mudança de forma |
from |
from |
igual |
to (repetido, ou com vírgula) |
to |
lista JSON |
cc · bcc |
cc · bcc |
listas |
subject |
subject |
igual |
html · text |
html · text |
igual |
h:Reply-To |
reply_to |
campo próprio |
h:X-Qualquer-Coisa |
headers |
objeto, sem o prefixo h: |
attachment (arquivo no multipart) |
attachments[] |
base64 em content, ou url |
o:tag (repetido) |
tags[] |
lista |
v:minha-var |
tags[] |
não há variável de usuário |
o:deliverytime |
— | não há agendamento |
o:tracking-opens · o:tracking-clicks |
tracking.opens · tracking.clicks |
booleanos JSON; não há o:tracking geral — ver Medição de abertura e clique |
id da resposta |
message.tracking_code |
ver A resposta |
Antes (form-encoded):
curl -X POST https://api.mailgun.net/v3/cliente.com.br/messages \ -u "api:$MAILGUN_KEY" \ -F subject="Seu pedido 1234" \ -F html="<p>Confirmado.</p>" \ -F o:tag=transacionalDepois:
curl -X POST https://api.iporto.com.br/api/external/v1/messages \ -H "Authorization: Bearer $IPORTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "Loja <[email protected]>", "to": ["[email protected]"], "subject": "Seu pedido 1234", "html": "<p>Confirmado.</p>", "tags": ["transacional"] }'A resposta
Seção intitulada “A resposta”Todo provedor devolve um identificador. Aqui ele se chama message.tracking_code, e é o que
você guarda no lugar do id, do MessageId ou do X-Message-Id.
{ "object": "message", "channel": "email", "message": { "tracking_code": "3f2a7c18-9d4e-4b6a-8c1f-5e2d7a0b3f49", "sent_at": null }, "delivery": { "status": "msg:yes:queue", "bounce": null }}Duas diferenças que mexem no seu código:
- O status é 202, não 200. A mensagem foi aceita e sai em seguida. Se o seu código compara com 200, passa a comparar com 202 — ou aceitar a faixa 2xx.
- A resposta já tem a forma do estado da mensagem. Os mesmos campos
delivery.statusedelivery.bounceque você vai ler depois na consulta já vêm aqui, no estado aceito. Não há um segundo formato para aprender.
O webhook
Seção intitulada “O webhook”Se você usa webhook no provedor atual, a troca é de formato de evento, e o ganho é que o corpo do evento é idêntico ao que a consulta devolve — um parser serve para os dois.
Os eventos, o corpo de cada um e como verificar a assinatura estão em Receber eventos. A configuração é no painel, não por API.
Medição de abertura e clique
Seção intitulada “Medição de abertura e clique”Desligada por padrão: sem o campo tracking, os seus links saem
intactos e nenhum pixel é inserido. Para medir, peça no envio:
"tracking": { "opens": true, "clicks": true }clickstroca cada linkhttp/httpsnohrefde um link —<a>,<area>ou o botão VML do Outlook —, entre aspas duplas ou simples, no HTML por um endereço de redirecionamento no seu domínio de rastreio, e acrescentautm_source,utm_mediumeutm_termao endereço final, antes do#;opensacrescenta uma imagem de rastreamento (o pixel) ao fim do HTML.
Cada abertura e cada clique chega pelo webhook, como
email.opened e email.clicked.
O que não tem equivalente
Seção intitulada “O que não tem equivalente”Vale conferir antes de começar, porque é o que faz uma migração parar no meio:
| O que você usa hoje | Aqui |
|---|---|
| Template no provedor, com variáveis | Não existe. O HTML vai pronto no pedido — monte no seu lado, que é onde os dados estão |
Agendamento (send_at, scheduled_at, o:deliverytime) |
Não existe. O envio é imediato; agende no seu lado |
| Conteúdo diferente por destinatário numa chamada | Um pedido é uma mensagem. Para conteúdos diferentes, uma chamada cada |
Metadado livre (custom_args, Metadata, v:) |
Use tags, até 10 por mensagem |
Testar antes de trocar
Seção intitulada “Testar antes de trocar”Mande um envio para um endereço seu e confira três coisas: a mensagem chegou, o remetente
aparece como você espera, e a consulta pelo tracking_code responde. Depois disso, a troca
no seu código é de nomes de campo.
O caminho completo está em Referência → Mensagens.
