Inviare email tramite SMTP

Se la tua applicazione supporta già SMTP, puntala verso il nostro relay modificando host, porta e credenziali. Framework, sistemi di gestione dei contenuti, stampanti e qualsiasi altro software in grado di inviare posta a un relay SMTP possono usare questo percorso.

La posta inviata tramite SMTP viene trattata esattamente come quella inviata attraverso l'email API: stessa verifica del dominio, pool di IP, firma DKIM, gestione delle soppressioni, tracking, eventi e analytics. SMTP è un secondo punto di accesso allo stesso prodotto, quindi tutto ciò che configuri per uno si applica anche all'altro.

Scegli il servizio relay SMTP quando vuoi mantenere il codice esistente della tua applicazione per la composizione dei messaggi. Scegli l'email API quando hai bisogno di campi strutturati nella richiesta o di template salvati. SMTP prende il contenuto dal messaggio MIME e le opzioni di invio dalla configurazione della chiave API.

Cosa serve prima

Un dominio di invio verificato. L'indirizzo inserito in MAIL FROM (e nell'header From del messaggio) deve appartenere a un dominio verificato in questo spazio di lavoro. Vedi Domini di invio.
Una chiave API con lo scope emails. SMTP usa le normali chiavi API e non richiede una credenziale SMTP separata. Crea una chiave in Developers > Chiavi API con l'invio email abilitato. Una chiave senza lo scope emails non può inviare, e nemmeno una chiave di solo verify.

Impostazioni di connessione

Punta il tuo client verso l'host SMTP della regione della tua chiave. La regione è il prefisso nella chiave stessa: una chiave bk_eu1_... invia attraverso l'host eu1, una chiave bk_us1_... attraverso us1. Autenticarsi con una chiave dell'altra regione genera un errore con una risposta 535 che indica l'host corretto.

Regione	Host
EU	eu1.smtp.bird.com
US	us1.smtp.bird.com

Porta	Crittografia
465	TLS implicito (SMTPS)
587	STARTTLS
2525	STARTTLS

Usa quella supportata dal tuo client:

Porta 465, TLS implicito (SMTPS). La connessione è crittografata dal primo byte, prima che venga inviato qualsiasi comando. Nella maggior parte delle librerie corrisponde all'opzione "SSL/TLS" o "SMTPS".
Porte 587 e 2525, STARTTLS. La connessione si apre in chiaro e viene promossa a TLS con il comando STARTTLS prima dell'autenticazione. Corrisponde all'opzione "STARTTLS", a volte indicata semplicemente come "TLS". Usa la 2525 se la tua rete blocca la 587.

In entrambi i casi la sessione è crittografata prima dell'invio delle credenziali, che quindi non transitano mai in chiaro: sulle porte 587 e 2525 AUTH viene rifiutato finché STARTTLS non è stato eseguito. La porta 25 non è disponibile per l'invio.

Autenticazione

Autenticati con AUTH PLAIN o AUTH LOGIN. Il nome utente è la stringa letterale bird e la password è la tua chiave API:

Esempio di codice

Username: bird
Password: bk_eu1_your_api_key

Il nome utente è un valore letterale fisso e non ha un'identità propria. La chiave API nel campo password è ciò che esegue l'autenticazione. Nella maggior parte degli strumenti SMTP incolli la chiave API nel campo password e imposti il nome utente su bird. La revoca della chiave interrompe l'invio SMTP entro pochi secondi, anche a connessione in corso.

Cosa proviene dal messaggio e cosa dalla configurazione della chiave

Tutto ciò che ha una collocazione naturale in un messaggio MIME proviene dal messaggio stesso: gli header From, To, Cc e Reply-To, l'oggetto, il corpo HTML e testo, gli allegati e le immagini inline. I destinatari vengono presi dall'envelope SMTP (RCPT TO). Un indirizzo in RCPT TO che non compare in un header To o Cc visibile viene trattato come Bcc. Un messaggio può avere al massimo 50 destinatari tra to, cc e bcc, e la dimensione totale è limitata a 20 MB.

Le opzioni di invio che non hanno una collocazione standard in un messaggio MIME provengono dalla configurazione SMTP della chiave. Includono il pool di IP, la categoria, i tag e il tracking di apertura e clic. Una chiave non configurata usa il pool predefinito dell'organizzazione, la categoria transactional e il tracking abilitato. Configura la chiave in Email > SMTP oppure chiama l'SMTP config API. Assegna a ogni applicazione una chiave propria quando servono valori predefiniti diversi. Le modifiche si applicano ai nuovi messaggi senza riconnettere il client.

Una sessione completa

Sulla porta 465 il client apre prima la connessione TLS, poi esegue l'intero dialogo SMTP al suo interno:

Esempio di codice

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

Sulla porta 587 o 2525 il client si connette in chiaro, emette STARTTLS per promuovere la connessione, poi esegue lo stesso dialogo all'interno di TLS. AUTH non viene offerto finché l'upgrade non è completato:

Esempio di codice

S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

Il 250 finale restituisce l'ID del messaggio accodato, lo stesso ID em_... che otterresti dall'API. Puoi cercare il messaggio tramite quell'ID nel Log email o attraverso GET /v1/email/messages/{message_id}.

Riprovare in sicurezza

La pipeline accetta un messaggio e lo consegna in modo asincrono, e i client SMTP riprovano in modo aggressivo quando una connessione cade. Per rendere sicuro un nuovo tentativo, aggiungi un header X-Bird-Idempotency-Key al messaggio: una ripetizione entro la finestra di conservazione restituisce l'ID del messaggio già accodato invece di inviare una seconda copia. Usa un valore stabile per il messaggio logico, come un ID ordine o un ID notifica. Evita di generare un valore casuale a ogni tentativo.

Conserva l'ID del messaggio accodato insieme all'evento applicativo che ha causato l'invio. Se la connessione cade prima di ricevere la risposta finale, riprova lo stesso messaggio logico con la stessa chiave. Dopo la finestra di conservazione, un nuovo tentativo può creare un altro messaggio. Mantieni il tuo registro di invio per il recupero oltre quella finestra.

Limiti di connessione

Ogni organizzazione può mantenere fino a 10 connessioni SMTP autenticate simultanee per impostazione predefinita. Una connessione conta dall'autenticazione fino alla chiusura, su tutti i server e le chiavi API dell'organizzazione. Raggiunto il limite, un'ulteriore connessione riceve una risposta temporanea 421 dopo l'autenticazione. Riusa le connessioni, riduci la concorrenza e riprova. Il limite conta le connessioni aperte indipendentemente dal volume di messaggi. Email > SMTP mostra le connessioni attive rispetto al limite.

Dimensiona il tuo pool di connessioni in base al limite di connessioni dell'organizzazione. Regola le sottomissioni in base alle quote di invio. Gli header di HTTP limitazione delle richieste descrivono le richieste API; non rappresentano un'allowance di velocità di invio SMTP.

Gestire le risposte SMTP

SMTP segnala un dominio di invio non verificato, un dominio destinatario riservato, un pool di IP non utilizzabile, un tipo di allegato bloccato o un messaggio malformato con una risposta permanente 550. Un messaggio oltre il limite di 20 MB restituisce 552. Una quota di invio superata o un numero di destinatari oltre 50 restituisce una risposta temporanea 452. I destinatari soppressi vengono gestiti in modo asincrono: SMTP accetta il messaggio, poi ogni destinatario soppresso compare come rejected nel log email e negli eventi.

Per la scelta dell'interfaccia, confronta invio e recupero tramite SMTP e HTTP. Entrambi i percorsi accodano il lavoro prima della consegna al destinatario. Un evento email.delivered registra l'accettazione da parte del server ricevente. Quell'evento non garantisce il posizionamento in inbox.

Prossimi passi

Domini di invio: verifica il dominio da cui invierai.
IP dedicati e pool: scegli da quale pool invia una chiave.
Soppressioni: perché un destinatario accettato potrebbe non ricevere un messaggio.
Log email: trova un messaggio tramite l'ID restituito da SMTP.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Esplora la funzionalitàSMTP relay