Wysyłanie e-maili przez SMTP

Jeśli Twoja aplikacja obsługuje już SMTP, skieruj ją na nasz relay, zmieniając hosta, port i dane uwierzytelniające. Frameworki, systemy zarządzania treścią, drukarki i inne oprogramowanie, które potrafi przekazać pocztę do relay SMTP, mogą korzystać z tej ścieżki.

Poczta przesłana przez SMTP jest traktowana dokładnie tak samo jak poczta wysłana przez e-mailowe API: ta sama weryfikacja domeny, pule IP, podpisywanie DKIM, obsługa suppresji, śledzenie, zdarzenia i analityka. SMTP to druga droga do tego samego produktu, więc wszystko, co skonfigurujesz dla jednej, działa też dla drugiej.

Wybierz relay SMTP, gdy chcesz zachować istniejący kod budowania wiadomości w aplikacji. Wybierz e-mailowe API, gdy potrzebujesz ustrukturyzowanych pól żądania lub zapisanych szablonów. SMTP pobiera treść z wiadomości MIME, a opcje wysyłki z konfiguracji klucza API.

Wymagania wstępne

• Zweryfikowana domena wysyłkowa. Adres podany w MAIL FROM (oraz nagłówek From wiadomości) musi należeć do domeny zweryfikowanej w tym obszarze roboczym. Zobacz Domeny wysyłkowe.
• Klucz API z uprawnieniem emails. SMTP korzysta ze zwykłych kluczy API i nie wymaga osobnych danych uwierzytelniających SMTP. Utwórz klucz w Developers > Klucze API z włączonym wysyłaniem e-maili. Klucz bez uprawnienia emails nie może wysyłać, podobnie jak klucz wyłącznie verify.

Ustawienia połączenia

Skieruj klienta na hosta SMTP odpowiadającego regionowi Twojego klucza. Region to prefiks w samym kluczu: klucz bk_eu1_... wysyła przez hosta eu1, klucz bk_us1_... przez us1. Uwierzytelnienie kluczem z innego regionu kończy się odpowiedzią 535 wskazującą właściwego hosta.

Użyj tego, który obsługuje Twój klient:

• Port 465, niejawne TLS (SMTPS). Połączenie jest szyfrowane od pierwszego bajtu, zanim zostanie wysłana jakakolwiek komenda. W większości bibliotek jest to opcja "SSL/TLS" lub "SMTPS".
• Porty 587 i 2525, STARTTLS. Połączenie otwiera się jako nieszyfrowane i przechodzi na TLS komendą STARTTLS przed uwierzytelnieniem. Jest to opcja "STARTTLS", czasem oznaczana po prostu jako "TLS". Wybierz 2525, jeśli Twoja sieć blokuje 587.

Wersje TLS: Porty 465, 587 i 2525 obsługują TLS 1.2 oraz TLS 1.3. Skonfiguruj klienta tak, aby używał TLS 1.2 lub nowszego. TLS 1.0 i TLS 1.1 nie są obsługiwane.

W obu przypadkach sesja jest szyfrowana, zanim dane uwierzytelniające zostaną wysłane, więc nigdy nie wędrują otwartym tekstem: na portach 587 i 2525 AUTH jest odrzucane, dopóki nie zakończy się STARTTLS. Port 25 nie jest udostępniany do wysyłki.

Uwierzytelnianie

Uwierzytelnij się za pomocą AUTH PLAIN lub AUTH LOGIN. Nazwa użytkownika to literalny ciąg bird, a hasło to Twój klucz API:

Username: bird
Password: bk_eu1_your_api_key

Nazwa użytkownika to stały literał i nie ma własnej tożsamości. Uwierzytelnia klucz API podany w polu hasła. W większości narzędzi SMTP wklejasz klucz API w pole hasła i ustawiasz nazwę użytkownika na bird. Unieważnienie klucza odcina jego wysyłkę SMTP w ciągu sekund, również w trakcie trwającego połączenia.

Co pochodzi z wiadomości, a co z konfiguracji klucza

Wszystko, co ma naturalne miejsce w wiadomości MIME, pochodzi z samej wiadomości: nagłówki From, To, Cc i Reply-To, temat, treść HTML i tekstowa oraz załączniki i obrazy inline. Odbiorcy są pobierani z koperty SMTP (RCPT TO). Adres w RCPT TO, którego nie ma w widocznym nagłówku To ani Cc, jest traktowany jako Bcc. Wiadomość może mieć maksymalnie 50 odbiorców łącznie w polach to, cc i bcc, a całkowity rozmiar wiadomości jest ograniczony do 20 MB.

Opcje wysyłki, które nie mają standardowego miejsca w wiadomości MIME, pochodzą z konfiguracji SMTP klucza. Obejmują one pulę IP, kategorię, tagi oraz śledzenie otwarć i kliknięć. Nieskonfigurowany klucz używa domyślnej puli organizacji, kategorii transactional oraz włączonego śledzenia. Skonfiguruj klucz w Email > SMTP lub wywołaj SMTP config API. Przypisz każdej aplikacji osobny klucz, gdy potrzebuje innych wartości domyślnych. Zmiany obowiązują dla nowych wiadomości bez ponownego łączenia klienta.

Pełna sesja

Na porcie 465 klient najpierw otwiera połączenie TLS, a potem prowadzi cały dialog SMTP wewnątrz niego:

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

Na porcie 587 lub 2525 klient łączy się otwartym tekstem, wydaje STARTTLS, aby podnieść połączenie, a następnie prowadzi ten sam dialog wewnątrz TLS. AUTH nie jest oferowane, dopóki podniesienie się nie zakończy:

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

Końcowe 250 zwraca ID zakolejkowanej wiadomości, ten sam identyfikator em_..., który otrzymałbyś z API. Możesz wyszukać wiadomość po tym ID w Email log lub przez GET /v1/email/messages/{message_id}.

Bezpieczne ponawianie

Potok przyjmuje wiadomość i dostarcza ją asynchronicznie, a klienty SMTP agresywnie ponawiają próby po zerwaniu połączenia. Aby ponowienie było bezpieczne, dodaj do wiadomości nagłówek X-Bird-Idempotency-Key: powtórzenie w oknie retencji zwraca ID już zakolejkowanej wiadomości zamiast wysyłać drugą kopię. Użyj wartości stałej dla danej wiadomości logicznej, np. ID zamówienia lub ID powiadomienia. Nie generuj losowej wartości przy każdej próbie.

Zachowaj ID zakolejkowanej wiadomości razem ze zdarzeniem aplikacji, które wywołało wysyłkę. Jeśli połączenie zostanie zerwane, zanim otrzymasz końcową odpowiedź, ponów tę wiadomość logiczną z tym samym kluczem. Po upływie okna retencji ponowienie może utworzyć kolejną wiadomość. Prowadź własny rejestr wysyłek na potrzeby odtwarzania po tym oknie.

Limity połączeń

Każda organizacja może domyślnie utrzymywać do 10 jednoczesnych uwierzytelnionych połączeń SMTP. Połączenie jest liczone od uwierzytelnienia do zamknięcia, we wszystkich serwerach i kluczach API w organizacji. Po osiągnięciu limitu kolejne połączenie otrzymuje tymczasową odpowiedź 421 po uwierzytelnieniu. Używaj połączeń ponownie, zmniejsz współbieżność i ponów próbę. Limit liczy otwarte połączenia niezależnie od wolumenu wiadomości. Email > SMTP pokazuje aktywne połączenia względem limitu.

Dostosuj pulę połączeń do limitu połączeń organizacji. Reguluj tempo wysyłek zgodnie z limitami wysyłania. HTTP nagłówki ograniczania liczby żądań opisują żądania API; nie stanowią limitu szybkości wysyłania SMTP.

Obsługa odpowiedzi SMTP

SMTP zgłasza niezweryfikowaną domenę nadawczą, zarezerwowaną domenę odbiorcy, nieużywalną pulę IP, zablokowany typ załącznika lub nieprawidłową wiadomość stałą odpowiedzią 550. Wiadomość przekraczająca limit 20 MB zwraca 552. Przekroczony limit wysyłania lub liczba odbiorców powyżej 50 zwraca tymczasową odpowiedź 452. Odbiorcy objęci suppresją są obsługiwani asynchronicznie: SMTP przyjmuje wiadomość, a następnie każdy odbiorca objęty suppresją pojawia się jako rejected w logu e-mail i zdarzeniach.

Przy wyborze interfejsu porównaj wysyłanie i odtwarzanie SMTP i HTTP. Obie ścieżki kolejkują pracę przed dostarczeniem do odbiorcy. Zdarzenie email.delivered rejestruje przyjęcie przez serwer odbiorczy. To zdarzenie nie potwierdza dostarczenia do skrzynki odbiorczej.

Następne kroki

• Domeny wysyłkowe: zweryfikuj domenę, z której będziesz wysyłać.
• Dedykowane IP i pule: wybierz, z której puli wysyła dany klucz.
• Suppresje: dlaczego zaakceptowany odbiorca może nie otrzymać wiadomości.
• Dziennik e-mail: znajdź wiadomość po ID zwróconym przez SMTP.