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.

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

Poort	Versleuteling
465	Impliciet TLS (SMTPS)
587	STARTTLS
2525	STARTTLS

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.

In beide gevallen is de sessie versleuteld voordat je inloggegevens worden verzonden, zodat ze nooit onversleuteld over de lijn gaan: op 587 en 2525 wordt AUTH geweigerd totdat STARTTLS is doorlopen. Poort 25 wordt niet aangeboden voor indiening.

Authenticeren

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

Codevoorbeeld

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 authenticatie uitvoert. 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 blokkeert de SMTP-verzending binnen enkele seconden, ook midden in een verbinding.

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

Alles met een natuurlijke 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 Bcc. Een bericht kan maximaal 50 ontvangers hebben over to, cc en bcc, en de totale berichtgrootte is beperkt tot 20 MB.

Verzendopties die geen standaardplek in een MIME-bericht hebben, komen uit de SMTP-configuratie van de key. Dit omvat 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 wanneer 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 vervolgens de volledige SMTP-dialoog daarbinnen uit:

Codevoorbeeld

   ... 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 platte tekst, geeft STARTTLS om de verbinding te upgraden en voert vervolgens dezelfde dialoog uit binnen TLS. AUTH wordt pas aangeboden nadat de upgrade is voltooid:

Codevoorbeeld

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 agressief opnieuw wanneer een verbinding wegvalt. Om een herpoging veilig te maken, voeg je een X-Bird-Idempotency-Key-header toe aan het bericht: een herhaling binnen het retentievenster retourneert het ID 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 per poging.

Bewaar het ID van het in de wachtrij geplaatste bericht samen met het applicatie-event dat de verzending heeft veroorzaakt. Als de verbinding wegvalt voordat je het laatste antwoord ontvangt, probeer dat logische bericht dan opnieuw met dezelfde key. Na het retentievenster kan een herpoging 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 het sluiten ervan, over alle servers en API-keys in de organisatie. Bij het bereiken van de limiet ontvangt een volgende verbinding een tijdelijk 421-antwoord na authenticatie. Hergebruik verbindingen, verlaag de gelijktijdigheid en probeer opnieuw. De limiet telt open verbindingen onafhankelijk van het berichtvolume. Email > SMTP toont actieve verbindingen ten opzichte van de limiet.

Stem je verbindingspool af op de verbindingslimiet van de organisatie. Doseer indieningen op basis van verzendquota. HTTP rate-limit headers beschrijven API-requests; ze zijn geen SMTP-verzendsnelheidstoewijzing.

SMTP-antwoorden afhandelen

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

Vergelijk voor de interfacekeuze SMTP- en HTTP-indiening 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 mogelijk geen bericht ontvangt.
E-maillogboek: zoek een bericht op aan de hand van het ID dat SMTP heeft geretourneerd.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Ontdek de mogelijkheidSMTP relay