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.

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.

Versioni TLS: le porte 465, 587 e 2525 supportano TLS 1.2 e TLS 1.3. Configura il client per usare TLS 1.2 o successivo. TLS 1.0 e TLS 1.1 non sono supportati.

In entrambi i casi la sessione è cifrata prima dell'invio delle credenziali, che non viaggiano 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:

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 autentica la connessione. 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 viene dal messaggio e cosa dalla configurazione della chiave

Tutto ciò che ha una collocazione naturale in un messaggio MIME viene dal messaggio stesso: gli header From, To, Cc e Reply-To, l'oggetto, i body HTML e testo, gli allegati e le immagini inline. I destinatari sono ricavati dall'envelope SMTP (RCPT TO). Un indirizzo in RCPT TO che non compare in un header visibile To o Cc è 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 vengono dalla configurazione SMTP della chiave. Tra queste: IP pool, categoria, tag e tracciamento di aperture e clic. Una chiave non configurata usa il pool predefinito dell'organizzazione, la categoria transactional e il tracciamento abilitato. Configura la chiave in Email > SMTP oppure chiama l'endpoint SMTP config API. Assegna a ogni applicazione una chiave propria quando servono impostazioni diverse. 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:

   ... 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, invia STARTTLS per aggiornare la connessione, poi esegue lo stesso dialogo all'interno di TLS. AUTH non è disponibile finché l'upgrade non è completato:

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 dalla API. Puoi cercare il messaggio tramite quell'ID nell'Email log o attraverso GET /v1/email/messages/{message_id}.

Riprovare in sicurezza

La pipeline accetta il 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: un invio ripetuto entro la finestra di conservazione restituisce l'ID del messaggio già in coda 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 in coda insieme all'evento applicativo che ha causato l'invio. Se la connessione cade prima di ricevere la risposta finale, riprova con lo stesso messaggio logico e la stessa chiave. Dopo la finestra di conservazione, un nuovo tentativo può creare un altro messaggio. Mantieni un tuo registro degli invii 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. Al raggiungimento del limite, un'altra connessione riceve una risposta transitoria 421 dopo l'autenticazione. Riusa le connessioni, riduci la concorrenza e riprova. Il limite conta le connessioni aperte indipendentemente dal volume dei messaggi. Email > SMTP mostra le connessioni attive rispetto al limite.

Dimensiona il pool di connessioni in base al limite dell'organizzazione. Distribuisci gli invii in base alle quote di invio. Gli header HTTP di limitazione delle richieste descrivono le richieste API; non rappresentano un'autorizzazione alla velocità di invio SMTP.

Gestire le risposte SMTP

SMTP segnala un dominio di invio non verificato, un dominio destinatario riservato, un pool IP inutilizzabile, 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 superiore a 50 restituisce una risposta transitoria 452. I destinatari soppressi vengono gestiti in modo asincrono: SMTP accetta il messaggio, quindi ogni destinatario soppresso appare come rejected nel log email e negli eventi.

Per la scelta dell'interfaccia, confronta invio e recupero tramite SMTP e HTTP. Entrambi i percorsi mettono in coda 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 nella casella di posta.

Passaggi successivi

• 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 il messaggio.
• Log email: trova un messaggio tramite l'ID restituito da SMTP.