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.
| Transacional | Marketing | |
|---|---|---|
| Quem dispara | O seu sistema, por API | Você, pelo painel |
| Para quem | Uma pessoa por vez | Uma lista ou segmento |
| Quando | No momento do evento | No horário escolhido |
| Exemplos | Senha, pedido, boleto, código de acesso | Newsletter, promoção, lançamento |
| Descadastro | Não se aplica a mensagens de serviço | Obrigató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.
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.
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.
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.
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.
| Evento | Quando chega | O que fazer |
|---|---|---|
| delivered | O provedor do destinatário aceitou a mensagem | Marcar como entregue no seu sistema |
| bounce | A mensagem foi recusada; bounce_classification diz o motivo | Se for definitiva, pedir outro endereço à pessoa |
| spamreport | O destinatário marcou como spam | Não reenviar; o endereço já foi suprimido |
| open | A mensagem foi aberta; machine_open marca as de antivírus e pré-carregamento | Ignorar as de máquina na sua taxa de abertura |
| click | Um link foi clicado; o campo url diz qual | Ligar o clique ao registro pelos metadados |
| unsubscribe | O destinatário pediu descadastro | Refletir 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 planosPerguntas 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.