E-mail verzenden via SMTP

Als je applicatie al SMTP ondersteunt, richt je deze op onze relay door de host, poort en inloggegevens aan te passen. Frameworks, contentmanagementsystemen, printers en andere software die mail kan indienen bij een SMTP-relay kunnen dit pad gebruiken.

Mail ingediend via SMTP wordt exact hetzelfde behandeld als mail verzonden via de e-mail-API: dezelfde domeinverificatie, IP-pools, DKIM-ondertekening, suppressieafhandeling, tracking, events en analytics. SMTP is een tweede toegangsweg tot hetzelfde product, dus alles wat je voor de ene instelt geldt ook voor de andere.

Kies de SMTP-relayservice als je de bestaande code voor het opbouwen van berichten in je applicatie wilt behouden. Kies de e-mail-API als je gestructureerde requestvelden of opgeslagen templates nodig hebt. SMTP haalt content uit het MIME-bericht en verzendopties uit de configuratie van de API-key.

Wat je eerst nodig hebt

• Een geverifieerd verzenddomein. Het adres dat je in MAIL FROM zet (en de From-header van het bericht) moet bij een domein horen dat je in deze werkruimte hebt geverifieerd. Zie Verzenddomeinen.
• Een API-key met de emails-scope. SMTP gebruikt je normale API-keys en vereist geen apart SMTP-credential. Maak een key aan in Developers > API keys met e-mailverzending ingeschakeld. Een key zonder de emails-scope kan niet verzenden, en een verify-only key evenmin.

Verbindingsinstellingen

Richt je client op de SMTP-host voor de regio van je key. De regio is het voorvoegsel in de key zelf: een bk_eu1_...-key verzendt via de eu1-host, een bk_us1_...-key via us1. Authenticeren met een key uit de andere regio mislukt met een 535-antwoord dat de juiste host vermeldt.

Gebruik wat je client ondersteunt:

• Poort 465, impliciet TLS (SMTPS). De verbinding is versleuteld vanaf de eerste byte, nog voordat er een commando wordt verstuurd. In de meeste bibliotheken is dit de "SSL/TLS"- of "SMTPS"-optie.
• Poorten 587 en 2525, STARTTLS. De verbinding opent in platte tekst en upgradet naar TLS met het STARTTLS-commando vóór authenticatie. Dit is de "STARTTLS"-optie, soms simpelweg "TLS" genoemd. Kies 2525 als je netwerk poort 587 blokkeert.

TLS-versies: Poorten 465, 587 en 2525 ondersteunen TLS 1.2 en TLS 1.3. Configureer je client voor TLS 1.2 of hoger. TLS 1.0 en TLS 1.1 worden niet ondersteund.

In beide gevallen is de sessie versleuteld voordat je inloggegevens worden verstuurd, dus ze gaan nooit onversleuteld over de lijn: op 587 en 2525 wordt AUTH geweigerd totdat STARTTLS is uitgevoerd. Poort 25 wordt niet aangeboden voor het indienen van berichten.

Authenticeren

Authenticeer met AUTH PLAIN of AUTH LOGIN. De gebruikersnaam is de letterlijke string bird en het wachtwoord is je API-key:

Username: bird
Password: bk_eu1_your_api_key

De gebruikersnaam is een vast letterlijk woord en heeft geen eigen identiteit. De API-key in het wachtwoordveld is wat authenticeert. In de meeste SMTP-tools plak je je API-key in het wachtwoordveld en stel je de gebruikersnaam in op bird. Het intrekken van de key stopt het SMTP-verzenden binnen enkele seconden, ook midden in een verbinding.

Wat uit het bericht komt en wat uit de configuratie van de key

Alles met een logische plek in een MIME-bericht komt uit het bericht zelf: de From-, To-, Cc- en Reply-To-headers, het onderwerp, de HTML- en tekstbody's, en bijlagen en inline-afbeeldingen. Ontvangers worden overgenomen uit de SMTP-envelope (RCPT TO). Een adres in RCPT TO dat niet in een zichtbare To- of Cc-header staat, wordt behandeld als een Bcc. Een bericht kan maximaal 50 ontvangers hebben over to, cc en bcc, en de totale berichtgrootte is begrensd op 20 MB.

Verzendopties die geen standaardplek in een MIME-bericht hebben, komen uit de SMTP-configuratie van de key. Hieronder vallen de IP-pool, categorie, tags en open- en kliktracking. Een niet-geconfigureerde key gebruikt de standaardpool van je organisatie, de transactional-categorie en tracking ingeschakeld. Configureer de key in Email > SMTP, of gebruik de SMTP config API. Geef elke applicatie een eigen key als deze andere standaardwaarden nodig heeft. Wijzigingen gelden voor nieuwe berichten zonder de client opnieuw te verbinden.

Een volledige sessie

Op poort 465 opent de client eerst de TLS-verbinding en voert daarna de volledige SMTP-dialoog erbinnen uit:

   ... 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

Op poort 587 of 2525 maakt de client verbinding in plaintext, geeft STARTTLS om de verbinding te upgraden en voert daarna dezelfde dialoog uit binnen TLS. AUTH wordt pas aangeboden nadat de upgrade is voltooid:

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

Het laatste 250 retourneert het ID van het in de wachtrij geplaatste bericht, hetzelfde em_...-ID dat je van de API zou krijgen. Je kunt het bericht met dat ID opzoeken in het E-maillogboek of via GET /v1/email/messages/{message_id}.

Veilig opnieuw proberen

De pipeline accepteert een bericht en bezorgt het asynchroon, en SMTP-clients proberen het agressief opnieuw wanneer een verbinding wegvalt. Voeg een X-Bird-Idempotency-Key-header toe aan het bericht om een retry veilig te maken: een herhaling binnen het retentievenster geeft het ID terug van het bericht dat al in de wachtrij stond, in plaats van een tweede kopie te verzenden. Gebruik een waarde die stabiel is voor het logische bericht, zoals een order-ID of notificatie-ID. Vermijd het genereren van een willekeurige waarde bij elke poging.

Bewaar het wachtrij-ID van het bericht bij het applicatie-event dat de verzending veroorzaakte. Als de verbinding wegvalt voordat je het laatste antwoord ontvangt, probeer dat logische bericht dan opnieuw met dezelfde sleutel. Na het retentievenster kan een retry een nieuw bericht aanmaken. Bewaar je eigen verzendregistratie voor herstel na dat venster.

Verbindingslimieten

Elke organisatie kan standaard maximaal 10 gelijktijdige geauthenticeerde SMTP-verbindingen openhouden. Een verbinding telt vanaf authenticatie tot deze wordt gesloten, over alle servers en API-keys in de organisatie. Bij de limiet ontvangt een volgende verbinding een tijdelijk 421-antwoord na authenticatie. Hergebruik verbindingen, verminder gelijktijdigheid en probeer opnieuw. De limiet telt open verbindingen onafhankelijk van berichtvolume. Email > SMTP toont actieve verbindingen afgezet tegen de limiet.

Stem je verbindingspool af op de verbindingslimiet van de organisatie. Reguleer verzendingen aan de hand van verzendquota's. HTTP rate-limit-headers beschrijven API-verzoeken; ze vormen geen SMTP-verzendsnelheidsbudget.

SMTP-antwoorden afhandelen

SMTP meldt een niet-geverifieerd verzenddomein, gereserveerd ontvangerdomein, onbruikbare IP-pool, geblokkeerd bijlagetype of ongeldig bericht met een permanent 550-antwoord. Een bericht boven de limiet van 20 MB geeft 552 terug. Een overschreden verzendquotum of een aantal ontvangers boven de 50 geeft een tijdelijk 452 terug. Onderdrukte ontvangers worden asynchroon afgehandeld: SMTP accepteert het bericht en vervolgens verschijnt elke onderdrukte ontvanger als rejected in het e-maillogboek en de events.

Vergelijk voor de interfacekeuze SMTP- en HTTP-verzending en -herstel. Beide paden plaatsen werk in de wachtrij vóór bezorging aan de ontvanger. Een email.delivered-event registreert acceptatie door de ontvangende server. Dat event bevestigt geen inboxplaatsing.

Volgende stappen

• Verzenddomeinen: verifieer het domein waarvandaan je verzendt.
• Dedicated IP's en pools: kies vanuit welke pool een key verzendt.
• Suppressies: waarom een geaccepteerde ontvanger een bericht mogelijk niet ontvangt.
• E-maillog: zoek een bericht op aan de hand van het ID dat SMTP heeft teruggegeven.