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 supresji, ś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.

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

Port	Szyfrowanie
465	Niejawne TLS (SMTPS)
587	STARTTLS
2525	STARTTLS

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.

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

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:

Przykład kodu

Username: bird
Password: bk_eu1_your_api_key

Nazwa użytkownika to stały literał i nie ma własnej tożsamości. Klucz API w polu hasła jest tym, co uwierzytelnia. 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łanie SMTP w ciągu sekund, łącznie z trwającymi połączeniami.

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ć najwyżej 50 odbiorców łącznie w polach to, cc i bcc, a maksymalny rozmiar wiadomości to 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 i włączonego śledzenia. Skonfiguruj klucz w Email > SMTP lub wywołaj SMTP config API. Przydziel każdej aplikacji osobny klucz, jeśli potrzebuje innych wartości domyślnych. Zmiany obowiązują dla nowych wiadomości bez konieczności ponownego łączenia klienta.

Pełna sesja

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

Przykład kodu

   ... 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ę nieszyfrowanie, wydaje STARTTLS, aby uaktualnić połączenie, a następnie prowadzi ten sam dialog wewnątrz TLS. AUTH nie jest oferowane, dopóki uaktualnienie się nie zakończy:

Przykład kodu

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 otrzymasz z API. Możesz wyszukać wiadomość po tym ID w Logu e-maili lub przez GET /v1/email/messages/{message_id}.

Bezpieczne ponawianie

Pipeline przyjmuje wiadomość i dostarcza ją asynchronicznie, a klienci 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órka w obrębie okna retencji zwraca ID już zakolejkowanej wiadomości zamiast wysyłać drugą kopię. Użyj wartości stabilnej dla danej wiadomości logicznej, np. ID zamówienia lub ID powiadomienia. Unikaj generowania losowej wartości przy każdej próbie.

Zachowuj ID zakolejkowanej wiadomości razem ze zdarzeniem aplikacji, które spowodował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ść. Przechowuj własny rekord wysyłki na wypadek 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, niezależnie od serwera i klucza API w organizacji. Po osiągnięciu limitu kolejne połączenie otrzymuje przejściową odpowiedź 421 po uwierzytelnieniu. Używaj połączeń ponownie, zmniejsz współbieżność i ponawiaj próby. Limit liczy otwarte połączenia niezależnie od liczby wiadomości. Email > SMTP pokazuje aktywne połączenia w stosunku do limitu.

Dobierz rozmiar puli połączeń do limitu połączeń organizacji. Dostosuj tempo przesyłania do limitów wysyłki. 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ę wysyłkową, 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łki lub liczba odbiorców powyżej 50 zwraca przejściową odpowiedź 452. Stłumieni odbiorcy są obsługiwani asynchronicznie: SMTP przyjmuje wiadomość, a każdy stłumiony odbiorca pojawia się jako rejected w logu e-maili i zdarzeniach.

Aby wybrać interfejs, porównaj przesyłanie i odtwarzanie SMTP i HTTP. Obie ścieżki kolejkują pracę przed dostarczeniem do odbiorcy. Zdarzenie email.delivered rejestruje przyjęcie przez serwer odbierający. 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 klucz.
Supresje: dlaczego zaakceptowany odbiorca może nie otrzymać wiadomości.
Log e-maili: znajdź wiadomość po ID zwróconym przez SMTP.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Poznaj możliwościSMTP relay