Transactional Messaging API: e-mail transacional em tempo real no Marketing Cloud

Confirmação de pedido, código de verificação, redefinição de senha: são mensagens que precisam chegar agora, uma por vez, disparadas pelo seu sistema. A Transactional Messaging API do Marketing Cloud Engagement foi feita para isso. Ela é mais direta que montar um Triggered Send e é a API recomendada para novos fluxos transacionais.

Antes de começar

• Um token OAuth 2.0 server-to-server. Veja o tutorial de autenticação na API REST.
• No Installed Package, as permissões de e-mail (leitura, escrita e envio).
• Um e-mail pronto no Content Builder, com a customer key anotada. Personalize com atributos que você vai mandar na chamada, por exemplo %%=v(@NumeroPedido)=%% ou %%NumeroPedido%%.

1. A definição de envio

A definição liga o e-mail às configurações de envio. Ela é criada uma vez e reutilizada em todos os disparos.

curl -X POST "https://SEU_SUBDOMINIO.rest.marketingcloudapis.com/messaging/v1/email/definitions" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionKey": "pedido-confirmado",
    "name": "Pedido confirmado",
    "content": { "customerKey": "CUSTOMER_KEY_DO_EMAIL" },
    "subscriptions": { "list": "All Subscribers" },
    "options": { "trackLinks": true }
  }'

• definitionKey é o nome que o seu sistema vai usar em todo envio. Escolha algo estável e legível.
• subscriptions.list aponta para a lista de assinantes. Confira a customer key da lista no seu ambiente.

2. Enviando

Cada envio tem uma messageKey gerada por você. Use um identificador único, como um UUID, e guarde: é com ela que você consulta o status depois.

curl -X POST "https://SEU_SUBDOMINIO.rest.marketingcloudapis.com/messaging/v1/email/messages/7f3c2a90-5b1e-4d3a-9a0f-1c2b3d4e5f60" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionKey": "pedido-confirmado",
    "recipient": {
      "contactKey": "cliente-10021",
      "to": "ana@exemplo.com",
      "attributes": {
        "NumeroPedido": "10021",
        "ValorTotal": "189,90"
      }
    }
  }'

A API responde 202 Accepted: o pedido foi aceito e entrou na fila de envio, que é processada em tempo real.

• contactKey é a chave do contato no Marketing Cloud. Use a mesma chave do resto da sua operação (normalmente o ID do cliente), não o e-mail, para não criar contatos duplicados.
• attributes são os dados de personalização daquela mensagem.

3. Consultando o status

curl "https://SEU_SUBDOMINIO.rest.marketingcloudapis.com/messaging/v1/email/messages/7f3c2a90-5b1e-4d3a-9a0f-1c2b3d4e5f60" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

O retorno informa se a mensagem foi enviada ou o motivo de não ter sido (por exemplo, endereço em bounce ou descadastrado).

Boas práticas

• Reaproveite o token OAuth em vez de pedir um a cada envio.
• Trate erros 4xx do lado do seu sistema: 400 costuma ser corpo inválido ou definitionKey inexistente.
• Pause a definição em vez de apagá-la quando precisar parar um fluxo: o histórico continua disponível.
• Monitore os envios que não saíram, consultando o status pela messageKey.

Resumo

Crie a definição uma vez, dispare cada mensagem com uma messageKey única e os atributos do evento, e acompanhe o status pela mesma chave. Para confirmações e códigos, a Transactional Messaging API é o caminho mais simples e rápido dentro do Marketing Cloud.