SMTP dla Node.js — poczta z Państwa aplikacji, która dociera
Node.js nie ma wbudowanej funkcji pocztowej; praktycznie każda aplikacja używa do tego Nodemailera. Ta biblioteka ułatwia wysyłkę, ale nic nie mówi o dostarczalności: ta zależy w całości od serwera SMTP, przez który Państwo wysyłają.
Nodemailer pracuje z transportem. Tworzą Państwo transport SMTP z danymi swojego relaya — hostem, portem, szyfrowaniem i loginem — a reszta kodu zostaje bez zmian. To, co dziś wychodzi przez serwer lokalny albo konto testowe, jutro idzie przez 2mail.
Dlaczego bez relaya coś idzie nie tak
Aplikacja w Node.js wysyła pocztę zwykle w momencie, w którym to się liczy: kod weryfikacyjny, reset hasła, potwierdzenie rezerwacji. To wiadomości oczekiwane w ciągu kilku sekund. Gdy wychodzą z serwera bez reputacji, część z nich nie dociera albo dociera za późno — a użytkownik klika „wyślij ponownie”, aż się podda.
Konfiguracja SMTP w Node.js
Pobranie danych
Zaloguj się na swoje konto 2mail i pobierz stamtąd serwer SMTP, nazwę użytkownika oraz hasło.
Wpisanie w Node.js
Prosimy utworzyć w Nodemailerze transport SMTP. Jako host prosimy podać serwer SMTP 2mail, a jako port 587, i wyłączyć opcję secure, aby połączenie zostało podniesione przez STARTTLS. Pod auth prosimy wpisać nazwę użytkownika i hasło swojego loginu 2mail. Prosimy odczytywać te dane ze zmiennych środowiskowych, a nie z kodu. Nodemailer ma metodę verify do sprawdzenia połączenia, zanim wyślą Państwo pierwszą prawdziwą wiadomość — prosimy z niej skorzystać.
Uwierzytelnienie domeny
Zadbaj o poprawne ustawienie SPF, DKIM i DMARC dla swojej domeny, aby odbiorcy mogli zweryfikować, że wiadomość pochodzi od Ciebie.
Test
Wyślij ze swojej platformy wiadomość testową na adres u dużego dostawcy i sprawdź, czy trafia do skrzynki odbiorczej, a nie do spamu.
Pola, o które prosi Node.js
Każda platforma nazywa je nieco inaczej, ale zawsze chodzi o te same pięć. Konkretne wartości są powiązane z kontem i znajdą je Państwo na swoim koncie 2mail — prosimy je stamtąd przepisać, aby mieć pewność, że są właściwe.
| Pole | Co wpisać |
|---|---|
| Serwer SMTP (host) | Nazwa serwera z Państwa konta 2mail. |
| Port | Port odpowiadający wybranemu szyfrowaniu; Państwa konto pokazuje, który to. |
| Szyfrowanie | TLS. Nigdy nie wysyłają Państwo bez szyfrowania — inaczej dane logowania idą przez sieć otwartym tekstem. |
| Nazwa użytkownika | Login SMTP Państwa konta 2mail. |
| Hasło | Odpowiadające mu hasło. Nigdy nie należy używać hasła do skrzynki pracownika. |
Konfiguracja SMTP dla Node.js w kodzie
Działające przykłady dla portu 587 ze STARTTLS, gotowe do skopiowania. Prosimy zastąpić adres nadawcy adresem we własnej domenie oraz sprawdzić nazwę serwera i login na swoim koncie 2mail. Miejsce hasła jest w zmiennej środowiskowej — nigdy w kodzie i nigdy w systemie kontroli wersji.
Nodemailer: createTransport dla portu 587
Jeden transport, utworzony przy starcie i używany wszędzie. Kombinacja secure: false i requireTLS: true jest właściwa dla portu 587: połączenie zaczyna się bez szyfrowania, zostaje podniesione do TLS przez STARTTLS, a Nodemailer odmawia dalszej pracy, gdy to podniesienie się nie powiedzie. Login i hasło pochodzą ze zmiennych środowiskowych.
// mailer.js
const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransport({
host: 'relay.2mail.eu',
port: 587,
secure: false, // 587 starts plain and upgrades with STARTTLS; true is for port 465 only
requireTLS: true, // refuse to continue if the upgrade to TLS fails
auth: {
user: process.env.SMTP_USERNAME,
pass: process.env.SMTP_PASSWORD,
},
});
module.exports = transporter;Test połączenia za pomocą verify() i pierwsza wiadomość
verify() przechodzi całe logowanie, niczego nie wysyłając, i zgłasza błąd z polem code, po którym rozpoznają Państwo przyczynę — zob. tabelę komunikatów o błędach poniżej. Przy prawdziwej wysyłce prosimy logować messageId i odpowiedź serwera: to Państwa dowód, że relay przyjął wiadomość.
const transporter = require('./mailer');
async function main() {
// Checks DNS, port, TLS and login without sending anything.
await transporter.verify();
const info = await transporter.sendMail({
from: '"Example" <noreply@example.com>',
to: 'you@example.org',
subject: 'SMTP test',
text: 'Sent through the 2mail SMTP relay.',
});
console.log(info.messageId, info.response);
}
main().catch((err) => {
console.error(err.code, err.message);
process.exit(1);
});Większe wolumeny: pula połączeń
Jeśli Państwa aplikacja wysyła falami — runda przypomnień, seria powiadomień — prosimy pozwolić Nodemailerowi utrzymywać niewielką liczbę otwartych połączeń, zamiast zestawiać nowe dla każdej wiadomości. To szybsze i nie wygląda dla relaya jak nadużycie.
const transporter = nodemailer.createTransport({
pool: true, // keep connections open and reuse them
maxConnections: 3,
maxMessages: 100, // per connection, then reconnect
host: 'relay.2mail.eu',
port: 587,
secure: false,
requireTLS: true,
auth: {
user: process.env.SMTP_USERNAME,
pass: process.env.SMTP_PASSWORD,
},
});Jakie wiadomości wysyła Node.js
Gdy relay jest już skonfigurowany, wszystkie idą przez 2mail — nie trzeba ich konfigurować pojedynczo.
Pułapki przy Node.js
secure i port muszą do siebie pasować
Opcja secure nie oznacza „bezpiecznie albo niebezpiecznie”, lecz „TLS od pierwszego bajtu”. Na porcie 587 secure powinno być wyłączone — STARTTLS następuje potem. Gdy mimo to je włączą, połączenie wisi albo zostaje od razu zerwane, bez wyraźnego błędu.
Jeden transport, używany wielokrotnie
Prosimy utworzyć transport raz przy starcie i używać go wielokrotnie, zamiast zakładać nowy przy każdej wiadomości. Przy skoku — rundzie przypomnień, kampanii — otworzą Państwo inaczej setki połączeń naraz, co relay może odczytać jako nadużycie. Nodemailer potrafi łączyć połączenia w pulę; prosimy to włączyć przy większych wolumenach.
Prosimy poczekać na wynik i go zalogować
Wysyłka jest asynchroniczna. Kto nie czeka na odpowiedź serwera albo jej nie loguje, nigdy nie zobaczy, że wiadomość została odrzucona. Prosimy logować co najmniej identyfikator wiadomości i ewentualne odrzucenie, a najlepiej podłączyć webhooki 2mail dla dostarczenia i odbicia, aby widzieć też, co psuje się po przekazaniu.
Częste komunikaty o błędach przy Node.js
Komunikaty, które zobaczą Państwo, gdy host, port, szyfrowanie albo login się nie zgadzają — przytoczone dosłownie, aby dało się je rozpoznać w logu, wraz z przyczyną i rozwiązaniem obok.
| Komunikat | Przyczyna | Rozwiązanie |
|---|---|---|
Error: connect ECONNREFUSED 127.0.0.1:587 | Nodemailer łączy się z Państwa własną maszyną zamiast z relayem. Opcja host jest pusta albo ma wartość undefined — zwykle to zmienna środowiskowa, która nie istnieje w produkcji — i wtedy Nodemailer wraca do localhost. | Prosimy zalogować opcje tuż przed createTransport i sprawdzić, czy host faktycznie zawiera relay.2mail.eu. |
Error: Connection timeout | Relay nie odpowiada (err.code ma wartość ETIMEDOUT). Ruch wychodzący na porcie 587 zatrzymuje zapora Państwa dostawcy hostingu, kontenera albo platformy chmurowej. | Prosimy przetestować z tej samej maszyny poleceniem openssl s_client -starttls smtp -connect relay.2mail.eu:587 i zlecić otwarcie portu 587 dla ruchu wychodzącego. |
Error: Invalid login: 535 5.7.8 Error: authentication failed | Relay odrzuca login (err.code ma wartość EAUTH): błędna nazwa użytkownika albo błędne hasło, albo pusta zmienna środowiskowa, przez którą Nodemailer loguje się bez loginu albo z pustym loginem. | Prosimy sprawdzić SMTP_USERNAME i SMTP_PASSWORD w środowisku, w którym działa proces, i użyć loginu SMTP z Państwa konta 2mail — a nie hasła do skrzynki pocztowej. |
Error: …:SSL routines:ssl3_get_record:wrong version number | secure: true na porcie 587. Nodemailer zaczyna wtedy od razu od uzgadniania TLS, podczas gdy relay na tym porcie oczekuje najpierw zwykłego SMTP i przełącza się dopiero po STARTTLS. | Prosimy ustawić secure: false i requireTLS: true. Połączenie jest wtedy szyfrowane równie dobrze. |
Error: self signed certificate | Certyfikat przedstawia nie relay, lecz coś po drodze: firmowe proxy albo antywirus przechwytujący TLS, albo lokalny serwer testowy, na który wciąż wskazuje host. | Prosimy naprawić trasę, zamiast wyłączać weryfikację. tls: { rejectUnauthorized: false } sprawia, że błąd znika, ale wysyła Państwa login do każdego, kto podaje się za relay. |
Inna platforma?
SMTP to protokół standardowy: każdy system, który mówi po SMTP — CRM, ERP, własna aplikacja albo serwer — może wysyłać przez 2mail z użyciem tych samych pięciu pól.
