Twilio SendGrid: Guida tecnica completa per l'email transazionale

⚡Riepilogo

• 📢 SendGrid utilizza un Return-Path personalizzabile (sottodominio del vostro dominio), consentendo l'allineamento SPF in modalità relaxed per DMARC dal piano base.
• La Web API v3 è il metodo raccomandato: 10 000 richieste/secondo, fino a 1 000 destinatari per chiamata, Dynamic Templates con Handlebars.
• Domain Authentication con Automated Security genera 3 CNAME: Return-Path + 2 selettori DKIM (rotazione automatica, chiavi 2048 bit).
• IP dedicato raccomandato a partire da 50 000 email/mese, con warm-up automatico di 41 giorni e costo di 30$/mese per IP aggiuntivo.
• Piano Free eliminato a maggio 2025: migrazione obbligatoria a Essentials 50K a 19,95$/mese minimo.

Introduzione

SendGrid si è affermata come una delle piattaforme di email transazionale più robuste sul mercato, elaborando oltre 190 miliardi di email mensili nel 2024. Acquisito da Twilio nel 2019 per circa 3 miliardi di dollari, il servizio combina una potente API REST, un relay SMTP universale e funzionalità di autenticazione avanzate che lo distinguono dalla concorrenza.

La forza di SendGrid risiede in tre pilastri tecnici principali: una Web API v3 capace di gestire 10 000 richieste/secondo, una Domain Authentication che consente l'allineamento SPF DMARC dal piano base, e un sistema di rotazione automatica delle chiavi DKIM 2048 bit senza interruzione del servizio.

Questa guida si rivolge a sviluppatori, DevOps e architetti di sistema che cercano di integrare SendGrid per l'email transazionale con una comprensione completa dell'infrastruttura: configurazione DNS, scelta API vs SMTP, gestione degli IP dedicati, limiti tecnici e webhook degli eventi.

Web API v3 vs SMTP Relay: architettura e scelta di integrazione

SendGrid propone due metodi di integrazione per l'email transazionale, entrambi disponibili dai piani a pagamento.

Confronto tecnico

Criterio	Web API v3	SMTP Relay
Endpoint	POST https://api.sendgrid.com/v3/mail/send	smtp.sendgrid.net porte 587/465
Autenticazione	Bearer token (API key)	User: apikey / Pass: API key
Rate limit	10 000 richieste/secondo	Dipende dall'IP e dal piano
Destinatari/req	Fino a 1 000 (personalizations)	1 email = 1 connessione SMTP
Templates	Dynamic Templates (Handlebars)	Solo contenuto inline
Scheduling	send_at (fino a 72h in anticipo)	Tramite header X-SMTPAPI
Tracking	Nativo (click, open, Google Analytics)	Tramite X-SMTPAPI
Compatibilità	Richiede SDK o client HTTP	Qualsiasi sistema compatibile SMTP
Caso d'uso ideale	App moderne, batch, personalizzazione avanzata	Legacy, plugin CMS, server mail

Quando scegliere Web API v3?

La Web API v3 è il metodo raccomandato da SendGrid per qualsiasi nuova integrazione. È accessibile a POST https://api.sendgrid.com/v3/mail/send (o api.eu.sendgrid.com per la regione EU).

Vantaggi chiave:

• Personalizations: invio fino a 1 000 destinatari in una singola richiesta, ciascuno ricevendo contenuti personalizzati diversi
• Dynamic Templates: sintassi Handlebars con condizioni, cicli, confronti, formattazione date
• Scheduling: programmazione invio fino a 72 ore in anticipo con possibilità di annullamento
• Rate limit generoso: 10 000 richieste/secondo sull'endpoint mail/send

Esempio di invio con personalizzazione:

{
  "personalizations": [{
    "to": [{"email": "utente@captaindns.com", "name": "Mario Rossi"}],
    "dynamic_template_data": {
      "nome": "Mario",
      "numero_ordine": "ORD-12345",
      "importo": "149,90 €"
    }
  }],
  "from": {"email": "ordini@captaindns.com"},
  "template_id": "d-abc123def456"
}

SDK ufficiali: SendGrid mantiene 7 SDK ufficiali (Node.js, Python, PHP, Ruby, Go, Java, C#) che incapsulano l'API REST e semplificano l'integrazione.

Quando scegliere SMTP Relay?

L'SMTP Relay è ideale per sistemi legacy o applicazioni che supportano solo SMTP.

Configurazione ufficiale:

SMTP server: smtp.sendgrid.net
SMTP user: apikey (letteralmente la stringa "apikey")
SMTP password: [la vostra chiave API SendGrid]
Port: 587 (TLS raccomandato) o 465 (SSL) o 2525 (fallback)

Punto critico: l'autenticazione SMTP utilizza una configurazione specifica. Il nome utente è letteralmente la stringa apikey (non il vostro identificativo account), e la password è la vostra chiave API SendGrid.

Header X-SMTPAPI: permette di accedere alle funzionalità avanzate tramite SMTP (categories, unique_args, filtri, scheduling, tag di sostituzione). Dimensione massima: 10 000 byte.

Esempio di header X-SMTPAPI per il tracking:

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

Domain Authentication: SPF, DKIM 2048 bit e allineamento DMARC

L'autenticazione del dominio con SendGrid genera i record DNS necessari per SPF, DKIM e l'allineamento DMARC. Il processo si effettua in Settings > Sender Authentication > Domain Authentication.

Architettura con Automated Security (raccomandato)

Con l'opzione Automated Security attivata, SendGrid genera 3 record CNAME:

1. CNAME per Return-Path: em1234.captaindns.com puntante a 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

Vantaggi di questa architettura:

• Rotazione automatica delle chiavi DKIM: i due selettori (s1 e s2) permettono a SendGrid di cambiare le chiavi senza interruzione del servizio
• Chiavi DKIM 2048 bit per default da maggio 2021 (configurazioni precedenti possono usare 1024 bit)
• Nessun record SPF manuale richiesto: il CNAME delega la gestione SPF a SendGrid
• Selettori personalizzabili: 1-3 caratteri alfanumerici nei parametri avanzati

Return-Path e allineamento SPF: un vantaggio importante

Il Return-Path (Envelope From) è cruciale per l'allineamento DMARC. Per default, SendGrid utilizza un sottodominio nel formato em[XXX].captaindns.com:

• SPF passa automaticamente perché il CNAME delega la gestione SPF a SendGrid
• L'allineamento SPF funziona in modalità relaxed (il sottodominio em1234.captaindns.com corrisponde al dominio padre captaindns.com)
• Non serve modificare il vostro SPF principale: il CNAME gestisce tutto

Tuttavia, per una policy DMARC stretta (aspf=s), l'allineamento SPF fallirà perché il dominio Return-Path non corrisponderà mai esattamente al dominio From. La soluzione è di appoggiarsi a DKIM per l'allineamento DMARC, che supporta la modalità stretta (adkim=s).

Custom Return Path

L'opzione Custom Return Path nei parametri avanzati permette di personalizzare il sottodominio (ad esempio mail.captaindns.com invece di em1234.captaindns.com).

Link Branding

Il Link Branding sostituisce i domini SendGrid nei link tracciati con il vostro dominio. Invece di sendgrid.net/click/xxx, i link mostreranno url1234.captaindns.com/click/xxx. Questa configurazione richiede 2 record CNAME aggiuntivi e migliora la fiducia dei destinatari.

Migrazione a DKIM 2048 bit

Per migrare una configurazione precedente (chiavi 1024 bit) verso 2048 bit, bisogna creare una nuova autenticazione di dominio con un nuovo selettore personalizzato non utilizzato in precedenza.

IP dedicato vs IP condiviso: strategia di deliverability

SendGrid raccomanda ufficialmente un IP dedicato a partire da 50 000 email al mese. Oltre 200 000-300 000 email mensili, si consigliano due IP dedicati.

IP condiviso (piani Free ed Essentials)

Vantaggi:

• Nessun warm-up necessario
• Reputazione mantenuta da SendGrid
• Ideale per volumi bassi o irregolari

Svantaggi:

• Esposizione a rischi di reputazione legati ad altri mittenti del pool
• Problemi di blocklist frequenti su Microsoft/Outlook

IP dedicato (piano Pro e superiore)

Il piano Pro include 1 IP dedicato, con possibilità di aggiungerne a 30$/mese per IP aggiuntivo.

Vantaggi:

• Reputazione isolata e controllabile
• Funzione di IP Warmup automatico su 41 giorni
• Possibilità di separare i flussi (transazionale vs marketing)

IP Warmup automatico: limita progressivamente gli invii secondo un calendario predefinito:

• Giorno 1: 20 email/ora
• Giorno 41: Oltre 19 milioni/ora

IP Pools: permettono di raggruppare più IP dedicati e assegnarli a diversi flussi. La separazione è rafforzata dai Subusers (sotto-account isolati con proprie statistiche, liste di soppressione e webhook).

Subusers: i piani Pro e Premier supportano fino a 15 subusers per account.

Quando scegliere un IP dedicato?

Avete bisogno di un IP dedicato se:

• Volume regolare > 50 000 email/mese
• Necessità di separare reputazione transazionale vs marketing
• Requisiti di whitelisting cliente o conformità normativa
• Volume > 200 000 email/mese: 2 IP dedicati raccomandati

Restate su IP condiviso se:

• Volume < 50 000 email/mese
• Invii irregolari o sporadici
• Avvio attività senza storico

Tariffazione 2025 ed evoluzione del piano Free

Piani Email API

Piano	Volume mensile	Prezzo/mese	IP dedicato	Subusers
Free	100/giorno (60g)	Gratuito	No	No
Essentials 50K	50 000	19,95$	No	No
Essentials 100K	100 000	34,95$	No	No
Pro 100K	100 000	89,95$	1 incluso	Fino a 15
Pro 300K	300 000	249$	1 incluso	Fino a 15
Pro 700K	700 000	499$	1 incluso	Fino a 15
Premier	Personalizzato	Su preventivo	1 incluso	Fino a 15

Evoluzione importante: A maggio 2025, SendGrid ha annunciato la rimozione del piano Free con un periodo di transizione di 60 giorni. Gli utenti devono migrare a un piano a pagamento per continuare a inviare email.

Costi aggiuntivi

• IP dedicato aggiuntivo: 30$/mese
• Email Validation API: 2 500 validazioni/mese incluse (Pro), 5 000 (Premier), poi tariffazione a consumo
• Inbound Parse: incluso in tutti i piani a pagamento
• Superamenti: fatturati pro-rata (~0,001$/email su Pro)

Limiti tecnici e rate limits

Rate limits per endpoint

Endpoint	Limite
v3 Mail Send	10 000 richieste/secondo
API generale	600 richieste/minuto
Email Validation	7 richieste/secondo

Quando si raggiunge il limite, l'API restituisce un codice HTTP 429. Gli header X-RateLimit-Remaining e X-RateLimit-Reset indicano la quota rimanente e il timestamp di reinizializzazione.

Gestione raccomandata: backoff esponenziale e messa in coda locale.

Quote per messaggio

Parametro	Limite
Dimensione massima email	30 MB
Destinatari per messaggio	1 000
Categories per messaggio	10
Custom args	< 10 000 byte
Gruppi di unsubscribe	200 per account

Gestione delle soppressioni

SendGrid mantiene automaticamente diverse liste di soppressione:

• Global Suppressions: disiscrizioni globali
• Group Unsubscribes: tramite ASM (Advanced Suppression Manager)
• Bounces: hard e soft
• Spam Reports
• Invalid Emails

Gli indirizzi sono soppressi indefinitamente per default, con opzione di purga configurabile da 1 a 3650 giorni per i bounce.

Event Webhook e tracking in tempo reale

Il webhook degli eventi permette di ricevere in tempo reale le notifiche di delivery, engagement e compliance.

Eventi disponibili

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

Comportamento e retry

Gli eventi sono inviati per batch entro 30 secondi o quando il batch raggiunge 768 KB. In caso di fallimento (risposta non-2xx), SendGrid riprova per 24 ore con intervalli crescenti.

Sicurezza

La sicurezza del webhook può essere assicurata tramite:

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

Requisito: l'endpoint deve supportare TLS 1.2 minimo.

Inbound Parse

L'Inbound Parse permette di ricevere e parsare le email in arrivo. La configurazione necessita di un record MX puntante verso mx.sendgrid.net su un sottodominio dedicato.

SendGrid estrae automaticamente:

• Header
• Corpo (text e HTML)
• Allegati
• Punteggio spam (opzionale)

Casi d'uso: sistemi di ticketing, workflow di comunicazione bidirezionale.

Funzionalità avanzate

Email Validation API

Disponibile solo sui piani Pro e Premier. Utilizza machine learning addestrato su oltre 100 miliardi di email.

Verifiche:

• Sintassi
• Record DNS
• Rilevamento indirizzi usa e getta
• Rilevamento indirizzi di ruolo
• Verdetto: Valid / Risky / Invalid + punteggio di confidenza

Sandbox Mode

Permette di testare il formato delle richieste senza inviare realmente email.

Attivato tramite mail_settings.sandbox_mode.enable: true, fa quanto segue:

• Valida la struttura JSON
• Restituisce un codice 200 (vs 202 per invii reali)
• Non consuma crediti

Categories e unique_args

Permettono un tracking granulare:

• Categories: raggruppamento statistico (newsletter, receipts, alerts)
• unique_args (custom_args in v3): identificatori specifici (numero ordine, ID cliente) restituiti negli eventi webhook

Piano d'azione: integrazione in 5 passi

1. Creare l'account e generare una API key

• Creare un account SendGrid (piano Essentials minimo dalla rimozione del Free)
• Generare una API key in Settings > API Keys
• Definire i permessi (Full Access o solo Mail Send)

2. Configurare Domain Authentication

• Andare in Settings > Sender Authentication > Domain Authentication
• Attivare Automated Security (raccomandato)
• Creare i 3 record CNAME presso il vostro registrar:
  1. Return-Path (em1234.captaindns.com)
  2. DKIM s1 (s1._domainkey.captaindns.com)
  3. DKIM s2 (s2._domainkey.captaindns.com)
• Verificare la propagazione DNS (24-48h)

3. Scegliere il metodo di integrazione

Opzione A: Web API v3

• Installare l'SDK ufficiale (npm install @sendgrid/mail, pip install sendgrid, ecc.)
• Implementare l'endpoint POST /v3/mail/send
• Creare Dynamic Templates se necessario

Opzione B: SMTP Relay

• Configurare la vostra app/plugin:
  • Host: smtp.sendgrid.net
  • Port: 587 (STARTTLS)
  • User: apikey
  • Password: la vostra API key

4. Configurare i webhook

• Andare in Settings > Mail Settings > Event Webhook
• Definire l'URL del vostro endpoint (HTTPS + TLS 1.2)
• Selezionare gli eventi (delivered, bounced, ecc.)
• Attivare la firma ECDSA per la sicurezza

5. Testare e monitorare

• Inviare un'email di test
• Verificare in Activity Feed che l'email sia ben consegnata
• Verificare gli eventi webhook
• Controllare le statistiche (open rate, bounce rate)

FAQ

Perché SendGrid utilizza due selettori DKIM (s1 e s2)?

I due selettori permettono la rotazione automatica delle chiavi DKIM senza interruzione del servizio. Quando SendGrid vuole rinnovare le chiavi per ragioni di sicurezza, può generare una nuova chiave su s2 mentre s1 è ancora attivo, poi spostare progressivamente il traffico. Ciò evita qualsiasi interruzione di deliverability durante il cambio chiave.

Devo aggiungere SendGrid nel mio record SPF?

No, con Domain Authentication e Automated Security è inutile. Il CNAME Return-Path (em1234.captaindns.com) delega automaticamente la gestione SPF a SendGrid. Il vostro record SPF principale non deve menzionare SendGrid. Eccezione: se inviate anche direttamente dai vostri server, dovete includerli nel vostro SPF.

Come funziona la programmazione invio con annullamento?

Utilizzate send_at (timestamp Unix in secondi, max 72h in anticipo). Per poter annullare, generate prima un batch_id tramite POST /v3/mail/batch, includetelo nella richiesta di invio, poi inviate un annullamento almeno 10 minuti prima dell'ora prevista tramite POST /v3/user/scheduled_sends.

Qual è il limite reale di destinatari per chiamata API?

1 000 destinatari massimo tramite l'array personalizations (to + cc + bcc combinati). Ogni destinatario può ricevere contenuti personalizzati diversi tramite dynamic_template_data. Per inviare a 10 000 persone, servono 10 chiamate API (limitate a 10 000 req/s).

Posso utilizzare il piano Essentials per produzione critica?

Sì, ma senza IP dedicato. Il piano Essentials utilizza IP condivisi, esponendovi a rischi di reputazione collettiva. Per email transazionali critiche (conferme ordine, reset password), si raccomanda il piano Pro con IP dedicato da 50 000 email/mese. Sotto, Essentials è sufficiente se il vostro volume è regolare.

Come gestire i rate limits di 10 000 req/s?

Implementare backoff esponenziale e coda locale. Monitorare gli header X-RateLimit-Remaining e X-RateLimit-Reset. Se raggiungete 429, attendere il reset o rallentare il ritmo. Per volumi molto grandi, usare più API key e distribuire le chiamate (rate limit per API key).

L'header X-SMTPAPI funziona anche con Web API v3?

No, X-SMTPAPI è specifico per SMTP Relay. Con Web API v3, utilizzate i parametri JSON nativi: categories, custom_args, mail_settings (tracking), send_at (scheduling). La Web API offre un controllo più fine e strutturato rispetto al JSON in un header SMTP.

Glossario

• Web API v3: API REST di SendGrid per l'invio di email transazionali. Endpoint principale: POST /v3/mail/send. Rate limit: 10 000 richieste/secondo. Metodo raccomandato per qualsiasi nuova integrazione.

• SMTP Relay: Server SMTP di SendGrid (smtp.sendgrid.net) che permette di inviare tramite il protocollo SMTP standard. Autenticazione: user apikey + password = API key. Porte disponibili: 587 (TLS), 465 (SSL), 2525 (fallback).

• Personalizations: Array JSON nella Web API v3 che permette di inviare fino a 1 000 destinatari per richiesta, ciascuno ricevendo contenuti personalizzati tramite dynamic_template_data.

• Dynamic Templates: Sistema di template di SendGrid utilizzando sintassi Handlebars. Supporta variabili, condizioni, cicli, confronti, formattazione date. Tripla parentesi graffa {{{html}}} per HTML non escaped.

• Domain Authentication: Configurazione DNS per autenticare il vostro dominio con SendGrid. Con Automated Security: 3 CNAME (Return-Path + DKIM s1 + DKIM s2). Genera chiavi DKIM 2048 bit con rotazione automatica.

• Return-Path (Envelope From): Indirizzo tecnico utilizzato per il routing SMTP e i bounce. SendGrid utilizza un sottodominio del vostro dominio (em1234.captaindns.com), permettendo l'allineamento SPF relaxed per DMARC. Personalizzabile tramite Custom Return Path.

• Automated Security: Opzione raccomandata per Domain Authentication. Genera CNAME invece di TXT, permette la rotazione automatica delle chiavi DKIM, e utilizza chiavi 2048 bit per default.

• IP Warmup: Processo automatico di ramp-up di un IP dedicato nuovo. Calendario su 41 giorni: da 20 email/ora (G1) a oltre 19 milioni/ora (G41). Evita spam massiccio e costruisce progressivamente la reputazione.

• Subusers: Sotto-account isolati con statistiche, liste di soppressione e webhook propri. Disponibili sui piani Pro e Premier (fino a 15 subusers). Permettono di separare reputazione per cliente o per flusso.

• IP Pools: Gruppi di IP dedicati assegnabili a diversi flussi (transazionale vs marketing, per cliente, per brand). Rafforzano la separazione di reputazione.

• Event Webhook: Endpoint HTTP chiamato da SendGrid durante eventi (delivered, bounced, opened, clicked). Invio per batch (30s o 768 KB). Retry per 24h in caso di fallimento. Sicurezza: firma ECDSA o OAuth 2.0.

• X-SMTPAPI: Header JSON specifico per SMTP Relay per accedere a funzionalità avanzate (categories, unique_args, filtri, scheduling). Dimensione max: 10 000 byte. Non usato con Web API v3.

• Link Branding: Configurazione DNS per sostituire i domini SendGrid nei link tracciati con il vostro dominio. Richiede 2 CNAME aggiuntivi. Migliora fiducia e reputazione.

• Sandbox Mode: Modalità test che valida la struttura JSON senza inviare realmente. Attivato tramite mail_settings.sandbox_mode.enable: true. Restituisce codice 200 (vs 202 in produzione). Non consuma crediti.

• Email Validation API: Servizio di validazione indirizzi email tramite machine learning (solo Pro/Premier). Verifica sintassi, DNS, rileva usa e getta e ruoli. Verdetto: Valid / Risky / Invalid + punteggio.

• Inbound Parse: Servizio per ricevere e parsare email in arrivo. Configurazione: record MX verso mx.sendgrid.net su sottodominio. Estrae header, corpo, allegati, punteggio spam. Casi d'uso: ticketing, comunicazione bidirezionale.

Fonti ufficiali

• SendGrid Official Documentation
• Twilio SendGrid Pricing