E-mail transacional

E-mail transacional pela API, cobrado em real

Confirmação de pedido, redefinição de senha e aviso de cobrança saindo do seu sistema por uma API REST, no mesmo medidor das suas campanhas.

O que é e-mail transacional

E-mail transacional é a mensagem que o seu sistema envia para uma pessoa por causa de algo que ela fez: criou uma conta, comprou, pediu para trocar a senha, recebeu uma cobrança. Ele vai para um destinatário por vez, no momento do evento, e a pessoa espera recebê-lo.

O e-mail marketing é o contrário: a mesma mensagem para uma lista, no horário que a empresa escolhe. Por isso os dois costumam ficar em ferramentas separadas, com duas faturas e dois painéis para acompanhar a entrega.

Diferença entre e-mail transacional e e-mail marketing
TransacionalMarketing
Quem disparaO seu sistema, por APIVocê, pelo painel
Para quemUma pessoa por vezUma lista ou segmento
QuandoNo momento do eventoNo horário escolhido
ExemplosSenha, pedido, boleto, código de acessoNewsletter, promoção, lançamento
DescadastroNão se aplica a mensagens de serviçoObrigatório, em um clique

No WiseData Mail os dois saem da mesma conta, do mesmo domínio autenticado e contam no mesmo medidor de envios.

Duas formas de enviar pela API

Escolha um modelo criado na plataforma ou mande o conteúdo pronto na chamada. A resposta volta na hora; a entrega chega depois, pelo webhook.

  • Modelo da plataforma: crie o e-mail transacional no painel e a chamada leva só a chave do modelo e as variáveis (nome, número do pedido, link). Mudar o texto não exige mexer no seu sistema.
  • Conteúdo na chamada: quem prefere manter o e-mail no próprio código manda assunto, HTML e versão em texto direto na API.
  • 202 quando a mensagem entra na fila; 200 quando a mesma chave de idempotência já foi usada, sem enviar de novo.
  • Até 10 anexos por mensagem, somando 10 MB, também junto com um modelo da plataforma: a confirmação salva no painel com o PDF da fatura na chamada.
  • Tags e metadados voltam em todo evento de webhook, para você ligar a entrega ao pedido.

Exemplos de e-mail transacional

Os seis tipos que quase todo sistema precisa mandar, cada um com o cuidado que evita o problema mais comum.

  • Cadastro e confirmação de e-mail

    Boas-vindas e link para confirmar o endereço logo após o cadastro. Dica: o link deve expirar e funcionar uma vez só. Envie na hora do cadastro, nunca em lote no fim do dia.

  • Redefinição de senha

    Link para criar uma senha nova. Dica: validade curta, uso único e nenhuma senha no corpo. Na tela de "esqueci a senha", mostre a mesma mensagem exista ou não a conta.

  • Código de acesso

    Código de verificação em duas etapas ou de login sem senha. Dica: o código vai no corpo, nunca no assunto, porque o assunto aparece na notificação da tela bloqueada.

  • Confirmação de pedido

    Número do pedido, itens, total e próximos passos. Dica: use o id do pedido na Idempotency-Key. Se o seu sistema repetir a chamada, o cliente não recebe duas confirmações.

  • Cobrança, fatura e recibo

    Boleto, fatura, recibo e aviso de vencimento. Dica: anexe o PDF (até 10 MB no total) ou mande um link para a área logada. Guarde o id da fatura nos metadados para conciliar pelo webhook.

  • Aviso de sistema

    Novo acesso à conta, troca de e-mail, mudança de termos, falha em integração. Dica: escreva o que aconteceu e o que a pessoa deve fazer, com um único botão. Sem promoção junto.

Como funciona a entrega

Da chamada da API até o evento chegar ao seu sistema, em quatro etapas.

  1. O seu sistema chama a API

    POST /v1/emails com a chave da API. A resposta 202 traz o identificador da mensagem; com a mesma Idempotency-Key, a resposta é 200 e nada sai de novo.

  2. A conta confere antes de enviar

    Endereço já suprimido por rejeição permanente ou reclamação volta com o status suppressed. Sem cota no ciclo, a API recusa a chamada com 403 em vez de enfileirar.

  3. A mensagem sai pelo seu domínio

    Assinada com o DKIM do domínio autenticado. O provedor do destinatário aceita (entrega) ou recusa (rejeição), e o resultado vira evento.

  4. Os eventos chegam no webhook

    Entrega, abertura, clique, rejeição, reclamação e descadastro, em lotes de até cem, assinados e com nova tentativa automática se o seu servidor não responder.

Os eventos do webhook

Cada evento traz o tipo, o horário, o endereço, o identificador da mensagem e as tags e metadados que você mandou no envio. O campo campaign_id vem nulo no transacional, e message_type diz se a mensagem era transactional ou marketing.

Tipos de evento do webhook e o que fazer com cada um
EventoQuando chegaO que fazer
deliveredO provedor do destinatário aceitou a mensagemMarcar como entregue no seu sistema
bounceA mensagem foi recusada; bounce_classification diz o motivoSe for definitiva, pedir outro endereço à pessoa
spamreportO destinatário marcou como spamNão reenviar; o endereço já foi suprimido
openA mensagem foi aberta; machine_open marca as de antivírus e pré-carregamentoIgnorar as de máquina na sua taxa de abertura
clickUm link foi clicado; o campo url diz qualLigar o clique ao registro pelos metadados
unsubscribeO destinatário pediu descadastroRefletir a preferência no seu cadastro

Os eventos chegam em lotes de até cem, assinados com o segredo do endpoint, e o exemplo completo de um lote está na central de ajuda.

O desfecho simulado pela caixa de homologação chega no mesmo endpoint, assinado do mesmo jeito, com is_test: true. Filtre por esse campo para uma rejeição de teste nunca descadastrar um cliente real.

Boas práticas de e-mail transacional

O transacional é o e-mail que a pessoa está esperando. Se ele cai no spam ou chega duas vezes, o problema vira chamado no suporte. Estas seis práticas resolvem a maior parte dos casos.

1. Remetente separado do marketing

Use um endereço próprio para o transacional, como pedidos@ ou conta@, e não o mesmo da newsletter. Se o seu plano tem mais de um domínio, um subdomínio só para o transacional (por exemplo, avisos.suaempresa.com.br) separa a reputação dos dois aos olhos dos provedores: uma campanha com muitas reclamações não arrasta a redefinição de senha para o spam.

2. Assunto sem dado sensível

O assunto aparece na notificação do celular, na lista da caixa de entrada e nos logs de quem processa o e-mail. Nada de código de acesso, senha, CPF ou número de cartão no assunto. "Seu código de acesso" basta; o código vai no corpo.

3. Sempre com versão em texto

Mande o campo text junto com o html. Leitores de tela, relógios e alguns clientes de e-mail corporativos mostram a versão em texto, e a falta dela pesa contra a mensagem nos filtros de spam.

4. Idempotência em toda chamada

Fila que repete, timeout que dispara nova tentativa e clique duplo no botão geram a mesma chamada duas vezes. Derive a Idempotency-Key do identificador interno (pedido-48213-confirmacao) e reaproveite a mesma chave em toda nova tentativa. A API devolve a mensagem anterior com 200 e não envia outra.

5. Webhook tratado do jeito certo

  • Confira a assinatura: HMAC-SHA256 do timestamp, um ponto e o corpo cru, com o segredo do endpoint, comparado ao cabeçalho X-WiseData-Signature.
  • Recuse timestamp antigo, para um lote capturado não ser reaproveitado depois.
  • Responda 2xx rápido e processe em fila. Resposta lenta vira nova tentativa.
  • Descarte repetição pelo X-WiseData-Delivery (o lote) e pelo id de cada evento.
  • Não presuma ordem: use occurred_at para não trocar um estado mais novo por um mais velho.

6. Não misture marketing no transacional

Um banner de promoção no rodapé da confirmação de pedido transforma a mensagem de serviço em mensagem comercial: ela passa a exigir descadastro e consentimento, e as reclamações que ela gerar caem sobre o canal que entrega a senha. Promoção vai por campanha, para quem aceitou receber.

O domínio ainda não está autenticado? Leia o guia de SPF, DKIM e DMARC.

O que vem junto com a API

  • Webhooks assinados

    Entrega, abertura, clique, rejeição, reclamação e descadastro chegam em lotes de até cem eventos, com assinatura, nova tentativa automática e rotação de segredo.

  • Caixa de homologação

    Uma chave de teste simula entrega, rejeição e reclamação sem mandar nada para fora. Dá para testar o receptor de webhook antes de ir para produção.

  • Chaves com escopo

    Cada chave recebe só o que precisa: ler contatos, gravar contatos, excluir contatos ou enviar e-mail.

  • Contatos pela mesma API

    Crie ou corrija contatos pelo identificador do seu sistema e coloque-os em listas, para as campanhas usarem a mesma base.

  • Abertura de máquina marcada

    Aberturas e cliques feitos por antivírus ou pré-carregamento vêm marcados, para não inflar o seu número.

  • SDK PHP e transport para Laravel

    Cliente PHP de código aberto (MIT). Em Laravel, o envio passa pelo WiseData Mail trocando o mailer no .env.

Por que trocar o provedor em dólar

  • Cobrança em real e com nota fiscal, sem IOF e sem a fatura mudar com o câmbio.
  • Marketing e transacional no mesmo fornecedor e no mesmo medidor.
  • Verificação pré-envio e painel de saúde também para o transacional.
  • Suporte em português.

Em quais planos

A API está incluída no plano Volume (R$ 799, 400 mil envios). O teste grátis não inclui a API.

Ver os planos

Perguntas sobre e-mail transacional

Qual a diferença entre e-mail transacional e e-mail marketing?

O transacional é disparado pelo seu sistema por causa de uma ação da pessoa (cadastro, compra, troca de senha) e vai para um destinatário por vez. O marketing é a mesma mensagem para uma lista, no horário que a empresa escolhe. No WiseData Mail os dois saem da mesma conta.

E-mail transacional precisa de consentimento?

Mensagem de serviço, ligada a um cadastro, pedido ou contrato, não depende do consentimento de marketing e não exige descadastro. Isso vale enquanto ela for só serviço: com promoção dentro, ela passa a ser e-mail comercial.

Vocês têm SMTP?

Não. O envio é pela API REST e pelo painel. Em Laravel, o SDK PHP substitui o SMTP sem mudar o código que chama o Mail.

O e-mail transacional tem descadastro?

Mensagens de serviço, como senha e pedido, não exigem descadastro. Se o endereço já estiver suprimido por rejeição permanente ou reclamação, a API devolve o status suppressed em vez de enviar.

Como evito enviar duas vezes a mesma mensagem?

Mande o cabeçalho Idempotency-Key. Se a mesma chave chegar de novo, a API devolve a mensagem anterior com status 200 e não envia outra.

Como sei se o e-mail foi entregue?

Pelo webhook, que manda o evento delivered quando o provedor do destinatário aceita a mensagem e bounce quando recusa. No painel, a linha do tempo do contato mostra cada envio e o motivo de cada falha.

Posso testar a integração sem enviar para clientes reais?

Sim. A chave de teste da caixa de homologação simula entrega, rejeição e reclamação sem mandar nada para fora, e os eventos chegam ao webhook com is_test: true.

Quanto custa o e-mail transacional?

Cada mensagem conta um envio no mesmo medidor das campanhas. A API está no plano Volume, R$ 799 por mês com 400 mil envios. Estourou a cota, a API recusa novos envios até a virada do ciclo: não existe cobrança de excedente.

Comece pelo teste grátis

Conheça o painel e autentique o domínio sem cartão. A API e a caixa de homologação vêm no plano Volume.