Pular para o conteúdo

Enviar uma mensagem

POST
/messages
curl --request POST \
"https://api.iporto.com.br/api/external/v1/messages" \
--header "Authorization: Bearer $IPORTO_API_KEY" \
--header "Content-Type: application/json" \
--data '{"from":"Loja <[email protected]>","to":["[email protected]"],"subject":"Seu pedido 1234","html":"<p>Seu pedido 1234 foi confirmado.</p>"}'

Envia um e-mail ou um SMS. Um endpoint para os dois canais: channel decide, e o padrão é email.

A resposta é 202, não 200: a mensagem foi aceita, e sai em seguida pela fila. 200 diria “está entregue”, e nesse instante ela não está — quem informa a entrega é a consulta ou o webhook.

Idempotência

Mande Idempotency-Key com um valor seu, único por mensagem — um UUID, ou o número do pedido com o tipo da mensagem (pedido-1234-confirmacao). Até 255 caracteres. A comparação é exata, diferencia maiúsculas de minúsculas e vale só para a sua conta. Sem o cabeçalho, cada requisição é um envio.

Situação Resposta
primeira requisição com a chave 202
mesma chave, mesmo corpo 202 com Idempotent-Replayed: true — a mensagem original, sem novo envio
mesma chave, corpo diferente 422 — são dois pedidos distintos, e aceitar o segundo em silêncio esconderia um defeito no seu laço de retentativa
mesma chave, enquanto outra requisição idêntica é aceita 409 com Retry-After — repita, e a resposta será o 202 da original

A chave vale 7 dias a partir do aceite. Depois desse prazo ela é removida — em até alguns minutos, por uma rotina automática — e a mesma chave passa a criar uma mensagem nova.

Só o aceite registra a chave. Uma recusa — 401, 402, 413, 422, 429 — não a consome: corrija o que a resposta apontou e repita com a mesma chave.

O corpo é comparado depois de interpretado. A ordem das chaves e os espaços não importam; a ordem dos itens de uma lista e o tipo dos valores importam ("1" não é 1).

O replay traz o estado atual da mensagem: o mesmo id e o mesmo tracking_code da primeira resposta, mas delivery.status pode já ter avançado.

⚠️ Tempo esgotado ou 5xx não quer dizer que a mensagem não foi aceita. O aceite pode ter terminado depois que o seu cliente HTTP desistiu de esperar. Repita com a mesma chave e o mesmo corpo: Idempotent-Replayed: true diz que ela já existia; sem o cabeçalho, ela foi aceita agora. Sem a chave não há como distinguir os dois casos — por isso, mande-a sempre.

Limites

Corpo da requisição 16 MB
Destinatários, somando to, cc e bcc 50
html + text 2 MB
Anexos 10, 10 MB no total
headers 20
tags 10
Envios por minuto, por conta 8.000

Os endpoints antigos

Existem dois endpoints de envio anteriores a este, em /api/panel/application/delivery/.... Eles continuam funcionando e não precisam de nenhuma mudança de quem já os usa. Não têm documentação, e não recebem recurso novo. Para integração nova, use POST /messages.

Idempotency-Key
string
<= 255 characters

Um valor seu que identifica este envio. Repetir a mesma chave com o mesmo corpo devolve a mensagem original em vez de enviar outra, por 7 dias. Sem a chave, cada requisição é um envio.

Media typeapplication/json
One of: discriminator: channel

Um e-mail. É preciso html ou text; os dois juntos viram uma mensagem multipart/alternative, que é o que o leitor de e-mail espera.

object
channel

Pode ser omitido: email é o padrão.

string
default: email
Allowed values: email
from
required

O remetente. Endereço, ou Nome <endereco@dominio>. O nome é opcional e sai no cabeçalho como você escreveu.

⚠️ Qualquer endereço de um domínio de envio seu, cadastrado no painel do SMTP — não precisa ser uma conta. Domínio que não é seu, ou subdomínio não cadastrado, devolve 422: o domínio é quem carrega a reputação e a assinatura DKIM.

string
from_auth

A conta de envio que autentica a mensagem — do mesmo domínio do from. Opcional: sem ele, autentica a conta do próprio from, quando ele é uma conta, ou a conta mais antiga do domínio. Conta que não é sua, ou de outro domínio, devolve 422.

⚠️ Se a conta for apagada entre o aceite e o envio, a mensagem falha em vez de sair por outra conta: a escolha foi sua.

string format: email
to
required

Os destinatários. Sempre uma lista, mesmo com um só.

Array<string>
>= 1 items
cc
Array<string>
bcc

Cópia oculta. Não aparece no cabeçalho que os outros destinatários recebem.

Array<string>
reply_to

Para onde vai a resposta, quando é diferente do from.

Array<string>
subject
required

O assunto. Sem quebra de linha — ela encerraria o cabeçalho e o resto do texto entraria na mensagem como se fosse outro campo.

string
>= 1 characters <= 500 characters
html

O corpo em HTML. Os links saem exatamente como você escreveu, a não ser que você peça medição em tracking.

string
text

O corpo em texto puro. Sozinho, é a mensagem; junto com html, é a alternativa para quem não exibe HTML.

string
headers

Cabeçalhos seus, enviados como você escreveu — sem prefixo. O caso comum é o descadastro em um clique (RFC 8058): List-Unsubscribe com uma URL https e List-Unsubscribe-Post: List-Unsubscribe=One-Click. Os dois entram na assinatura DKIM.

⚠️ Os cabeçalhos que a mensagem já define são recusados: From, To, Cc, Bcc, Subject, Reply-To, Date, Message-ID, MIME-Version, Return-Path, Received, Sender, Bounces-To, Errors-To, Authentication-Results, e os prefixos Content-*, DKIM-*, ARC-*, X-Mailer-*, X-Original-*. Aceitar um deles deixaria dois valores no mesmo cabeçalho, e qual vale depende do servidor que ler.

object
<= 20 properties
key
additional properties
string
tags

Rótulos seus. Voltam na consulta e no webhook, e são o que permite separar “recuperação de senha” de “fatura” no seu relatório.

Array<string>
<= 10 items
tracking

Medição de abertura e clique, desligada por padrão. Os eventos chegam pelo webhook, como email.opened e email.clicked.

⚠️ Só tem efeito com o rastreamento do domínio do from verificado (CNAME track-s1). Sem ele, a mensagem é aceita e sai sem reescrita e sem medição.

object
opens

Acrescenta uma imagem de rastreamento (o pixel) ao fim do html.

boolean
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. O endereço final ganha utm_source, utm_medium e utm_term, antes do #. O text não é alterado.

boolean
attachments

Anexos. Cada um traz content (base64) ou url pública — nunca os dois. Somados, no máximo 10 MB.

Array<object>
<= 10 items
object
filename
required

O nome que o destinatário vê. Sem barra e sem quebra de linha.

string
<= 255 characters
content_type

O tipo do arquivo. Omitido, usamos o que o servidor informar.

string
<= 255 characters
content

O arquivo em base64.

string format: byte
url

Endereço público do arquivo, que buscamos na hora do envio.

⚠️ Precisa ser http ou https, e precisa resolver para um endereço público: endereço interno, localhost e faixa privada são recusados. Redirecionamento também — informe a URL final.

⚠️ Anexo que não pudermos obter não impede o envio: a mensagem sai sem ele, e o que faltou aparece em message.attachments_dropped, com o motivo. Falha passageira do seu servidor é tentada mais uma vez na hora; 404 e recusa de acesso não são tentadas de novo, porque não mudam.

string format: uri
<= 2048 characters

A mensagem foi aceita e entrou na fila de envio. Guarde o message.tracking_code: é por ele que você consulta e é ele que chega nos eventos de webhook.

Media typeapplication/json

O mesmo objeto que o webhook entrega em param.details (v1) e data (v2). Cada campo está descrito em https://docs.iporto.com.br/api/webhooks/eventos/

object
object
string
nullable
event
nullable
channel
string
nullable
message
object
id
string
nullable
tracking_code
string
nullable
message_id
string
nullable
message_id_relay
string
nullable
subject
string
nullable
body
nullable
from
string
nullable
from_visible
string
nullable
to
string
nullable
recipients
Array<string>
tags
Array<string>
smtp_domain_id
integer
smtp_account_id
integer
plan_type
string
nullable
attachments_dropped
Array
sent_at
string
nullable
delivery
object
status
string
nullable
hard_bounce
integer
soft_bounce
integer
discarded
integer
trap
integer
bounce
object
kind
string
nullable
code
string
nullable
answer
string
nullable
domain
string
nullable
recipients
Array<object>
object
email
string
nullable
domain
string
nullable
kind
string
nullable
code
string
nullable
answer
string
nullable
discard_reason
nullable
engagement
object
link
string
nullable
ip
string
nullable
user_agent
string
nullable
device
string
nullable
platform
string
nullable
referer
nullable
Examplegenerated
{
"object": "example",
"event": "example",
"channel": "example",
"message": {
"id": "example",
"tracking_code": "example",
"message_id": "example",
"message_id_relay": "example",
"subject": "example",
"body": "example",
"from": "example",
"from_visible": "example",
"to": "example",
"recipients": [
"example"
],
"tags": [
"example"
],
"smtp_domain_id": 1,
"smtp_account_id": 1,
"plan_type": "example",
"attachments_dropped": [
"example"
],
"sent_at": "example"
},
"delivery": {
"status": "example",
"hard_bounce": 1,
"soft_bounce": 1,
"discarded": 1,
"trap": 1,
"bounce": {
"kind": "example",
"code": "example",
"answer": "example",
"domain": "example"
},
"recipients": [
{
"email": "example",
"domain": "example",
"kind": "example",
"code": "example",
"answer": "example",
"discard_reason": "example"
}
]
},
"engagement": {
"link": "example",
"ip": "example",
"user_agent": "example",
"device": "example",
"platform": "example",
"referer": "example"
}
}
Idempotent-Replayed
string
Allowed values: true

Presente, com valor true, quando a requisição repetiu uma Idempotency-Key já usada. A mensagem devolvida é a original, e nada foi enviado de novo.

A chave não foi enviada, ou venceu.

Media typeapplication/json
object
error
string
Examplegenerated
{
"error": "example"
}

Sem crédito para o envio. A mensagem traz o que falta — é 402, e não 422, porque o pedido está correto.

Media typeapplication/json
object
error
string
Examplegenerated
{
"error": "example"
}

Outra requisição idêntica, com a mesma Idempotency-Key, foi aceita neste instante. Repita depois do Retry-After: a resposta será 202 com Idempotent-Replayed: true.

Media typeapplication/json
object
error
string
Examplegenerated
{
"error": "example"
}
Retry-After
integer

Segundos a esperar antes de repetir.

O corpo da requisição passou de 16 MB. A mensagem traz o teto e o tamanho recebido. É 413, e não 422, porque o pedido está correto: só é grande demais.

Media typeapplication/json
object
error
string
Examplegenerated
{
"error": "example"
}

Um campo não passou na validação, e errors diz qual — inclusive a Idempotency-Key acima do tamanho. Também é 422 quando a chave já foi usada com um corpo DIFERENTE — ver a descrição acima.

Media typeapplication/json
object
error
string
Examplegenerated
{
"error": "example"
}

Passou de 8.000 envios por minuto nesta conta. O cabeçalho Retry-After diz quantos segundos esperar.

Media typeapplication/json
object
error
string
Examplegenerated
{
"error": "example"
}