Pular para o conteúdo

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.

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:

{
"from": "Loja <[email protected]>",
"subject": "Seu pedido 1234",
"html": "<p>Confirmado.</p>",
"tags": [{ "name": "tipo", "value": "transacional" }]
}

Depois:

{
"from": "Loja <[email protected]>",
"to": ["[email protected]"],
"subject": "Seu pedido 1234",
"html": "<p>Confirmado.</p>",
"tags": ["tipo:transacional"]
}

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:

{
"personalizations": [{ "to": [{ "email": "[email protected]" }] }],
"from": { "email": "[email protected]", "name": "Loja" },
"subject": "Seu pedido 1234",
"content": [{ "type": "text/html", "value": "<p>Confirmado.</p>" }],
"categories": ["transacional"]
}

Depois:

{
"from": "Loja <[email protected]>",
"to": ["[email protected]"],
"subject": "Seu pedido 1234",
"html": "<p>Confirmado.</p>",
"tags": ["transacional"]
}
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:

{
"FromEmailAddress": "[email protected]",
"Destination": { "ToAddresses": ["[email protected]"] },
"Content": {
"Simple": {
"Subject": { "Data": "Seu pedido 1234" },
"Body": { "Html": { "Data": "<p>Confirmado.</p>" } }
}
}
}

Depois:

{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Seu pedido 1234",
"html": "<p>Confirmado.</p>"
}
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 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):

Janela do terminal
curl -X POST https://api.mailgun.net/v3/cliente.com.br/messages \
-u "api:$MAILGUN_KEY" \
-F from="Loja <[email protected]>" \
-F subject="Seu pedido 1234" \
-F html="<p>Confirmado.</p>" \
-F o:tag=transacional

Depois:

Janela do terminal
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"]
}'

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.status e delivery.bounce que você vai ler depois na consulta já vêm aqui, no estado aceito. Não há um segundo formato para aprender.

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.

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 }
  • clicks troca cada link http/https no href de 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 acrescenta utm_source, utm_medium e utm_term ao endereço final, antes do #;
  • opens acrescenta uma imagem de rastreamento (o pixel) ao fim do HTML.

Cada abertura e cada clique chega pelo webhook, como email.opened e email.clicked.

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

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.