Mailgun: Guia técnico completo para email transacional
Por CaptainDNS
Publicado em 21 de janeiro de 2026
- 📢 O Mailgun utiliza o seu domínio no Return-Path (
bounce+id@oseudominio.com), permitindo o alinhamento SPF nativo para DMARC logo a partir do plano base. - A REST API é o método recomendado: até 1 000 destinatários por chamada, rate limits não documentados (exceto Domains API: 300 req/min).
- Automatic Sender Security gera 2 CNAME DKIM com rotação automática a cada 120 dias, chaves de 2048 bits por predefinição.
- IP dedicado recomendado a partir de 1 milhão de emails/mês, com warm-up automático ao longo de 15+ dias e custo adicional de 59$/IP/mês.
- Plano Flex aumentado para 2,00$/1000 emails desde dezembro de 2025 (duplicação do tarifário).
Introdução
O Mailgun impôs-se como uma das plataformas de email transacional mais robustas do mercado, processando mais de 600 mil milhões de emails por ano para mais de 100 000 clientes. Adquirido pela Sinch em dezembro de 2021 por 1,9 mil milhões de dólares, o serviço combina uma REST API potente, um relay SMTP universal e funcionalidades de autenticação avançadas que o distinguem da concorrência.
A força do Mailgun assenta em três pilares técnicos principais: uma abordagem API-first orientada para programadores, uma Domain Verification que utiliza o seu próprio domínio para o Return-Path (alinhamento SPF nativo para DMARC), e um sistema de rotação automática das chaves DKIM 2048 bits a cada 120 dias sem interrupção de serviço.
Este guia destina-se a programadores, DevOps e arquitetos de sistemas que procuram integrar o Mailgun para email transacional com uma compreensão completa da infraestrutura: configuração DNS, escolha entre API e SMTP, gestão dos IP dedicados, limites técnicos e webhooks de eventos.
REST API vs SMTP Relay: arquitetura e escolha de integração
O Mailgun propõe dois métodos de integração para email transacional, ambos disponíveis desde o plano gratuito (100 emails/dia).
Comparativo técnico
| Critério | REST API | 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@ + password 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 ligação SMTP |
| Templates | Variáveis com sintaxe {{variable}} | Via header X-Mailgun-Variables |
| Scheduling | o:deliverytime (até 3 dias, 7 dias se storage 7d+) | Via header X-Mailgun-Deliver-By |
| Tracking | Nativo (o:tracking, o:track-clicks, o:track-opens) | Via headers X-Mailgun-Track* |
| Compatibilidade | Requer SDK ou cliente HTTP | Qualquer sistema compatível com SMTP |
| Caso de uso ideal | Apps modernas, batch, personalização avançada | Legacy, plugins CMS, servidores de mail |
Quando escolher a REST API?
A REST API é o método recomendado pelo Mailgun para qualquer nova integração. Está acessível em POST https://api.mailgun.net/v3/{domain}/messages para a região US, ou em api.eu.mailgun.net para a UE.
Vantagens principais:
- Batch sending: envio até 1 000 destinatários num único pedido, com personalização através de recipient variables
- Templates armazenados: sintaxe Handlebars com condições, ciclos e helpers personalizados
- Scheduling: programação de envio até 3 dias de antecedência (7 dias se o plano incluir 7 ou mais dias de storage)
- Rate limit headers:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Resetpara monitorização
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}}, 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'
SDK oficiais: o Mailgun mantém SDK para Go, Node.js, PHP, Python, Ruby e Java que encapsulam a REST API e simplificam a integração.
Quando escolher o SMTP Relay?
O SMTP Relay é ideal para sistemas legacy ou para aplicações que apenas suportam SMTP.
Configuração oficial:
SMTP server: smtp.mailgun.org (US) ou smtp.eu.mailgun.org (UE)
SMTP user: postmaster@mail.captaindns.com (ou utilizador SMTP personalizado)
SMTP password: [palavra-passe SMTP do dominio]
Port: 587 (STARTTLS recomendado) ou 465 (TLS direto) ou 2525 (fallback GCE)
Ponto crítico: a autenticação SMTP utiliza a palavra-passe SMTP do domínio, distinta da chave API. O username é o endereço postmaster@ do domínio verificado (ou um utilizador SMTP personalizado criado no painel).
Headers proprietários X-Mailgun-*: permitem aceder às funcionalidades avançadas através de SMTP (tags, tracking, templates, scheduling, variáveis). Lista completa:
X-Mailgun-Tag: tag para estatísticas (vários possíveis)X-Mailgun-Track: ativar/desativar o tracking globalX-Mailgun-Track-Clicks: tracking de cliques (yes/no/htmlonly)X-Mailgun-Track-Opens: tracking de aberturas (yes/no)X-Mailgun-Deliver-By: planeamento (formato RFC 2822 ou timestamp Unix)X-Mailgun-Template-Name: nome do template a utilizarX-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 registos necessários para SPF, DKIM e o alinhamento DMARC. O processo é efetuado 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 registos CNAME DKIM para a rotação automática das chaves:
Registos necessários (exemplo para mail.captaindns.com):
| Tipo | Name/Host | Valor | 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 região UE: para a UE, os registos MX utilizam mxa.eu.mailgun.org e mxb.eu.mailgun.org.
Vantagens desta arquitetura:
- Rotação automática das chaves DKIM: os dois seletores (
pdk1epdk2) permitem ao Mailgun mudar as chaves a cada 120 dias sem interrupção de serviço - Chaves DKIM de 2048 bits por predefinição (as configurações manuais em TXT podem usar 1024 bits, mas recomenda-se 2048)
- Nenhum registo CNAME de tracking necessário por predefinição: o Mailgun utiliza
mailgun.org(oueu.mailgun.orgpara a UE) - Seletores DKIM:
pdk1epdk2para o Automatic Security, oumxpara a configuração manual em TXT
Return-Path e alinhamento SPF: uma vantagem determinante
O Return-Path (Envelope From) é crucial para o alinhamento DMARC. O Mailgun utiliza automaticamente o seu domínio no Return-Path, no formato bounce+UNIQUEID@mail.captaindns.com:
- O SPF passa automaticamente, porque o registo
include:mailgun.orgautoriza os IP do Mailgun a enviar em nome do seu domínio - O alinhamento SPF funciona em modo relaxed (o Return-Path
bounce+id@mail.captaindns.comcorresponde ao domínio paimail.captaindns.com) - Sem necessidade de configuração separada: ao contrário de outros fornecedores, o Mailgun não exige um subdomínio dedicado para o bounce domain
Diferença face à concorrência:
- SendGrid: utiliza um subdomínio personalizável (
em1234.captaindns.com) - Amazon SES: exige Custom MAIL FROM para o alinhamento SPF
- Mailgun: utiliza diretamente o domínio verificado
Com uma política DMARC estrita (aspf=s), o alinhamento SPF falha se o envio for feito a partir de um subdomínio diferente do Return-Path. A solução passa por apoiar-se no DKIM para o alinhamento DMARC, que suporta o modo estrito (adkim=s).
Tracking domain (link branding)
O tracking domain substitui os domínios do Mailgun nas ligações rastreadas pelo seu próprio domínio. Por predefinição, o Mailgun utiliza email.mail.captaindns.com a apontar para mailgun.org (US) ou eu.mailgun.org (UE) através de CNAME.
Configuração opcional HTTPS: o Mailgun gera automaticamente um certificado Let's Encrypt assim que o CNAME é verificado.
Migração para DKIM 2048 bits
Para migrar uma configuração TXT manual (chaves de 1024 bits) para Automatic Sender Security (2048 bits), basta ativar o Automatic Sender Security no painel e criar depois os 2 novos CNAME DKIM. A transição é fluida graças aos dois seletores.
Fluxo de autenticação de email: da API à entregabilidade
Ao enviar através do Mailgun:
- A sua aplicação chama a REST API ou utiliza SMTP
- O Mailgun assina a mensagem com a sua chave DKIM (domínio
d=mail.captaindns.com) - O Mailgun utiliza o seu domínio no Return-Path (
bounce+id@mail.captaindns.com) - O servidor destinatário verifica o SPF (IP de envio), o DKIM (assinatura) e depois o DMARC (alinhamento)
- O SPF passa:
include:mailgun.orgautoriza os IP do Mailgun, o Return-Path utiliza o seu domínio - O DKIM passa: a assinatura
d=mail.captaindns.comcorresponde ao header From - O DMARC passa: pelo menos SPF E DKIM estão alinhados (dupla validação)
Alinhamento DMARC: configuração para p=reject
O que funciona (e o que falha)
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 utiliza o seu domínio (nativo) | Sim | Sim |
| aspf=r (relaxed, predefinição) | Sim | Sim |
| aspf=s (strict) + envio a partir de subdomínio | Não | Não (mismatch de subdomínio) |
Registo DMARC recomendado
_dmarc.captaindns.com TXT "v=DMARC1;p=reject;adkim=r;aspf=r;rua=mailto:dmarc@captaindns.com"
Pontos-chave:
adkim=reaspf=r: alinhamento relaxed (autoriza os subdomínios)- Progredir de
p=none→p=quarantine→p=reject - Vigiar os relatórios
ruaantes de endurecer a política - Vantagem Mailgun: duplo alinhamento (SPF + DKIM) nativo, melhor proteção do que apenas com DKIM
Tabela recapitulativa DNS completa
| Tipo | Host/Name | Valor | Obrigatório | Notas |
|---|---|---|---|---|
| TXT | mail.captaindns.com | v=spf1 include:mailgun.org ~all | ✅ Sim | SPF idêntico US/UE |
| CNAME | pdk1._domainkey.mail.captaindns.com | pdk1._domainkey.XXXX.dkim1.mailgun.com | ✅ Sim | Rotação DKIM auto |
| CNAME | pdk2._domainkey.mail.captaindns.com | pdk2._domainkey.XXXX.dkim1.mailgun.com | ✅ Sim | Rotação DKIM auto |
| 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 partilhado: estratégia de entregabilidade
O Mailgun recomenda oficialmente um IP dedicado a partir de 1 milhão de emails por mês. Abaixo desse volume, o IP partilhado oferece geralmente melhor entregabilidade.
IP partilhado (planos Free, Foundation e Growth de base)
Vantagens:
- Não é necessário qualquer warm-up
- Reputação mantida pelo Mailgun
- Ideal para volumes baixos ou irregulares
- Melhor entregabilidade inicial do que num IP dedicado ainda frio
Inconvenientes:
- Exposição aos riscos de reputação ligados aos outros remetentes do pool (raro no Mailgun, graças aos controlos 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 ao longo de 15 etapas (~15+ dias)
- Possibilidade de separar os fluxos (transacional vs marketing) através de IP Pools
IP Warmup automático: o Mailgun propõe um warm-up em 15 etapas progressivas:
| Etapa | Limite diário | Limite horário | Duração |
|---|---|---|---|
| 1 | 1 000 | 100 | 24h |
| 2 | 2 500 | ~100 | 24h |
| 3 | 5 000 | Progressivo | 24h |
| ... | Progressivo | Progressivo | ... |
| 15 | Capacidade total | Sem limite | Atingido no D15+ |
O sistema avança uma etapa a cada 24 horas se os limites forem atingidos. O tráfego excedente é encaminhado automaticamente para os IP partilhados ou para outros IP dedicados disponíveis.
IP Pools: disponíveis nos planos Scale e superiores. Permitem:
- Separar emails transacionais e de marketing
- Distinguir clientes/marcas (multi-tenant)
- Dynamic IP Pools: atribuição automática com base na saúde da reputação
Nota importante: os IP dedicados estão associados a uma região (US ou UE). Uma migração de região exige um novo IP e um novo warm-up.
Quando escolher um IP dedicado?
É necessário um IP dedicado se:
- O volume regular for superior a 1 milhão de emails/mês
- For preciso separar a reputação transacional da de marketing
- Existirem exigências de whitelisting por parte do cliente ou de conformidade regulamentar
- O volume ultrapassar 2,5 milhões de emails/mês: recomendam-se vários IP dedicados
Convém manter o IP partilhado se:
- O volume for inferior a 1 milhão de emails/mês
- Os envios forem irregulares ou esporádicos
- A atividade estiver a arrancar, sem histórico
- O tráfego for puramente transacional e de baixo volume
Tarifário 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/D | 1 dia | Não |
| Flex | Pay-per-use | 1 000 gratuitos/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
⚠️ Alteração importante (1 de dezembro de 2025): o plano Flex passou de 1,00 $ para 2,00 $ por cada 1 000 emails, um aumento de 100%. Esta subida significativa torna os planos Foundation muito mais atrativos para volumes superiores a 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 $ (poupança de 63 $)
- Limiar de rentabilidade: o plano Foundation torna-se rentável a partir de cerca 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 estão documentados publicamente. Os clientes Enterprise referem descontos de 10%+ negociáveis.
Tarifário US vs UE
O tarifário é normalizado a nível mundial em USD. Não há diferença regional documentada entre US e UE.
Limites técnicos e quotas
| Limite | Valor | Notas |
|---|---|---|
| Tamanho máx. 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 rigoroso |
| Versões/template | 10 | - |
| Domínios (Free) | 5 | - |
| Domínios (pago) | 1 000 | - |
| Destinatários sandbox | 5 | Têm de estar verificados |
| Rate limit Domains API | 300 req/min | Único endpoint documentado |
| Rate limit de envio (contas novas) | 100 mensagens/hora | Antes da verificação de negócio |
| Scheduling máx. | 3 dias | 7 dias com plano de storage 7d+ |
Retenção de dados
| Dados | 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 horárias | 60 dias |
| Estatísticas diárias | 1 ano |
| Estatísticas mensais | Indefinido |
| 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é remoção manual) |
| Erro devolvido | "Not delivering to previously bounced address" |
Soft bounce (falha temporária)
| Comportamento | Detalhe |
|---|---|
| Retry | Automático para os soft bounces imediatos |
| Duração | Até ao sucesso ou à classificação como permanente |
| Conversão | Após várias falhas, adição à lista de bounces |
Spam complaints (FBL)
O Mailgun inscreve-se automaticamente nos Feedback Loops dos principais operadores. As queixas desencadeiam:
- Adição automática à lista Complaints
- Envio do webhook
complained - Bloqueio dos envios futuros para esse endereço
Operadores suportados: Yahoo, Microsoft/Outlook, Comcast, Cox, Fastmail e outros através do Universal Feedback Loop. Nota: o Gmail não fornece um FBL tradicional.
Unsubscribe automático
O Mailgun adiciona automaticamente:
- Cabeçalho
List-Unsubscribe - 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 que endereços sejam adicionados à lista de bounces, mas não se sobrepõe às Complaints nem às Unsubscribes.
Event Webhook e tracking em tempo real
O webhook de eventos permite receber em tempo real as notificações de entrega, envolvimento e conformidade.
Eventos disponíveis
- Entrega:
accepted,delivered,temporary_fail,permanent_fail - Envolvimento:
opened,clicked - Conformidade:
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"
}
}
}
}
Retry policy
| Código de resposta | Ação |
|---|---|
| 200 | Sucesso, sem retry |
| 406 | Rejeitado, sem retry |
| Outro | Retry segundo o calendário |
Calendário 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 URL por tipo de evento e por domínio
- Configuração ao nível do domínio (não da conta)
- API:
POST /v3/domains/{domain}/webhooks
Templates Handlebars
O Mailgun utiliza 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 ciclos
{{#if condicao}}
Conteudo se verdadeiro
{{else if outraCondicao}}
Conteudo alternativo
{{else}}
Conteudo predefinido
{{/if}}
{{#unless condicao}}
Conteudo se falso
{{/unless}}
{{#equal variavel "valor"}}
Conteudo se igual
{{/equal}}
{{#each tabela}}
<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) | Não suportado |
Funcionalidades adicionais
Email Validation API
| Atributo | Valor |
|---|---|
| Endpoint single | GET /v4/address/validate?address=... |
| Endpoint bulk | POST /v4/address/validate/bulk/{list_id} |
| Base de dados | 450+ mil milhões de emails |
| Tarifa Foundation | 1,20 $/100 validações |
| Tarifa Scale | 5 000 incluídas, depois 0,80 $/100 |
Validações efetuadas: sintaxe RFC, registos MX, existência da mailbox, bounces da rede Mailgun, endereços de risco, endereços role-based, emails descartáveis, gralhas de domínio, domínios catch-all.
Inbound Parse (Routes)
Permite receber emails e encaminhá-los para um 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
Anexos
| Limite | Valor |
|---|---|
| Tamanho total da mensagem | 25 MB (corpo + anexos + headers) |
| Tipos de ficheiro | Sem restrição documentada |
| Inline (CID) | Suportado através do parâmetro inline |
AMP for Email
Suportado desde 2019 através do parâmetro amp-html. Exige:
- Registo como remetente AMP junto da Google
- SPF, DKIM e DMARC configurados
- Fallback HTML obrigatório
Segurança e conformidade
Certificações
| Certificação | Estado |
|---|---|
| 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 |
RGPD
| Elemento | Detalhe |
|---|---|
| DPA | Disponível: mailgun.com/legal/dpa/ |
| Localização dos dados UE | Alemanha |
| Endpoints UE | api.eu.mailgun.net, smtp.eu.mailgun.org |
| Residência dos dados | As mensagens nunca são transferidas para fora da região |
| DPO | Dedicado, sediado na UE |
HIPAA
| Elemento | Detalhe |
|---|---|
| Estado | ✅ Conforme |
| BAA | Disponível: mailgun.com/legal/hipaa-baa/ |
| Pré-requisitos | Configuração de encriptação do lado do cliente, consentimento do paciente, assinatura do BAA |
Encriptação TLS
| Versão | Estado |
|---|---|
| TLS 1.0 | ❌ Descontinuado (março de 2021) |
| TLS 1.1 | ❌ Descontinuado (março de 2021) |
| TLS 1.2 | ✅ Suportado |
| TLS 1.3 | ✅ Suportado |
Encriptação em repouso: AES-256
Autenticação avançada
| Funcionalidade | 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 passos
1. Criar a conta e configurar o domínio
- Criar uma conta Mailgun em mailgun.com/signup
- Escolher a região (US ou UE, consoante as necessidades de RGPD)
- É criado automaticamente um domínio sandbox (100 emails/dia)
2. Verificar o domínio (Domain Verification)
- Aceder a Sending > Domains > Add New Domain
- Introduzir o domínio de envio (por exemplo,
mail.captaindns.com) - Ativar o Automatic Sender Security (recomendado)
- Criar os registos DNS no registrar:
- TXT SPF:
v=spf1 include:mailgun.org ~all - CNAME DKIM pdk1:
pdk1._domainkey.mail.captaindns.com - CNAME DKIM pdk2:
pdk2._domainkey.mail.captaindns.com - MX mxa:
mxa.mailgun.org(prioridade 10) - MX mxb:
mxb.mailgun.org(prioridade 10)
- TXT SPF:
- Verificar a propagação DNS (24-48h)
3. Publicar o registo DMARC
Criar o registo DMARC no domínio principal:
_dmarc.captaindns.com TXT "v=DMARC1;p=none;rua=mailto:dmarc@captaindns.com;aspf=r;adkim=r"
Começar por p=none para monitorização, passar depois a p=quarantine e finalmente a p=reject assim que os relatórios estiverem validados.
4. Escolher e configurar o método de envio
Opção A: REST API
- Gerar uma API key em Settings > API Keys
- Escolher as permissões (Full Access ou Domain sending keys para âmbito limitado)
- Implementar o endpoint
POST /v3/{domain}/messages - Criar templates em Sending > Templates, se necessário
Opção B: SMTP Relay
- Obter a palavra-passe SMTP do domínio em Sending > Domains > Domain settings > SMTP credentials
- Configurar a aplicação, o plugin ou o servidor de mail:
- Host:
smtp.mailgun.org(US) ousmtp.eu.mailgun.org(UE) - Porta:
587(STARTTLS recomendado) - User:
postmaster@mail.captaindns.com - Password: a palavra-passe SMTP do domínio
- Host:
5. Configurar os webhooks
- Aceder a Sending > Webhooks
- Definir o URL do endpoint (HTTPS recomendado)
- Selecionar os eventos (delivered, bounced, opened, clicked, etc.)
- Obter a Webhook Signing Key para validar as assinaturas HMAC
6. Testar e monitorizar
- Enviar um email de teste através da API ou de SMTP
- Confirmar em Sending > Logs que o email foi entregue
- Verificar os eventos de webhook no seu endpoint
- Controlar as estatísticas (entregabilidade, taxa de abertura, taxa de bounce)
- Para passar a produção, sair do modo sandbox contactando o suporte do Mailgun (verificação de negócio)
Guias técnicos: outras plataformas de email transacional
Conheça os nossos guias completos para outras soluções de email transacional:
- Postmark: configuração DKIM e REST API - 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 UE
- Mailjet: API v3.1 e configuração DKIM - DKIM 2048/4096 bits, aquisição pela Sinch
- Mandrill: integração Mailchimp transacional - Requer Mailchimp Standard, blocos de 25k emails
- Brevo: configuração DKIM e SPF - 300 emails/dia gratuitos, DKIM TXT ou CNAME
FAQ
Qual a diferença entre a chave API primária e as Domain Sending Keys?
A chave API primária (Primary Account API Key) dá acesso CRUD completo a todas as API da conta. As Domain Sending Keys estão limitadas ao envio (POST /messages) para um domínio específico. Convém usar as Domain Sending Keys nas aplicações, para limitar a superfície de ataque em caso de comprometimento.
Porque é 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 pretende renovar as chaves por razões de segurança, gera uma nova chave em pdk2 enquanto pdk1 ainda está ativo, passando depois o tráfego progressivamente. Isto evita qualquer interrupção da entregabilidade durante a mudança 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 utiliza automaticamente o domínio verificado no Return-Path (bounce+id@mail.captaindns.com). O alinhamento SPF para DMARC funciona nativamente logo após a configuração do domínio, sem qualquer configuração adicional.
Como funciona o modo de teste sem consumir créditos?
Basta usar o parâmetro o:testmode=yes (API) ou o header X-Mailgun-Drop-Message: yes (SMTP). As mensagens são aceites mas não entregues, gerando um evento delivered com o código 650. Ideal para testar a estrutura dos pedidos e o formato dos payloads sem enviar emails de verdade.
Qual é o limite real de destinatários por chamada à API?
1 000 destinatários no máximo por chamada (to + cc + bcc combinados). Acima disso, é preciso dividir em várias chamadas. Para enviar para 10 000 pessoas são necessárias 10 chamadas à API. As recipient variables permitem personalizar o conteúdo de cada destinatário dentro do mesmo batch.
O plano Flex é adequado para produção com volume variável?
Desde a duplicação do tarifário (2,00$/1000 emails em dezembro de 2025), o plano Flex tornou-se menos competitivo. Acima de 18 000 emails/mês, o plano Foundation 50k (35$/mês) é mais rentável. O Flex continua interessante para volumes muito baixos e irregulares (menos de 10 000/mês) ou para testar antes de assumir um compromisso.
Vale a pena adotar 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. Impõe um warm-up de 15 ou mais dias e custa 59$/IP/mês adicionais (ou vem incluído a partir do Foundation 100k). Se o volume for inferior ou se os envios forem irregulares, convém manter o IP partilhado. A reputação do Mailgun em IP partilhado é excelente.
Os rate limits da API estão documentados?
Não. O Mailgun não documenta publicamente os rate limits específicos por endpoint, exceto no caso da API Domains (300 req/min). As contas novas podem estar limitadas a 100 mensagens/hora antes da verificação de negócio. Os headers X-RateLimit-* nas respostas indicam a quota em tempo real. Em caso de 429, convém implementar um backoff exponencial.
Glossário
-
REST API: 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 através do protocolo SMTP padrão. Autenticação: SASL/PLAIN (postmaster@ + palavra-passe SMTP). Portas disponíveis: 587 (STARTTLS), 465 (TLS direto), 2525 (fallback GCE). -
Domain Verification: configuração DNS para autenticar o domínio junto do Mailgun. Gera os registos SPF, DKIM e MX. Com Automatic Sender Security: 2 CNAME DKIM (pdk1 e pdk2) para rotação automática a cada 120 dias, chaves de 2048 bits por predefinição.
-
Return-Path (Envelope From): endereço técnico usado no encaminhamento SMTP e nos bounces. O Mailgun utiliza automaticamente o seu domínio (
bounce+id@mail.captaindns.com), permitindo o alinhamento SPF relaxed para DMARC sem configuração separada. Diferença importante face ao SendGrid (subdomínioem1234) 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 utiliza chaves de 2048 bits por predefinição.
-
Recipient Variables: mecanismo para personalizar o conteúdo de cada destinatário num envio em batch. Sintaxe:
%recipient.variable%na mensagem, com um JSON que associa cada email às respetivas variáveis. Permite enviar até 1 000 versões personalizadas numa única chamada à API. -
IP Warmup: processo automático de subida de carga de um IP dedicado novo. Calendário em 15 etapas: de 1 000 emails/dia (D1) até à capacidade total (D15+). O sistema avança uma etapa a cada 24h se os limites forem atingidos. O tráfego excedente é encaminhado para os IP partilhados.
-
IP Pools: grupos de IP dedicados atribuíveis a fluxos distintos (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 invocado pelo Mailgun em cada evento (accepted, delivered, opened, clicked, bounced, complained, unsubscribed). Configuração: até 3 URL por tipo de evento. Retry durante 8h em caso de falha. Segurança: assinatura HMAC-SHA256.
-
Handlebars: linguagem de templating utilizada pelo Mailgun para os templates armazenados. Suporta variáveis
{{variable}}, condições{{#if}}, ciclos{{#each}}e helpers{{#equal}}. Limite: 100 templates por domínio, 10 versões por template. Sem suporte para partials. -
Sandbox Mode: modo de teste que valida o formato dos pedidos sem enviar emails de verdade. Ativa-se com
o:testmode=yes(API) ouX-Mailgun-Drop-Message: yes(SMTP). Gera um eventodeliveredcom o 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 são suprimidos por tempo indefinido por predefinição. Gestão através da API:
GET/POST/DELETE /v3/{domain}/{bounces|complaints|unsubscribes}. Allowlist: impede a adição à lista Bounces, mas não se sobrepõe a Complaints nem a Unsubscribes. -
Domain Sending Keys: chaves API limitadas ao envio (POST /messages) para um domínio específico. Ao contrário da chave API primária (acesso CRUD completo), reduzem a superfície de ataque. Recomendadas para aplicações em produção.
-
RBAC API Keys (Scale+): chaves API com funções predefinidas: Admin (leitura/escrita completa), Developer (acesso técnico completo), Analyst (apenas leitura de métricas), Support (leitura + gestão das supressões). Disponíveis apenas nos planos Scale e Enterprise.
