SMTP dla Laravela — poczta z Państwa aplikacji, która dociera
Laravel ma wbudowaną pełnoprawną warstwę pocztową, z kolejkami, szablonami i powiadomieniami. Czego nie dostarcza, to dostarczalność: ta zależy od serwera, przez który Państwo wysyłają, a domyślna konfiguracja na świeżym serwerze rzadko jest dobrym nadawcą.
Laravel odczytuje ustawienia poczty z konfiguracji środowiska. Zmieniają tam Państwo dane SMTP, a reszta aplikacji zostaje bez zmian — bez ruszania mailables, powiadomień i kolejek.
Dlaczego bez relaya coś idzie nie tak
Aplikacja w budowie wysyła na adres testowy i wszystko wygląda dobrze. Przy uruchomieniu zmienia się publiczność: prawdziwe adresy u prawdziwych dostawców, którzy <em>faktycznie</em> sprawdzają uwierzytelnianie i reputację. To moment, w którym wiadomości resetujące hasło nagle przestają docierać — do części użytkowników, co utrudnia rozpoznanie problemu.
Konfiguracja SMTP w Laravel
Pobranie danych
Zaloguj się na swoje konto 2mail i pobierz stamtąd serwer SMTP, nazwę użytkownika oraz hasło.
Wpisanie w Laravel
Ustawienia poczty znajdują się w pliku środowiskowym aplikacji, a nie w kodzie. Prosimy ustawić mailer na SMTP i wpisać pięć poniższych danych. Prosimy nie zapomnieć o adresie i nazwie nadawcy: stoją one jako osobne ustawienia obok danych połączenia.
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 Laravel
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 Laravel 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.
Plik .env: zmienne MAIL_*
Laravel odczytuje wszystkie dane połączenia z pliku .env. Port 587 działa ze STARTTLS: połączenie zaczyna się bez szyfrowania i zostaje podniesione do TLS, zanim Państwa login w ogóle pójdzie przez sieć. Hasło znajduje się wyłącznie w pliku .env na serwerze — ten plik nie powinien trafiać do systemu kontroli wersji. Prosimy zastąpić example.com domeną, którą uwierzytelnili Państwo w 2mail.
MAIL_MAILER=smtp
MAIL_HOST=relay.2mail.eu
MAIL_PORT=587
MAIL_USERNAME="<2mail-smtp-login>"
MAIL_PASSWORD="<2mail-smtp-password>"
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"
# Only when config/mail.php still has an 'encryption' key (older projects):
MAIL_ENCRYPTION=tls
# When config/mail.php has a 'scheme' key instead: leave MAIL_SCHEME unset.
# "smtp" on port 587 upgrades to STARTTLS by itself; "tls" is not a valid scheme.config/mail.php: mailer smtp
W standardowym projekcie nie muszą Państwo niczego tu zmieniać: plik po prostu odczytuje zmienne z .env. Prosimy jednak do niego zajrzeć, gdy jakieś ustawienie nie daje efektu — host wpisany na sztywno w tym pliku zawsze wygrywa z Państwa .env. Nowsze projekty mają klucz scheme, starsze klucz encryption; reszta jest identyczna.
// config/mail.php
'default' => env('MAIL_MAILER', 'smtp'),
'mailers' => [
'smtp' => [
'transport' => 'smtp',
'scheme' => env('MAIL_SCHEME'), // newer projects
// 'encryption' => env('MAIL_ENCRYPTION', 'tls'), // older projects use this key instead
'host' => env('MAIL_HOST', 'relay.2mail.eu'),
'port' => env('MAIL_PORT', 587),
'username' => env('MAIL_USERNAME'),
'password' => env('MAIL_PASSWORD'),
'timeout' => null,
],
],
'from' => [
'address' => env('MAIL_FROM_ADDRESS', 'noreply@example.com'),
'name' => env('MAIL_FROM_NAME', 'Example'),
],Wysyłka wiadomości testowej przez Tinker
Prosimy najpierw wyczyścić cache konfiguracji, inaczej będą Państwo testować jeszcze stare ustawienia. Mail::raw wysyła synchronicznie: błąd w hoście, porcie albo loginie widać od razu w terminalu, a nie dopiero w logu kolejki. Prosimy wysłać na adres zewnętrzny u dużego dostawcy.
php artisan config:clear
php artisan tinker
# At the tinker prompt:
Mail::raw('Sent through the 2mail SMTP relay.', fn ($m) => $m->to('you@example.org')->subject('SMTP test'));Jakie wiadomości wysyła Laravel
Gdy relay jest już skonfigurowany, wszystkie idą przez 2mail — nie trzeba ich konfigurować pojedynczo.
Pułapki przy Laravel
Kolejka musi działać
Jeśli umieszczą Państwo pocztę w kolejce bez aktywnego procesu przetwarzającego, nic nie wychodzi, a żaden błąd się nie pojawia. Przy problemie z dostarczaniem powinna to być pierwsza kontrola, a nie ostatnia.
Cache konfiguracji po zmianie
Jeśli aplikacja działa z zapisaną w cache konfiguracją, zmienione ustawienia poczty pozostają bez efektu do czasu odświeżenia tego cache. Ustawienie, które „nie działa”, często po prostu nie zostało jeszcze wczytane.
Środowiska testowe, które naprawdę wysyłają
Środowisko staging z kopią bazy produkcyjnej może niezauważenie wysyłać do prawdziwych klientów. Prosimy wyraźnie ograniczyć tam odbiorców albo użyć osobnego loginu.
Częste komunikaty o błędach przy Laravel
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 |
|---|---|---|
Connection could not be established with host "relay.2mail.eu:587": stream_socket_client(): Unable to connect to relay.2mail.eu:587 (Connection timed out) | Państwa serwer nie może połączyć się z relayem. Zwykle zapora dostawcy hostingu blokuje ruch wychodzący na porcie 587 albo w MAIL_HOST lub MAIL_PORT jest literówka. | Prosimy przetestować z tego samego serwera poleceniem openssl s_client -starttls smtp -connect relay.2mail.eu:587. Jeśli nie ma odpowiedzi, prosimy zwrócić się do dostawcy hostingu o otwarcie ruchu wychodzącego na porcie 587. |
Connection could not be established with host "ssl://relay.2mail.eu:587": stream_socket_client(): SSL operation failed with code 1. OpenSSL Error messages: error:…:SSL routines::wrong version number | Scheme jest ustawiony na smtps (albo, w starszym projekcie, MAIL_ENCRYPTION=ssl). Laravel oczekuje wtedy TLS od pierwszego bajtu, podczas gdy port 587 zaczyna bez szyfrowania i dopiero potem podnosi połączenie przez STARTTLS. | Prosimy zostawić MAIL_SCHEME puste albo ustawić je na smtp; w starszym projekcie prosimy ustawić MAIL_ENCRYPTION=tls. Port pozostaje 587. |
Failed to authenticate on SMTP server with username "…" using the following authenticators: "LOGIN", "PLAIN". … Expected response code "235" but got code "535" | Relay odrzuca login: błędna nazwa użytkownika albo błędne hasło, hasło ze spacją albo znakiem #, które w .env nie jest ujęte w cudzysłów, albo stara konfiguracja zapisana w cache. | Prosimy ująć wartość w podwójny cudzysłów, uruchomić php artisan config:clear i użyć loginu SMTP z Państwa konta 2mail — a nie hasła do skrzynki pocztowej. |
The "tls" scheme is not supported; supported schemes for mailer "smtp" are: "smtp", "smtps". | W MAIL_SCHEME wpisano tls. Ta zmienna nie jest następcą MAIL_ENCRYPTION: zna wyłącznie smtp i smtps. | Prosimy usunąć MAIL_SCHEME albo ustawić je na smtp. Na porcie 587 mailer sam przełącza się na STARTTLS. |
Expected response code "250/251/252" but got code "554", with message "554 5.7.1 <noreply@example.com>: Sender address rejected" | Login jest poprawny, ale adres nadawcy znajduje się w domenie, która nie jest powiązana z Państwa kontem 2mail. Często MAIL_FROM_ADDRESS ma jeszcze wartość domyślną z pliku przykładowego. | Prosimy ustawić MAIL_FROM_ADDRESS na adres w domenie dodanej przez Państwa w 2mail i sprawdzić, czy żaden Mailable nie ustawia własnego from() w innej domenie. |
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.
