Mailgun: Guia técnico completo para email transacional

⚡TL;DR

• 📢 O Mailgun usa seu domínio no Return-Path (bounce+id@seudominio.com), o que permite o alinhamento SPF nativo para DMARC já no plano básico.
• A API REST é o método recomendado: até 1.000 destinatários por chamada, rate limits não documentados (exceto a Domains API: 300 req/min).
• O Automatic Sender Security gera 2 CNAME DKIM com rotação automática a cada 120 dias, chaves de 2048 bits por padrão.
• IP dedicado recomendado a partir de 1 milhão de emails/mês, com warm-up automático em 15+ dias e custo adicional de 59$/IP/mês.
• Plano Flex aumentado para 2,00$/1000 emails desde dezembro de 2025 (a tarifa dobrou).

Introdução

O Mailgun se consolidou como uma das plataformas de email transacional mais robustas do mercado, processando mais de 600 bilhões de emails por ano para mais de 100.000 clientes. Adquirido pela Sinch em dezembro de 2021 por 1,9 bilhão de dólares, o serviço combina uma API REST poderosa, um relay SMTP universal e recursos de autenticação avançados que o diferenciam da concorrência.

A força do Mailgun está em três pilares técnicos principais: uma abordagem API-first voltada para desenvolvedores, uma Domain Verification que usa seu próprio domínio no Return-Path (alinhamento SPF nativo para DMARC) e um sistema de rotação automática das chaves DKIM de 2048 bits a cada 120 dias sem interrupção de serviço.

Este guia é destinado a desenvolvedores, DevOps e arquitetos de sistemas que querem integrar o Mailgun para email transacional com uma compreensão completa da infraestrutura: configuração DNS, escolha entre API e SMTP, gestão de IPs dedicados, limites técnicos e webhooks de eventos.

API REST vs SMTP Relay: arquitetura e escolha de integração

O Mailgun oferece dois métodos de integração para email transacional, ambos disponíveis já no plano gratuito (100 emails/dia).

Comparativo técnico

Critério	API REST	SMTP Relay
Endpoint	https://api.mailgun.net/v3/{domain}/messages (US)	smtp.mailgun.org portas 587/465
Autenticação	HTTP Basic Auth (api:YOUR_API_KEY)	SASL/PLAIN (postmaster@ + senha SMTP)
Rate limit	Não documentado (Domains API: 300 req/min)	Depende do IP e do plano
Destinatários/req	Até 1.000 (to + cc + bcc combinados)	1 email = 1 conexão SMTP
Templates	Variáveis com sintaxe {{variable}}	Via cabeçalho X-Mailgun-Variables
Agendamento	o:deliverytime (até 3 dias, 7d com armazenamento 7d+)	Via cabeçalho X-Mailgun-Deliver-By
Tracking	Nativo (o:tracking, o:track-clicks, o:track-opens)	Via cabeçalhos X-Mailgun-Track*
Compatibilidade	Requer SDK ou cliente HTTP	Qualquer sistema com suporte a SMTP
Caso de uso ideal	Apps modernos, batch, personalização avançada	Legacy, plugins de CMS, servidores de email

Quando escolher a API REST?

A API REST é o método recomendado pelo Mailgun para qualquer nova integração. Ela fica acessível em POST https://api.mailgun.net/v3/{domain}/messages para a região US, ou em api.eu.mailgun.net para a EU.

Principais vantagens:

• Batch sending: envio para até 1.000 destinatários em uma única requisição, com personalização via recipient variables
• Templates armazenados: sintaxe Handlebars com condições, laços e helpers personalizados
• Agendamento: programação de envio com até 3 dias de antecedência (7 dias se o seu plano incluir 7+ dias de armazenamento)
• Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset para monitoramento

Exemplo de envio com personalização:

curl -s --user 'api:YOUR_API_KEY' \
  https://api.mailgun.net/v3/mail.captaindns.com/messages \
  -F from='Notificacoes <no-reply@mail.captaindns.com>' \
  -F to='user1@captaindns.com' \
  -F to='user2@captaindns.com' \
  -F subject='Nova notificacao' \
  -F text='Ola {{nome}}, voce tem {{count}} notificacoes.' \
  -F recipient-variables='{"user1@captaindns.com":{"nome":"Joao","count":"3"},"user2@captaindns.com":{"nome":"Maria","count":"7"}}' \
  -F o:tag='notification' \
  -F o:tracking='yes'

SDKs oficiais: o Mailgun mantém SDKs para Go, Node.js, PHP, Python, Ruby e Java que encapsulam a API REST e simplificam a integração.

Quando escolher o SMTP Relay?

O SMTP Relay é ideal para sistemas legacy ou aplicações que só suportam SMTP.

Configuração oficial:

SMTP server: smtp.mailgun.org (US) ou smtp.eu.mailgun.org (EU)
SMTP user: postmaster@mail.captaindns.com (ou usuario SMTP personalizado)
SMTP password: [senha SMTP do dominio]
Port: 587 (STARTTLS recomendado) ou 465 (TLS direto) ou 2525 (fallback GCE)

Ponto crítico: a autenticação SMTP usa a senha SMTP do domínio, diferente da chave de API. O username é o endereço postmaster@ do seu domínio verificado (ou um usuário SMTP personalizado criado no painel).

Cabeçalhos proprietários X-Mailgun-*: dão acesso aos recursos avançados via SMTP (tags, tracking, templates, agendamento, variáveis). Lista completa:

• X-Mailgun-Tag: tag para estatísticas (vários possíveis)
• X-Mailgun-Track: ativar/desativar o tracking global
• X-Mailgun-Track-Clicks: tracking de cliques (yes/no/htmlonly)
• X-Mailgun-Track-Opens: tracking de aberturas (yes/no)
• X-Mailgun-Deliver-By: agendamento (formato RFC 2822 ou timestamp Unix)
• X-Mailgun-Template-Name: nome do template a usar
• X-Mailgun-Variables: variáveis do template (JSON)

Domain Verification: SPF, DKIM 2048 bits e alinhamento DMARC nativo

A configuração DNS no Mailgun gera os registros necessários para SPF, DKIM e o alinhamento DMARC. O processo é feito em Sending > Domains > Domain settings > Domain verification.

Arquitetura com Automatic Sender Security (recomendado)

Com a opção Automatic Sender Security ativada (recomendado), o Mailgun gera 2 registros CNAME DKIM para a rotação automática das chaves:

Registros necessários (exemplo para mail.captaindns.com):

Tipo	Name/Host	Value	Objetivo
TXT	mail.captaindns.com	v=spf1 include:mailgun.org ~all	SPF
CNAME	pdk1._domainkey.mail.captaindns.com	pdk1._domainkey.XXXX.dkim1.mailgun.com	Rotação DKIM (seletor 1)
CNAME	pdk2._domainkey.mail.captaindns.com	pdk2._domainkey.XXXX.dkim1.mailgun.com	Rotação DKIM (seletor 2)
MX	mail.captaindns.com	mxa.mailgun.org (prioridade 10)	Bounces/Inbound
MX	mail.captaindns.com	mxb.mailgun.org (prioridade 10)	Bounces/Inbound

Nota sobre a região EU: para a EU, os registros MX usam mxa.eu.mailgun.org e mxb.eu.mailgun.org.

Vantagens dessa arquitetura:

• Rotação automática das chaves DKIM: os dois seletores (pdk1 e pdk2) permitem que o Mailgun troque as chaves a cada 120 dias sem interrupção de serviço
• Chaves DKIM de 2048 bits por padrão (configurações manuais em TXT podem usar 1024 bits, mas 2048 é o recomendado)
• Nenhum registro CNAME de tracking exigido por padrão: o Mailgun usa mailgun.org (ou eu.mailgun.org para a EU)
• Seletores DKIM: pdk1 e pdk2 para o Automatic Security, ou mx para a configuração manual em TXT

Return-Path e alinhamento SPF: uma vantagem importante

O Return-Path (Envelope From) é essencial para o alinhamento DMARC. O Mailgun usa automaticamente seu domínio no Return-Path, no formato bounce+UNIQUEID@mail.captaindns.com:

• O SPF passa automaticamente, porque o registro include:mailgun.org autoriza os IPs do Mailgun a enviar pelo seu domínio
• O alinhamento SPF funciona em modo relaxed (o Return-Path bounce+id@mail.captaindns.com corresponde ao domínio pai mail.captaindns.com)
• Sem necessidade de configuração separada: ao contrário de outros provedores, o Mailgun não exige um subdomínio dedicado para o bounce domain

Diferença em relação aos concorrentes:

• SendGrid: usa um subdomínio personalizável (em1234.captaindns.com)
• Amazon SES: exige Custom MAIL FROM para o alinhamento SPF
• Mailgun: usa diretamente seu domínio verificado

Para uma política DMARC estrita (aspf=s), o alinhamento SPF vai falhar se você enviar a partir de um subdomínio diferente do Return-Path. A solução é se apoiar no DKIM para o alinhamento DMARC, que suporta o modo strict (adkim=s).

Tracking domain (link branding)

O tracking domain substitui os domínios do Mailgun nos links rastreados pelo seu próprio domínio. Por padrão, o Mailgun usa email.mail.captaindns.com apontando para mailgun.org (US) ou eu.mailgun.org (EU) via CNAME.

Configuração HTTPS opcional: o Mailgun gera automaticamente um certificado Let's Encrypt assim que o CNAME é verificado.

Migração para DKIM de 2048 bits

Para migrar uma configuração TXT manual (chaves de 1024 bits) para o Automatic Sender Security (2048 bits), basta ativar o Automatic Sender Security no painel e depois criar os 2 novos CNAME DKIM. A transição é suave graças aos dois seletores.

Fluxo de autenticação de email: da API à entregabilidade

Quando você envia pelo Mailgun:

1. Sua aplicação chama a API REST ou usa SMTP
2. O Mailgun assina a mensagem com sua chave DKIM (domínio d=mail.captaindns.com)
3. O Mailgun usa seu domínio no Return-Path (bounce+id@mail.captaindns.com)
4. O servidor destinatário verifica o SPF (IP de envio), o DKIM (assinatura) e depois o DMARC (alinhamento)
5. O SPF passa: include:mailgun.org autoriza os IPs do Mailgun, e o Return-Path usa seu domínio
6. O DKIM passa: a assinatura d=mail.captaindns.com corresponde ao cabeçalho From
7. O DMARC passa: pelo menos SPF E DKIM estão alinhados (validação dupla)

Alinhamento DMARC: configuração para p=reject

O que funciona (e o que quebra)

Alinhamento DKIM:

Configuração	Alinhado?	DMARC via DKIM?
Domínio com DKIM ativado (TXT ou CNAME)	Sim	Sim

Alinhamento SPF:

Configuração	Alinhado?	DMARC via SPF?
Return-Path usa seu domínio (nativo)	Sim	Sim
aspf=r (relaxed, padrão)	Sim	Sim
aspf=s (strict) + envio a partir de subdomínio	Não	Não (mismatch de subdomínio)

Registro DMARC recomendado

_dmarc.captaindns.com  TXT  "v=DMARC1;p=reject;adkim=r;aspf=r;rua=mailto:dmarc@captaindns.com"

Pontos-chave:

• adkim=r e aspf=r: alinhamento relaxed (permite subdomínios)
• Avance de p=none → p=quarantine → p=reject
• Acompanhe os relatórios rua antes de endurecer a política
• Vantagem do Mailgun: alinhamento duplo (SPF + DKIM) nativo, proteção melhor do que apenas com DKIM

Tabela resumo completa de DNS

Tipo	Host/Name	Value	Obrigatório	Notas
TXT	mail.captaindns.com	v=spf1 include:mailgun.org ~all	✅ Sim	SPF idêntico US/EU
CNAME	pdk1._domainkey.mail.captaindns.com	pdk1._domainkey.XXXX.dkim1.mailgun.com	✅ Sim	Rotação DKIM automática
CNAME	pdk2._domainkey.mail.captaindns.com	pdk2._domainkey.XXXX.dkim1.mailgun.com	✅ Sim	Rotação DKIM automática
MX	mail.captaindns.com	mxa.mailgun.org (prioridade 10)	✅ Sim	Bounces/Inbound
MX	mail.captaindns.com	mxb.mailgun.org (prioridade 10)	✅ Sim	Bounces/Inbound
TXT	_dmarc.captaindns.com	v=DMARC1;p=reject;adkim=r;aspf=r;...	Recomendado	Política DMARC
CNAME	email.mail.captaindns.com	mailgun.org ou eu.mailgun.org	Opcional	Tracking domain

IP dedicado vs IP compartilhado: estratégia de entregabilidade

O Mailgun recomenda oficialmente um IP dedicado a partir de 1 milhão de emails por mês. Abaixo disso, o IP compartilhado costuma oferecer melhor entregabilidade.

IP compartilhado (planos Free, Foundation e Growth básico)

Vantagens:

• Nenhum warm-up necessário
• Reputação mantida pelo Mailgun
• Ideal para volumes baixos ou irregulares
• Melhor entregabilidade inicial do que em um IP dedicado frio

Desvantagens:

• Exposição aos riscos de reputação ligados aos outros remetentes do pool (raro no Mailgun graças aos controles rigorosos)

IP dedicado (Foundation 100k+, Growth, Scale, Enterprise)

O plano Foundation 100k inclui 1 IP dedicado (a partir de 75$/mês). Cada IP adicional custa 59$/IP/mês.

Recomendação oficial: 1 IP dedicado para cerca de 1 milhão de emails por mês, no mínimo.

Vantagens:

• Reputação isolada e controlável
• Função de IP Warmup automático em 15 etapas (~15+ dias)
• Possibilidade de separar os fluxos (transacional vs marketing) via IP Pools

IP Warmup automático: o Mailgun oferece um warm-up em 15 etapas progressivas:

Etapa	Limite diário	Limite por hora	Duração
1	1.000	100	24h
2	2.500	~100	24h
3	5.000	Progressivo	24h
...	Progressivo	Progressivo	...
15	Capacidade total	Sem limite	Atingida no D15+

O sistema avança uma etapa a cada 24 horas se os limites forem atingidos. O tráfego excedente é roteado automaticamente para os IPs compartilhados ou para outros IPs dedicados disponíveis.

IP Pools: disponíveis nos planos Scale e superiores. Permitem:

• Separar emails transacionais e de marketing
• Atender clientes/marcas diferentes (multi-tenant)
• Dynamic IP Pools: atribuição automática com base na saúde da reputação

Nota importante: os IPs dedicados são vinculados a uma região (US ou EU). Uma migração de região exige um novo IP e um novo warm-up.

Quando escolher um IP dedicado?

Você precisa de um IP dedicado se:

• Volume regular > 1 milhão de emails/mês
• Necessidade de separar a reputação transacional da de marketing
• Exigências de whitelisting de clientes ou de conformidade regulatória
• Volume > 2,5 milhões de emails/mês: vários IPs dedicados recomendados

Fique no IP compartilhado se:

• Volume < 1 milhão de emails/mês
• Envios irregulares ou esporádicos
• Início de atividade sem histórico
• Apenas transacional e de baixo volume

Preços 2026 e evolução recente

Planos Send (janeiro de 2026)

Plano	Preço/mês	Emails incluídos	Overage (/1000)	Retenção de logs	IP dedicado
Free	0 $	100/dia	N/A	1 dia	Não
Flex	Pago por uso	1.000 grátis/mês	2,00 $ ⚠️	5 dias	Não
Foundation 50k	35 $	50.000	~1,30 $	5 dias	Não
Foundation 100k	75 $	100.000	~1,30 $	5 dias	1 incluído
Growth	80-650 $	100k-1M	Variável	15 dias	1 incluído
Scale 100k	90 $	100.000	~0,80-1,10 $	30 dias	1 incluído
Scale (máx)	1.250 $	2,5M	Variável	30 dias	1 incluído
Enterprise	Sob consulta	2,5M+	Negociado	30 dias	Múltiplos

Evolução tarifária recente

⚠️ Mudança importante (1º de dezembro de 2025): o plano Flex passou de 1,00 $ para 2,00 $ por 1.000 emails, um aumento de 100%. Essa alta significativa torna os planos Foundation bem mais atrativos para volumes acima de 25.000 emails/mês.

Análise econômica:

• Plano Flex: 50.000 emails = 49.000 pagos × 0,002 = 98 $
• Plano Foundation 50k: 50.000 emails = 35 $ (economia de 63 $)
• Ponto de equilíbrio: o plano Foundation passa a compensar a partir de ~18.000 emails/mês

Planos Optimize (ferramentas de entregabilidade)

Plano	Preço/mês	Validações	Testes de inbox	Previews
Pilot	49 $	2.500	25	500
Starter	99 $	5.000	50	1.000
Contract	Sob consulta	Personalizado	Personalizado	Personalizado

Descontos anuais

Não são documentados publicamente. Clientes Enterprise relatam descontos negociáveis de 10%+.

Preços US vs EU

Os preços são padronizados mundialmente em USD. Não há diferença regional documentada entre US e EU.

Limites técnicos e cotas

Limite	Valor	Notas
Tamanho máximo do email	25 MB	Corpo + anexos + cabeçalhos
Destinatários/mensagem	1.000	To + Cc + Bcc combinados
Parâmetros send options	16 KB	Parâmetros o:, h:, v:, t:
Templates/domínio	100	Limite rígido
Versões/template	10	-
Domínios (Free)	5	-
Domínios (pago)	1.000	-
Destinatários sandbox	5	Precisam ser verificados
Rate limit da Domains API	300 req/min	Único endpoint documentado
Rate limit de envio (contas novas)	100 mensagens/hora	Antes da verificação de negócio
Agendamento máximo	3 dias	7 dias em planos com 7d+ de storage

Retenção dos dados

Dado	Retenção
Logs de eventos (Free)	1 dia
Logs de eventos (Foundation)	5 dias
Logs de eventos (Growth)	15 dias
Logs de eventos (Scale)	30 dias (máx)
Conteúdo das mensagens	1-7 dias (configurável)
Estatísticas por hora	60 dias
Estatísticas diárias	1 ano
Estatísticas mensais	Indefinida
Logs de segurança críticos	365 dias

Gestão de bounces e supressões

Hard bounce (falha permanente)

Comportamento	Detalhe
Ação	Endereço adicionado à lista de supressão
Duração do bloqueio	Indefinida (até a remoção manual)
Erro retornado	"Not delivering to previously bounced address"

Soft bounce (falha temporária)

Comportamento	Detalhe
Retry	Automático para os soft bounces imediatos
Duração	Até o sucesso ou a classificação como permanente
Conversão	Após várias falhas, inclusão na lista de bounces

Spam complaints (FBL)

O Mailgun se inscreve automaticamente nos Feedback Loops dos principais provedores de acesso. As reclamações disparam:

• Inclusão automática na lista Complaints
• Envio do webhook complained
• Bloqueio dos envios futuros para esse endereço

Provedores suportados: Yahoo, Microsoft/Outlook, Comcast, Cox, Fastmail e outros via Universal Feedback Loop. Nota: o Gmail não fornece um FBL tradicional.

Descadastramento automático

O Mailgun adiciona automaticamente:

• O cabeçalho List-Unsubscribe
• O cabeçalho List-Unsubscribe-Post: List-Unsubscribe=One-Click

Em conformidade com a RFC 8058 e com as exigências do Gmail/Yahoo para remetentes em massa (5000+ mensagens/dia).

API de listas de supressão

Lista	Endpoint
Bounces	GET/POST/DELETE /v3/{domain}/bounces
Complaints	GET/POST/DELETE /v3/{domain}/complaints
Unsubscribes	GET/POST/DELETE /v3/{domain}/unsubscribes
Allowlist	GET/POST/DELETE /v3/{domain}/allowlist

A Allowlist impede a inclusão de endereços na lista de bounces, mas não sobrepõe Complaints ou Unsubscribes.

Event Webhook e tracking em tempo real

O webhook de eventos permite receber em tempo real as notificações de delivery, engajamento e compliance.

Eventos disponíveis

• Delivery: accepted, delivered, temporary_fail, permanent_fail
• Engajamento: opened, clicked
• Compliance: complained, unsubscribed

Formato do payload JSON

{
  "signature": {
    "timestamp": "1529006854",
    "token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",
    "signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"
  },
  "event-data": {
    "event": "delivered",
    "timestamp": 1529006854.329574,
    "id": "DACSsAdVSeGpLid7TN03WA",
    "recipient": "recipient@captaindns.com",
    "tags": [],
    "message": {
      "headers": {
        "message-id": "20180618211821.captaindns.com"
      }
    }
  }
}

Política de retry

Código de resposta	Ação
200	Sucesso, sem retry
406	Rejeitado, sem retry
Outro	Retry conforme o cronograma

Cronograma de retry: 5min → 10min → 15min → 1h → 2h → 4h (total: 8 horas)

Segurança (assinatura HMAC)

Elemento	Valor
Algoritmo	HMAC-SHA256
Chave	Webhook Signing Key (Control Panel → Account Security)
Cálculo	HMAC-SHA256(timestamp + token, signingKey)

Exemplo em Python:

import hmac, hashlib
def verify(api_key, token, timestamp, signature):
    expected = hmac.new(api_key.encode(), f"{timestamp}{token}".encode(), 
                        hashlib.sha256).hexdigest()
    return signature == expected

Configuração

• Até 3 URLs por tipo de evento por domínio
• Configuração no nível do domínio (não da conta)
• API: POST /v3/domains/{domain}/webhooks

Templates Handlebars

O Mailgun usa o Handlebars (versão personalizada) para os templates armazenados.

Sintaxe das variáveis

Contexto	Sintaxe
Templates armazenados	{{variable}}
Batch sending inline (API)	%recipient.variable%

Condições e laços

{{#if condicao}}
  Conteudo se verdadeiro
{{else if outraCondicao}}
  Conteudo alternativo
{{else}}
  Conteudo padrao
{{/if}}

{{#unless condicao}}
  Conteudo se falso
{{/unless}}

{{#equal variable "valor"}}
  Conteudo se igual
{{/equal}}

{{#each array}}
  <li>{{this.propriedade}}</li>
{{/each}}

{{#with objeto}}
  {{propriedadeAninhada}}
{{/with}}

Limites dos templates

Limite	Valor
Templates por domínio	100
Versões por template	10
Tamanho do template	Não documentado
Partials (import)	Sem suporte

Recursos adicionais

Email Validation API

Atributo	Valor
Endpoint único	GET /v4/address/validate?address=...
Endpoint bulk	POST /v4/address/validate/bulk/{list_id}
Base de dados	450+ bilhões de emails
Tarifa Foundation	1,20 $/100 validações
Tarifa Scale	5.000 incluídas, depois 0,80 $/100

Validações realizadas: sintaxe RFC, registros MX, existência da caixa de correio, bounces da rede Mailgun, endereços de risco, endereços role-based, emails descartáveis, erros de digitação em domínios, domínios catch-all.

Inbound Parse (Routes)

Permite receber emails e encaminhá-los para uma URL de webhook:

Filtros: match_recipient(), match_header(), catch_all()
Acoes: forward("https://url"), forward("email@"), store(), stop()

Retry inbound: até 8 horas (10min, 15min, 30min, 1h, 2h, 4h) Retenção das mensagens armazenadas: 3 dias

Attachments

Limite	Valor
Tamanho total da mensagem	25 MB (corpo + anexos + cabeçalhos)
Tipos de arquivo	Nenhuma restrição documentada
Inline (CID)	Suportado via parâmetro inline

AMP for Email

Suportado desde 2019 via o parâmetro amp-html. Requer:

• Registro como remetente AMP junto ao Google
• SPF, DKIM e DMARC configurados
• Fallback HTML obrigatório

Segurança e conformidade

Certificações

Certificação	Status
ISO 27001	✅ Certificado
ISO 27701	✅ Certificado (privacidade)
SOC 2 Type I	✅ Certificado
SOC 2 Type II	✅ Certificado
SOC 1 (SSAE-16)	✅ Certificado
PCI-DSS	✅ Conforme (SAQ-A)
CSA Star Level 1	✅ Conforme

GDPR

Elemento	Detalhe
DPA	Disponível: mailgun.com/legal/dpa/
Localização dos dados na EU	Alemanha
Endpoints EU	api.eu.mailgun.net, smtp.eu.mailgun.org
Residência dos dados	Mensagens nunca transferidas para fora da região
DPO	Dedicado, sediado na EU

HIPAA

Elemento	Detalhe
Status	✅ Conforme
BAA	Disponível: mailgun.com/legal/hipaa-baa/
Pré-requisitos	Configuração de criptografia no cliente, consentimento do paciente, assinatura do BAA

Criptografia TLS

Versão	Status
TLS 1.0	❌ Descontinuado (março de 2021)
TLS 1.1	❌ Descontinuado (março de 2021)
TLS 1.2	✅ Suportado
TLS 1.3	✅ Suportado

Criptografia em repouso: AES-256

Autenticação avançada

Recurso	Disponibilidade
2FA	✅ Todos os planos
SSO	✅ Scale e Enterprise
SAML 2.0	✅ Scale e Enterprise
IdP suportados	Okta, Auth0, OneLogin, Azure AD, ADFS, AWS IAM
RBAC	✅ Scale e Enterprise (Admin, Developer, Analyst, Support)

Plano de ação: configuração em 6 etapas

1. Criar a conta e configurar o domínio

• Crie uma conta Mailgun em mailgun.com/signup
• Escolha a região (US ou EU conforme suas necessidades de GDPR)
• Um domínio sandbox é criado automaticamente (100 emails/dia)

2. Verificar o domínio (Domain Verification)

• Acesse Sending > Domains > Add New Domain
• Informe seu domínio de envio (ex.: mail.captaindns.com)
• Ative o Automatic Sender Security (recomendado)
• Crie os registros DNS no seu registrador:
  1. TXT SPF: v=spf1 include:mailgun.org ~all
  2. CNAME DKIM pdk1: pdk1._domainkey.mail.captaindns.com
  3. CNAME DKIM pdk2: pdk2._domainkey.mail.captaindns.com
  4. MX mxa: mxa.mailgun.org (prioridade 10)
  5. MX mxb: mxb.mailgun.org (prioridade 10)
• Verifique a propagação DNS (24-48h)

3. Publicar o registro DMARC

Crie o registro DMARC no seu domínio principal:

_dmarc.captaindns.com  TXT  "v=DMARC1;p=none;rua=mailto:dmarc@captaindns.com;aspf=r;adkim=r"

Comece com p=none para monitoramento, depois passe para p=quarantine e, por fim, para p=reject, assim que os relatórios estiverem validados.

4. Escolher e configurar o método de envio

Opção A: API REST

• Gere uma API key em Settings > API Keys
• Escolha as permissões (Full Access ou Domain sending keys para escopo limitado)
• Implemente o endpoint POST /v3/{domain}/messages
• Crie templates em Sending > Templates, se necessário

Opção B: SMTP Relay

• Recupere a senha SMTP do domínio em Sending > Domains > Domain settings > SMTP credentials
• Configure seu app/plugin/servidor de email:
  • Host: smtp.mailgun.org (US) ou smtp.eu.mailgun.org (EU)
  • Porta: 587 (STARTTLS recomendado)
  • Usuário: postmaster@mail.captaindns.com
  • Senha: a senha SMTP do domínio

5. Configurar os webhooks

• Acesse Sending > Webhooks
• Defina a URL do seu endpoint (HTTPS recomendado)
• Selecione os eventos (delivered, bounced, opened, clicked, etc.)
• Recupere a Webhook Signing Key para validar as assinaturas HMAC

6. Testar e monitorar

• Envie um email de teste via API ou SMTP
• Verifique em Sending > Logs se o email foi mesmo entregue
• Verifique os eventos de webhook no seu endpoint
• Acompanhe as estatísticas (entregabilidade, taxa de abertura, taxa de bounce)
• Para entrar em produção, saia do modo sandbox entrando em contato com o suporte do Mailgun (verificação de negócio)

Guias técnicos: outras plataformas de email transacional

Descubra nossos guias completos para outras soluções de email transacional:

• Postmark: configuração DKIM e API REST - Especialista em entregabilidade, DKIM 1024 bits, Message Streams
• SendGrid: autenticação de domínio e Web API v3 - DKIM 2048 bits com rotação, IP dedicado a partir de 50k/mês
• Amazon SES: Easy DKIM e Custom MAIL FROM - $0.10/1000 emails, 7 regiões EU
• Mailjet: API v3.1 e configuração DKIM - DKIM 2048/4096 bits, aquisição Sinch
• Mandrill: integração Mailchimp transacional - Requisito Mailchimp Standard, blocos de 25k emails
• Brevo: configuração DKIM e SPF - 300 emails/dia grátis, DKIM TXT ou CNAME

FAQ

Qual é a diferença entre a chave de API primária e as Domain Sending Keys?

A chave de API primária (Primary Account API Key) dá acesso CRUD completo a todas as APIs da conta. As Domain Sending Keys se limitam apenas ao envio (POST /messages) para um domínio específico. Use as Domain Sending Keys nos seus apps para reduzir a superfície de ataque em caso de comprometimento.

Por que o Mailgun gera dois seletores DKIM (pdk1 e pdk2)?

Os dois seletores permitem a rotação automática das chaves DKIM a cada 120 dias sem interrupção de serviço. Quando o Mailgun quer renovar as chaves por motivos de segurança, ele gera uma nova chave em pdk2 enquanto pdk1 ainda está ativo e depois migra o tráfego gradualmente. Isso evita qualquer interrupção de entregabilidade durante a troca de chave.

Preciso configurar um Custom MAIL FROM como no Amazon SES?

Não. Ao contrário do Amazon SES, que exige Custom MAIL FROM para o alinhamento SPF, o Mailgun usa automaticamente seu domínio verificado no Return-Path (bounce+id@mail.captaindns.com). O alinhamento SPF do DMARC funciona de forma nativa já na configuração do domínio, sem ajustes separados.

Como funciona o modo de teste sem consumir créditos?

Use o parâmetro o:testmode=yes (API) ou o cabeçalho X-Mailgun-Drop-Message: yes (SMTP). As mensagens são aceitas, mas não entregues, gerando um evento delivered com código 650. Ideal para testar a estrutura das requisições e o formato dos payloads sem enviar emails de verdade.

Qual é o limite real de destinatários por chamada de API?

1.000 destinatários no máximo por chamada (to + cc + bcc combinados). Acima disso, divida em várias chamadas. Para enviar para 10.000 pessoas, são necessárias 10 chamadas de API. Use as recipient variables para personalizar o conteúdo de cada destinatário dentro do mesmo batch.

O plano Flex é adequado para produção com volume variável?

Desde que a tarifa dobrou (2,00$/1000 emails em dezembro de 2025), o plano Flex ficou menos competitivo. Acima de 18.000 emails/mês, o plano Foundation 50k (35$/mês) compensa mais. O Flex continua interessante para volumes muito baixos e irregulares (< 10.000/mês) ou para testar antes de se comprometer.

Devo contratar um IP dedicado para o meu projeto?

Provavelmente não. Um IP dedicado exige um volume mínimo de 1 milhão de emails por mês, com envios regulares. Ele impõe um warm-up de 15+ dias e custa 59$/IP/mês adicionais (ou já vem incluído a partir do Foundation 100k). Se o seu volume for menor ou se os envios forem irregulares, fique no IP compartilhado. A reputação do Mailgun em IP compartilhado é excelente.

Os rate limits da API são documentados?

Não. O Mailgun não documenta publicamente os rate limits específicos por endpoint, exceto para a Domains API (300 req/min). Contas novas podem ficar limitadas a 100 mensagens/hora antes da verificação de negócio. Os cabeçalhos X-RateLimit-* nas respostas indicam sua cota em tempo real. Em caso de 429, implemente um backoff exponencial.

Glossário

• API REST: API HTTP do Mailgun para o envio de emails transacionais. Endpoint principal: POST /v3/{domain}/messages. Autenticação: HTTP Basic Auth (api:YOUR_API_KEY). Método recomendado para qualquer nova integração.

• SMTP Relay: servidor SMTP do Mailgun (smtp.mailgun.org) que permite enviar pelo protocolo SMTP padrão. Autenticação: SASL/PLAIN (postmaster@ + senha SMTP). Portas disponíveis: 587 (STARTTLS), 465 (TLS direto), 2525 (fallback GCE).

• Domain Verification: configuração DNS para autenticar seu domínio no Mailgun. Gera os registros SPF, DKIM e MX. Com o Automatic Sender Security: 2 CNAME DKIM (pdk1 e pdk2) para rotação automática a cada 120 dias, chaves de 2048 bits por padrão.

• Return-Path (Envelope From): endereço técnico usado para o roteamento SMTP e para os bounces. O Mailgun usa automaticamente seu domínio (bounce+id@mail.captaindns.com), o que permite o alinhamento SPF relaxed para DMARC sem configuração separada. Diferença importante em relação ao SendGrid (subdomínio em1234) e ao Amazon SES (Custom MAIL FROM obrigatório).

• Automatic Sender Security: opção recomendada para a Domain Verification. Gera 2 CNAME DKIM em vez de TXT, permite a rotação automática das chaves DKIM a cada 120 dias e usa chaves de 2048 bits por padrão.

• Recipient Variables: mecanismo para personalizar o conteúdo de cada destinatário em um envio em batch. Sintaxe: %recipient.variable% na mensagem, com um JSON que mapeia cada email às suas variáveis. Permite enviar até 1.000 versões personalizadas em uma única chamada de API.

• IP Warmup: processo automático de aumento gradual de carga de um IP dedicado novo. Cronograma em 15 etapas: de 1.000 emails/dia (D1) até a capacidade total (D15+). O sistema avança uma etapa a cada 24h se os limites forem atingidos. O tráfego excedente é roteado para os IPs compartilhados.

• IP Pools: grupos de IPs dedicados atribuíveis a fluxos diferentes (transacional vs marketing, por cliente, por marca). Disponíveis nos planos Scale e Enterprise. Permitem separar a reputação. Dynamic IP Pools: atribuição automática com base na saúde da reputação.

• Event Webhook: endpoint HTTP chamado pelo Mailgun a cada evento (accepted, delivered, opened, clicked, bounced, complained, unsubscribed). Configuração: até 3 URLs por tipo de evento. Retry durante 8h em caso de falha. Segurança: assinatura HMAC-SHA256.

• Handlebars: linguagem de templating usada pelo Mailgun para os templates armazenados. Suporta variáveis {{variable}}, condições {{#if}}, laços {{#each}} e helpers {{#equal}}. Limite: 100 templates por domínio, 10 versões por template. Sem suporte a partials.

• Sandbox Mode: modo de teste que valida o formato das requisições sem enviar email de verdade. Ativado via o:testmode=yes (API) ou X-Mailgun-Drop-Message: yes (SMTP). Gera um evento delivered com código 650. Não consome créditos. Limite: 5 destinatários verificados.

• Suppressions: listas de bloqueio mantidas automaticamente pelo Mailgun (Bounces, Complaints, Unsubscribes). Os endereços ficam suprimidos por tempo indeterminado por padrão. Gestão via API: GET/POST/DELETE /v3/{domain}/{bounces|complaints|unsubscribes}. Allowlist: impede a inclusão em Bounces, mas não sobrepõe Complaints/Unsubscribes.

• Domain Sending Keys: chaves de API limitadas apenas ao envio (POST /messages) para um domínio específico. Ao contrário da chave de API primária (acesso CRUD completo), elas reduzem a superfície de ataque. Recomendadas para apps em produção.

• RBAC API Keys (Scale+): chaves de API com papéis pré-configurados: Admin (leitura/escrita completa), Developer (acesso técnico completo), Analyst (somente leitura de métricas), Support (leitura + gestão das supressões). Disponíveis apenas nos planos Scale e Enterprise.

Fontes oficiais

• Mailgun Official Documentation
• Mailgun Pricing
• Mailgun Security & Compliance
• Mailgun API Reference