Os dois formatos de corpo — v1 e v2

Os eventos podem chegar em dois formatos de corpo, e a escolha é por endereço:

	v1	v2
quem usa	todo mundo que integrou até agora	quem escolher
o corpo	`email`/`phone`, `event`, `about`, `param`	`id`, `event`, `api_version`, `created_at`, `data`
nome do evento	`msg_deliverability_yes_delivery`	`email.delivered`
os dados da mensagem	em `param.details`	em `data` — é o mesmo objeto
exige https	não	sim

O que o v2 resolve

Um lugar só para os dados. No v1 eles estão espalhados por três chaves com história própria: email é lista num evento, string noutro e nula no engajamento; about é objeto no e-mail e string vazia no SMS; param muda por evento. No v2 tudo está em data.

Nome de evento que diz o que aconteceu. email.delivered em vez de msg_deliverability_yes_delivery — e, mais importante, com o significado certo (abaixo).

Eventos que o v1 não tem, hoje três, todos de SMS.

O corpo v2

{
    "event": "email.bounced.hard",
    "api_version": "2026-10-15",
    "created_at": "2026-10-15T09:14:31-03:00",
    "data": {
        "object": "message",
        "event": {
            "type": "email.bounced.hard",
            "occurred_at": "2026-10-15T09:12:04-03:00",
            "emitted_at": "2026-10-15T09:14:31-03:00",
            "id": "01M4YQV7RC6VKAVJM5E6B4TCY8"
        },
        "channel": "email",
        "message": {
            "tracking_code": "<o seu código de rastreio>",
            "message_id": "1s9KpQ-0004Zx-2H",
            "message_id_relay": "1s9KpR-0007Bd-9K",
            "subject": "Seu pedido 1234",
            "body": null,
            "from": "[email protected]",
            "from_visible": "Loja <[email protected]>",
            "to": "[email protected]",
            "recipients": [
                "[email protected]"
            ],
            "tags": [
                "transacional",
                "pedido-1234"
            ],
            "smtp_domain_id": 4180,
            "smtp_account_id": 9271,
            "plan_type": "smtp",
            "sent_at": "2026-10-15T09:11:58-03:00",
            "id": "<identificador do registro>"
        },
        "delivery": {
            "status": "msg:yes:finished:with:bounce",
            "hard_bounce": 1,
            "soft_bounce": 0,
            "discarded": 0,
            "trap": 0,
            "bounce": {
                "kind": "hard",
                "code": "550",
                "answer": "550 5.1.1 The email account does not exist",
                "domain": "exemplo.com.br"
            }
        },
        "engagement": null
    },
    "id": "01M4YQV7RC6VKAVJM5E6B4TCY8"
}

Campo	O que é
`id`	o identificador do fato, igual ao cabeçalho `X-iPORTO-Event-Id`
`event`	o nome do evento, igual ao cabeçalho `X-iPORTO-Event`
`api_version`	a data em que este formato foi fixado
`created_at`	quando o evento foi emitido
`data`	a mensagem — os campos estão em O bloco `param.details`

Os nomes de evento

v1	v2
`msg_deliverability_yes_queue`	`email.queued`
`msg_deliverability_yes_delivery`	`email.delivered`
`msg_deliverability_not_delivery_soft_bounce`	`email.bounced.soft`
`msg_deliverability_not_delivery_hard_bounce`	`email.bounced.hard`
`msg_deliverability_not_accepted`	`email.rejected`
`msg_engagement_open`	`email.opened`
`msg_engagement_click`	`email.clicked`
`msg_engagement_compliance_spam`	`email.complained`
`msg_deliverability_yes_delivery` (SMS)	`sms.accepted`
`msg_deliverability_not_accepted` (SMS)	`sms.rejected`

O cabeçalho X-iPORTO-Event acompanha o corpo: nome antigo no v1, novo no v2. Se você casa o cabeçalho com o campo event, continua casando.

`email.delivered` passa a significar “entregue”

Entrega parcial não gera email.delivered. Três destinatários, dois entregues e um com hard bounce: sai só email.bounced.hard. Quantos de cada desfecho está em data.delivery:

{
    "status": "msg:yes:finished:with:bounce",
    "hard_bounce": 1,
    "soft_bounce": 0,
    "discarded": 0,
    "trap": 0
}

Se o seu relatório conta entregas pelo número de eventos delivered, no v2 ele passa a contar pelos contadores — e aí ele passa a estar certo nos casos parciais, onde antes contava a mensagem inteira como entregue.

Os três eventos que só o v2 tem

Todos de SMS:

Evento	Quando acontece
`sms.delivered`	o aparelho confirmou o recebimento. No v1 isso não tem evento: lá, `yes_delivery` significa “a operadora aceitou”
`sms.replied`	o destinatário respondeu — e o texto vem em `data.message.body`
`sms.unsubscribed`	a resposta pediu para parar (`SAIR`, `PARE`, `PARAR`, `STOP`)

O que o v2 não leva

http_request_params, que no v1 repete a sua requisição de envio inteira, incluindo o corpo da mensagem. Se o seu endpoint grava o que recebe, no v1 ele guarda o conteúdo dos seus e-mails; no v2 não há o que guardar.
about e o email/phone do topo: tudo está em data.

Trocar de formato

Na tela do endpoint, em Trocar o formato do corpo. Vale do próximo evento em diante.


a troca é por endereço	um endpoint em v2 e outro em v1, na mesma conta, é normal
não mexe nos eventos que você assinou	as marcações continuam as mesmas
o v2 exige https	endereço em `http://` tem a troca recusada, com o motivo na tela
voltar para o v1 é um clique	os eventos que só existem no v2 deixam de ser enviados