Enviar uma mensagem
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>"}'const resposta = await fetch("https://api.iporto.com.br/api/external/v1/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.IPORTO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "to": [ ], "subject": "Seu pedido 1234", "html": "<p>Seu pedido 1234 foi confirmado.</p>" }),});
console.log(await resposta.json());$client = new \GuzzleHttp\Client();
$resposta = $client->post('https://api.iporto.com.br/api/external/v1/messages', [ 'headers' => ['Authorization' => 'Bearer '.getenv('IPORTO_API_KEY')], 'json' => ['from' => 'Loja <[email protected]>', 'to' => ['[email protected]'], 'subject' => 'Seu pedido 1234', 'html' => '<p>Seu pedido 1234 foi confirmado.</p>'],]);
print_r(json_decode((string) $resposta->getBody(), true));import osimport requests
url = 'https://api.iporto.com.br/api/external/v1/messages'headers = {'Authorization': 'Bearer ' + os.environ['IPORTO_API_KEY']}
resposta = requests.post(url, headers=headers, json={"from":"Loja <[email protected]>","to":["[email protected]"],"subject":"Seu pedido 1234","html":"<p>Seu pedido 1234 foi confirmado.</p>"})
print(resposta.json())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.
Authorizations
Seção intitulada “Authorizations”Parameters
Seção intitulada “Parameters”Header Parameters
Seção intitulada “Header Parameters”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.
Request Bodyrequired
Seção intitulada “Request Bodyrequired”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
Pode ser omitido: email é o padrão.
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.
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.
Os destinatários. Sempre uma lista, mesmo com um só.
Cópia oculta. Não aparece no cabeçalho que os outros destinatários recebem.
Para onde vai a resposta, quando é diferente do from.
O assunto. Sem quebra de linha — ela encerraria o cabeçalho e o resto do texto entraria na mensagem como se fosse outro campo.
O corpo em HTML. Os links saem exatamente como você escreveu, a não ser que você peça medição em tracking.
O corpo em texto puro. Sozinho, é a mensagem; junto com html, é a alternativa para quem não exibe HTML.
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
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.
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
Acrescenta uma imagem de rastreamento (o pixel) ao fim do html.
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.
Anexos. Cada um traz content (base64) ou url pública — nunca os dois. Somados, no máximo 10 MB.
object
O nome que o destinatário vê. Sem barra e sem quebra de linha.
O tipo do arquivo. Omitido, usamos o que o servidor informar.
O arquivo em base64.
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.
Um SMS. O canal é liberado por conta: se o seu não estiver, o envio é aceito e não sai. Fale com o suporte antes de integrar.
⚠️ channel é obrigatório aqui — sem ele a mensagem é lida como e-mail, e os campos de e-mail passam a ser exigidos.
object
Só dígitos, com DDI e DDD, sem +, espaço ou pontuação.
O texto da mensagem.
Responses
Seção intitulada “Responses”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.
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
object
object
object
object
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" }}Headers
Seção intitulada “Headers”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.
object
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.
object
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.
object
Examplegenerated
{ "error": "example"}Headers
Seção intitulada “Headers”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.
object
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.
object
Examplegenerated
{ "error": "example"}Passou de 8.000 envios por minuto nesta conta. O cabeçalho Retry-After diz quantos segundos esperar.
object
Examplegenerated
{ "error": "example"}