Twilio SendGrid: Guia técnico completo para email transacional

⚡Resumo

• 📢 SendGrid utiliza um Return-Path personalizável (subdomínio do seu domínio), permitindo o alinhamento SPF em modo relaxed para DMARC desde o plano base.
• A Web API v3 é o método recomendado: 10 000 pedidos/segundo, até 1 000 destinatários por chamada, Dynamic Templates com Handlebars.
• Domain Authentication com Automated Security gera 3 CNAME: Return-Path + 2 seletores DKIM (rotação automática, chaves 2048 bits).
• IP dedicado recomendado a partir de 50 000 emails/mês, com warm-up automático de 41 dias e custo de 30$/mês por IP adicional.
• Plano Free removido em maio de 2025: migração obrigatória para Essentials 50K a 19,95$/mês mínimo.

Introdução

SendGrid estabeleceu-se como uma das plataformas de email transacional mais robustas do mercado, processando mais de 190 mil milhões de emails mensais em 2024. Adquirido pela Twilio em 2019 por cerca de 3 mil milhões de dólares, o serviço combina uma API REST potente, um relay SMTP universal e funcionalidades de autenticação avançadas que o distinguem da concorrência.

A força do SendGrid reside em três pilares técnicos principais: uma Web API v3 capaz de gerir 10 000 pedidos/segundo, uma Domain Authentication que permite o alinhamento SPF DMARC desde o plano base, e um sistema de rotação automática de chaves DKIM 2048 bits sem interrupção de serviço.

Este guia destina-se a programadores, DevOps e arquitetos de sistemas que procuram integrar SendGrid para email transacional com uma compreensão completa da infraestrutura: configuração DNS, escolha API vs SMTP, gestão de IPs dedicados, limites técnicos e webhooks de eventos.

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

SendGrid propõe dois métodos de integração para email transacional, ambos disponíveis desde os planos pagos.

Comparativo técnico

Critério	Web API v3	SMTP Relay
Endpoint	POST https://api.sendgrid.com/v3/mail/send	smtp.sendgrid.net portas 587/465
Autenticação	Bearer token (API key)	User: apikey / Pass: API key
Rate limit	10 000 pedidos/segundo	Depende do IP e do plano
Destinatários/req	Até 1 000 (personalizations)	1 email = 1 conexão SMTP
Templates	Dynamic Templates (Handlebars)	Conteúdo inline apenas
Scheduling	send_at (até 72h antecipadamente)	Via header X-SMTPAPI
Tracking	Nativo (click, open, Google Analytics)	Via X-SMTPAPI
Compatibilidade	Requer SDK ou cliente HTTP	Qualquer sistema compatível SMTP
Caso de uso ideal	Apps modernas, batch, personalização avançada	Legacy, plugins CMS, servidores mail

Quando escolher Web API v3?

A Web API v3 é o método recomendado pela SendGrid para qualquer nova integração. É acessível em POST https://api.sendgrid.com/v3/mail/send (ou api.eu.sendgrid.com para a região EU).

Vantagens principais:

• Personalizations: envio de até 1 000 destinatários num único pedido, cada um recebendo conteúdo personalizado diferente
• Dynamic Templates: sintaxe Handlebars com condições, ciclos, comparações, formatação de datas
• Scheduling: programação de envio até 72 horas antecipadamente com possibilidade de cancelamento
• Rate limit generoso: 10 000 pedidos/segundo no endpoint mail/send

Exemplo de envio com personalização:

{
  "personalizations": [{
    "to": [{"email": "utilizador@captaindns.com", "name": "João Silva"}],
    "dynamic_template_data": {
      "nome": "João",
      "numero_encomenda": "ORD-12345",
      "valor": "149,90 €"
    }
  }],
  "from": {"email": "encomendas@captaindns.com"},
  "template_id": "d-abc123def456"
}

SDKs oficiais: SendGrid mantém 7 SDKs oficiais (Node.js, Python, PHP, Ruby, Go, Java, C#) que encapsulam a API REST e simplificam a integração.

Quando escolher SMTP Relay?

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

Configuração oficial:

SMTP server: smtp.sendgrid.net
SMTP user: apikey (literalmente a string "apikey")
SMTP password: [a sua chave API SendGrid]
Port: 587 (TLS recomendado) ou 465 (SSL) ou 2525 (fallback)

Ponto crítico: a autenticação SMTP utiliza uma configuração específica. O nome de utilizador é literalmente a string apikey (não o seu identificador de conta), e a palavra-passe é a sua chave API SendGrid.

Header X-SMTPAPI: permite aceder a funcionalidades avançadas via SMTP (categories, unique_args, filtros, scheduling, tags de substituição). Tamanho máximo: 10 000 bytes.

Exemplo de header X-SMTPAPI para tracking:

{
  "category": ["confirmacao_encomenda"],
  "unique_args": {
    "order_id": "ORD-12345",
    "customer_id": "CUST-789"
  },
  "filters": {
    "clicktrack": {"settings": {"enable": 1}},
    "opentrack": {"settings": {"enable": 1}}
  }
}

Domain Authentication: SPF, DKIM 2048 bits e alinhamento DMARC

A autenticação de domínio no SendGrid gera os registos DNS necessários para SPF, DKIM e o alinhamento DMARC. O processo efetua-se em Settings > Sender Authentication > Domain Authentication.

Arquitetura com Automated Security (recomendado)

Com a opção Automated Security ativada, SendGrid gera 3 registos CNAME:

1. CNAME para Return-Path: em1234.captaindns.com apontando para SendGrid
2. CNAME DKIM s1: s1._domainkey.captaindns.com → s1.domainkey.u1234.wl5678.sendgrid.net
3. CNAME DKIM s2: s2._domainkey.captaindns.com → s2.domainkey.u1234.wl5678.sendgrid.net

Vantagens desta arquitetura:

• Rotação automática de chaves DKIM: os dois seletores (s1 e s2) permitem ao SendGrid alterar as chaves sem interrupção de serviço
• Chaves DKIM 2048 bits por defeito desde maio de 2021 (configurações anteriores podem usar 1024 bits)
• Nenhum registo SPF manual requerido: o CNAME delega a gestão SPF ao SendGrid
• Seletores personalizáveis: 1-3 caracteres alfanuméricos nos parâmetros avançados

Return-Path e alinhamento SPF: uma vantagem importante

O Return-Path (Envelope From) é crucial para o alinhamento DMARC. Por defeito, SendGrid utiliza um subdomínio no formato em[XXX].captaindns.com:

• SPF passa automaticamente porque o CNAME delega a gestão SPF ao SendGrid
• O alinhamento SPF funciona em modo relaxed (o subdomínio em1234.captaindns.com corresponde ao domínio pai captaindns.com)
• Não é necessário modificar o seu SPF principal: o CNAME gere tudo

Contudo, para uma política DMARC estrita (aspf=s), o alinhamento SPF falhará porque o domínio Return-Path nunca corresponderá exatamente ao domínio From. A solução é apoiar-se em DKIM para o alinhamento DMARC, que suporta o modo estrito (adkim=s).

Custom Return Path

A opção Custom Return Path nos parâmetros avançados permite personalizar o subdomínio (por exemplo mail.captaindns.com em vez de em1234.captaindns.com).

Link Branding

O Link Branding substitui os domínios SendGrid nas ligações rastreadas pelo seu próprio domínio. Em vez de sendgrid.net/click/xxx, as ligações mostrarão url1234.captaindns.com/click/xxx. Esta configuração necessita de 2 registos CNAME adicionais e melhora a confiança dos destinatários.

Migração para DKIM 2048 bits

Para migrar uma configuração anterior (chaves 1024 bits) para 2048 bits, é necessário criar uma nova autenticação de domínio com um novo seletor personalizado não utilizado anteriormente.

IP dedicado vs IP partilhado: estratégia de deliverability

SendGrid recomenda oficialmente um IP dedicado a partir de 50 000 emails por mês. Além de 200 000-300 000 emails mensais, dois IPs dedicados são aconselhados.

IP partilhado (planos Free e Essentials)

Vantagens:

• Nenhum warm-up necessário
• Reputação mantida pela SendGrid
• Ideal para volumes baixos ou irregulares

Desvantagens:

• Exposição a riscos de reputação relacionados com outros remetentes do pool
• Problemas de blocklist frequentes no Microsoft/Outlook

IP dedicado (plano Pro e superior)

O plano Pro inclui 1 IP dedicado, com possibilidade de adicionar a 30$/mês por IP adicional.

Vantagens:

• Reputação isolada e controlável
• Função de IP Warmup automático durante 41 dias
• Possibilidade de separar os fluxos (transacional vs marketing)

IP Warmup automático: limita progressivamente os envios segundo um calendário predefinido:

• Dia 1: 20 emails/hora
• Dia 41: Mais de 19 milhões/hora

IP Pools: permitem agrupar vários IPs dedicados e atribuí-los a diferentes fluxos. A separação é reforçada pelos Subusers (subcontas isoladas com as suas próprias estatísticas, listas de supressão e webhooks).

Subusers: os planos Pro e Premier suportam até 15 subusers por conta.

Quando escolher um IP dedicado?

Necessita de um IP dedicado se:

• Volume regular > 50 000 emails/mês
• Necessidade de separar reputação transacional vs marketing
• Exigências de whitelisting de cliente ou conformidade regulamentar
• Volume > 200 000 emails/mês: 2 IPs dedicados recomendados

Permaneça em IP partilhado se:

• Volume < 50 000 emails/mês
• Envios irregulares ou esporádicos
• Início de atividade sem histórico

Tarifário 2025 e evolução do plano Free

Planos Email API

Plano	Volume mensal	Preço/mês	IP dedicado	Subusers
Free	100/dia (60d)	Gratuito	Não	Não
Essentials 50K	50 000	19,95$	Não	Não
Essentials 100K	100 000	34,95$	Não	Não
Pro 100K	100 000	89,95$	1 incluído	Até 15
Pro 300K	300 000	249$	1 incluído	Até 15
Pro 700K	700 000	499$	1 incluído	Até 15
Premier	Personalizado	Sob consulta	1 incluído	Até 15

Evolução importante: Em maio de 2025, SendGrid anunciou a supressão do plano Free com um período de transição de 60 dias. Os utilizadores devem migrar para um plano pago para continuar a enviar emails.

Custos adicionais

• IP dedicado adicional: 30$/mês
• Email Validation API: 2 500 validações/mês incluídas (Pro), 5 000 (Premier), depois tarifação por uso
• Inbound Parse: incluído em todos os planos pagos
• Excedentes: faturados pro-rata (~0,001$/email em Pro)

Limites técnicos e rate limits

Rate limits por endpoint

Endpoint	Limite
v3 Mail Send	10 000 pedidos/segundo
API geral	600 pedidos/minuto
Email Validation	7 pedidos/segundo

Quando o limite é atingido, a API retorna um código HTTP 429. Os headers X-RateLimit-Remaining e X-RateLimit-Reset indicam a quota restante e o timestamp de reinicialização.

Gestão recomendada: backoff exponencial e colocação em fila de espera local.

Quotas por mensagem

Parâmetro	Limite
Tamanho máximo email	30 MB
Destinatários por mensagem	1 000
Categories por mensagem	10
Custom args	< 10 000 bytes
Grupos de unsubscribe	200 por conta

Gestão de supressões

SendGrid mantém automaticamente várias listas de supressão:

• Global Suppressions: cancelamentos de subscrição globais
• Group Unsubscribes: via ASM (Advanced Suppression Manager)
• Bounces: hard e soft
• Spam Reports
• Invalid Emails

Os endereços são suprimidos indefinidamente por defeito, com opção de purga configurável de 1 a 3650 dias para bounces.

Event Webhook e tracking em tempo real

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

Eventos disponíveis

• Delivery: processed, dropped, delivered, deferred, bounce
• Engagement: open, click, spamreport, unsubscribe
• ASM: group_unsubscribe, group_resubscribe

Comportamento e retry

Os eventos são enviados por lote nos 30 segundos ou quando o lote atinge 768 KB. Em caso de falha (resposta não-2xx), SendGrid tenta novamente durante 24 horas com intervalos crescentes.

Segurança

A segurança do webhook pode ser assegurada por:

• Assinatura ECDSA: headers X-Twilio-Email-Event-Webhook-Signature e X-Twilio-Email-Event-Webhook-Timestamp
• OAuth 2.0 Client Credentials

Requisito: endpoint deve suportar TLS 1.2 mínimo.

Inbound Parse

O Inbound Parse permite receber e processar emails recebidos. A configuração necessita de um registo MX apontando para mx.sendgrid.net num subdomínio dedicado.

SendGrid extrai automaticamente:

• Headers
• Corpo (text e HTML)
• Anexos
• Pontuação de spam (opcional)

Casos de uso: sistemas de ticketing, workflows de comunicação bidirecional.

Funcionalidades avançadas

Email Validation API

Disponível apenas em planos Pro e Premier. Utiliza machine learning treinado com mais de 100 mil milhões de emails.

Verificações:

• Sintaxe
• Registos DNS
• Deteção de endereços descartáveis
• Deteção de endereços de função
• Veredicto: Valid / Risky / Invalid + pontuação de confiança

Sandbox Mode

Permite testar o formato dos pedidos sem enviar realmente email.

Ativado via mail_settings.sandbox_mode.enable: true, faz o seguinte:

• Valida a estrutura JSON
• Retorna um código 200 (vs 202 para envios reais)
• Não consome créditos

Categories e unique_args

Permitem um tracking granular:

• Categories: agrupamento estatístico (newsletters, receipts, alerts)
• unique_args (custom_args em v3): identificadores específicos (número de encomenda, ID cliente) retornados nos eventos webhook

Plano de ação: integração em 5 passos

1. Criar a conta e gerar uma API key

• Criar uma conta SendGrid (plano Essentials mínimo desde supressão do Free)
• Gerar uma API key em Settings > API Keys
• Definir as permissões (Full Access ou apenas Mail Send)

2. Configurar Domain Authentication

• Ir a Settings > Sender Authentication > Domain Authentication
• Ativar Automated Security (recomendado)
• Criar os 3 registos CNAME no seu registrar:
  1. Return-Path (em1234.captaindns.com)
  2. DKIM s1 (s1._domainkey.captaindns.com)
  3. DKIM s2 (s2._domainkey.captaindns.com)
• Verificar a propagação DNS (24-48h)

3. Escolher o método de integração

Opção A: Web API v3

• Instalar o SDK oficial (npm install @sendgrid/mail, pip install sendgrid, etc.)
• Implementar o endpoint POST /v3/mail/send
• Criar Dynamic Templates se necessário

Opção B: SMTP Relay

• Configurar a sua app/plugin:
  • Host: smtp.sendgrid.net
  • Port: 587 (STARTTLS)
  • User: apikey
  • Password: a sua API key

4. Configurar os webhooks

• Ir a Settings > Mail Settings > Event Webhook
• Definir o URL do seu endpoint (HTTPS + TLS 1.2)
• Selecionar os eventos (delivered, bounced, etc.)
• Ativar a assinatura ECDSA para a segurança

5. Testar e monitorizar

• Enviar um email de teste
• Verificar em Activity Feed que o email está bem entregue
• Verificar os eventos webhook
• Controlar as estatísticas (open rate, bounce rate)

FAQ

Porque é que SendGrid utiliza dois seletores DKIM (s1 e s2)?

Os dois seletores permitem a rotação automática de chaves DKIM sem interrupção de serviço. Quando SendGrid quer renovar as chaves por razões de segurança, pode gerar uma nova chave em s2 enquanto s1 ainda está ativo, depois mudar progressivamente o tráfego. Isto evita qualquer interrupção de deliverability durante a mudança de chave.

Devo adicionar SendGrid no meu registo SPF?

Não, com Domain Authentication e Automated Security, é desnecessário. O CNAME Return-Path (em1234.captaindns.com) delega automaticamente a gestão SPF ao SendGrid. O seu registo SPF principal não precisa de mencionar SendGrid. Exceção: se também envia diretamente desde os seus servidores, deve incluí-los no seu SPF.

Como funciona a programação de envio com cancelamento?

Utilize send_at (timestamp Unix em segundos, máx 72h antecipadamente). Para poder cancelar, gere primeiro um batch_id via POST /v3/mail/batch, inclua-o no pedido de envio, depois submeta um cancelamento pelo menos 10 minutos antes da hora prevista via POST /v3/user/scheduled_sends.

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

1 000 destinatários máximo via o array personalizations (to + cc + bcc combinados). Cada destinatário pode receber conteúdo personalizado diferente via dynamic_template_data. Para enviar a 10 000 pessoas, são necessárias 10 chamadas API (limitadas a 10 000 req/s).

Posso utilizar o plano Essentials para produção crítica?

Sim, mas sem IP dedicado. O plano Essentials utiliza IPs partilhados, expondo-o a riscos de reputação coletiva. Para emails transacionais críticos (confirmações de encomenda, resets de palavra-passe), o plano Pro com IP dedicado é recomendado desde 50 000 emails/mês. Abaixo disso, Essentials é suficiente se o seu volume for regular.

Como gerir os rate limits de 10 000 req/s?

Implementar backoff exponencial e fila de espera local. Monitorizar os headers X-RateLimit-Remaining e X-RateLimit-Reset. Se atingir 429, aguardar o reset ou abrandar o ritmo. Para volumes muito grandes, usar várias API keys e distribuir as chamadas (rate limit por API key).

O header X-SMTPAPI funciona também com Web API v3?

Não, X-SMTPAPI é específico do SMTP Relay. Com Web API v3, utilize os parâmetros JSON nativos: categories, custom_args, mail_settings (tracking), send_at (scheduling). A Web API oferece um controlo mais fino e estruturado do que JSON num header SMTP.

Glossário

• Web API v3: API REST do SendGrid para o envio de emails transacionais. Endpoint principal: POST /v3/mail/send. Rate limit: 10 000 pedidos/segundo. Método recomendado para qualquer nova integração.

• SMTP Relay: Servidor SMTP do SendGrid (smtp.sendgrid.net) que permite enviar via o protocolo SMTP standard. Autenticação: user apikey + password = API key. Portas disponíveis: 587 (TLS), 465 (SSL), 2525 (fallback).

• Personalizations: Array JSON na Web API v3 que permite enviar até 1 000 destinatários por pedido, cada um recebendo conteúdo personalizado via dynamic_template_data.

• Dynamic Templates: Sistema de templates SendGrid utilizando sintaxe Handlebars. Suporta variáveis, condições, ciclos, comparações, formatação de datas. Chaveta tripla {{{html}}} para HTML não escapado.

• Domain Authentication: Configuração DNS para autenticar o seu domínio com SendGrid. Com Automated Security: 3 CNAME (Return-Path + DKIM s1 + DKIM s2). Gera chaves DKIM 2048 bits com rotação automática.

• Return-Path (Envelope From): Endereço técnico utilizado para o encaminhamento SMTP e os bounces. SendGrid utiliza um subdomínio do seu domínio (em1234.captaindns.com), permitindo o alinhamento SPF relaxed para DMARC. Personalizável via Custom Return Path.

• Automated Security: Opção recomendada para Domain Authentication. Gera CNAME em vez de TXT, permite a rotação automática de chaves DKIM, e utiliza chaves 2048 bits por defeito.

• IP Warmup: Processo automático de aquecimento de um IP dedicado novo. Calendário de 41 dias: de 20 emails/hora (D1) a mais de 19 milhões/hora (D41). Evita spam massivo e constrói progressivamente a reputação.

• Subusers: Subcontas isoladas com estatísticas, listas de supressão e webhooks próprios. Disponíveis em planos Pro e Premier (até 15 subusers). Permitem separar reputação por cliente ou por fluxo.

• IP Pools: Grupos de IPs dedicados atribuíveis a diferentes fluxos (transacional vs marketing, por cliente, por marca). Reforçam a separação de reputação.

• Event Webhook: Endpoint HTTP chamado pela SendGrid durante eventos (delivered, bounced, opened, clicked). Envio por lote (30s ou 768 KB). Retry durante 24h em caso de falha. Segurança: assinatura ECDSA ou OAuth 2.0.

• X-SMTPAPI: Header JSON específico do SMTP Relay para aceder a funcionalidades avançadas (categories, unique_args, filtros, scheduling). Tamanho máx: 10 000 bytes. Não usado com Web API v3.

• Link Branding: Configuração DNS para substituir os domínios SendGrid nas ligações rastreadas pelo seu próprio domínio. Necessita de 2 CNAME adicionais. Melhora confiança e reputação.

• Sandbox Mode: Modo teste que valida a estrutura JSON sem enviar realmente. Ativado via mail_settings.sandbox_mode.enable: true. Retorna código 200 (vs 202 em produção). Não consome créditos.

• Email Validation API: Serviço de validação de endereços email por machine learning (apenas Pro/Premier). Verifica sintaxe, DNS, deteta descartáveis e funções. Veredicto: Valid / Risky / Invalid + pontuação.

• Inbound Parse: Serviço para receber e processar emails recebidos. Configuração: registo MX para mx.sendgrid.net em subdomínio. Extrai headers, corpo, anexos, pontuação spam. Casos de uso: ticketing, comunicação bidirecional.

Fontes oficiais

• SendGrid Official Documentation
• Twilio SendGrid Pricing