API e-mail i webhooki
Obok SMTP 2mail ma REST API: wysyłają Państwo wiadomość jednym wywołaniem HTTPS, sprawdzają potem jej status i pozwalają, aby każde zdarzenie — dostarczono, odbito, otwarto — było automatycznie wypychane do Państwa systemu przez webhook.
Ta strona opisuje, co robi API i jak działa dostęp. Pełna referencja ze wszystkimi polami i przykładowymi wywołaniami jest otwarta: mogą ją Państwo przeczytać, zanim założą konto. Jeśli pracują Państwo w PHP, oficjalne SDK zdejmie z Państwa pracę z HTTP.
Co dzięki temu Państwo zbudują
Wysyłka z Państwa aplikacji
Jedno POST z nadawcą, odbiorcą, tematem i treścią. Wiadomość można też zaplanować z wyprzedzeniem i przy każdej z osobna zdecydować, czy mierzone są otwarcia. Odpowiedź od razu zawiera identyfikator, po którym odnajdą Państwo wiadomość później.
Sprawdzenie statusu jednej wiadomości
Tym identyfikatorem sprawdzają Państwo, czy wiadomość czeka w kolejce, została wysłana czy zawiodła — wraz z powodem błędu. Dzięki temu nie muszą Państwo szukać w plikach logów, gdy klient dzwoni w sprawie jednego konkretnego e-maila.
Automatyczne odbieranie zdarzeń
Prosimy zarejestrować adres URL, a 2mail wypchnie tam każde zdarzenie, gdy tylko będzie nam znane: przyjęto, dostarczono, odroczono, odbito, odrzucono, otwarto albo nie powiodło się. Bez odpytywania, bez kolejki, którą trzeba samemu opróżniać.
Klucz dla każdego zastosowania
Każda aplikacja dostaje własny klucz, który mogą Państwo unieważnić z osobna. Klucz wysyłkowy może wyłącznie wysyłać i śledzić własne wiadomości — nic więcej, także żadnych innych danych z Państwa konta.
Wysłanie wiadomości
Wywołanie jest świadomie proste: klucz w nagłówku Authorization i treść w JSON-ie. Adres nadawcy musi należeć do jednej z Państwa własnych domen.
POST https://www.2mail.eu/2mail/api/v1/messages Authorization: Bearer 2m_live_UW_SLEUTEL Content-Type: application/json { "from": "no-reply@twojadomena.be", "to": "klient@przyklad.be", "subject": "Państwa zamówienie zostało wysłane", "html": "<p>Dziękujemy za zamówienie.</p>" }
202 Accepted { "id": "4f3c…", "status": "queued" }
Otrzymują Państwo z powrotem 202 z identyfikatorem. Oznacza to przyjęte, a nie dostarczone — samo dostarczenie śledzą Państwo zapytaniem o status albo, lepiej, webhookiem.
Wolą Państwo nie pisać HTTP? PHP SDK
composer require jaanbv/2mail-php-api $api = new TwoMail($apiKey); $api->sendMail( 'no-reply@twojadomena.be', 'klient@przyklad.be', 'Państwa zamówienie zostało wysłane', '<p>Dziękujemy za zamówienie.</p>' );
Dla PHP dostępny jest oficjalny klient pokrywający każdy powyższy endpoint. To samo wywołanie zajmuje cztery linie, a Państwo nie muszą sami utrzymywać opcji curl, kodowania JSON ani obsługi błędów.
SDK rozdziela adres nadawcy i nazwę wyświetlaną, sprawdza za Państwa podpisy webhooków i nadaje każdemu kodowi błędu własny wyjątek — dzięki czemu mogą Państwo reagować na typ błędu, a nie na tekst, który jutro może brzmieć inaczej.
Webhooki: dostarczanie śledzą Państwo biernie
Webhook to Państwa własny adres URL, który wywołujemy, gdy tylko coś dzieje się z Państwa wiadomością. Dzięki temu nie muszą Państwo okresowo sprawdzać statusu: odbicie trafia do Państwa samo, gdy tylko je przetworzymy.
POST https://twojadomena.be/webhooks/2mail X-2mail-Event: bounced X-2mail-Signature: t=1755417600,v1=<hmac-sha256> { "event": "bounced", "timestamp": "2026-08-17T10:04:11+02:00", "recipient": "klient@przyklad.be", "message_id": "<…>", "detail": "550 5.1.1 unknown", "code": "5.1.1" }
// $secret: eenmalig getoond bij aanmaak $body = file_get_contents('php://input'); parse_str(strtr($_SERVER['HTTP_X_2MAIL_SIGNATURE'], ',', '&'), $p); $ok = hash_equals( hash_hmac('sha256', $p['t'] . '.' . $body, $secret), $p['v1'] );
Każde wywołanie jest podpisane
Przesyłamy podpis w nagłówku X-2mail-Signature, obliczony jako HMAC-SHA256 z sygnatury czasowej i surowej treści, kluczem znanym tylko Państwu i nam. Prosimy sprawdzić ten podpis, zanim zaufają Państwo treści: bez kontroli każdy, kto zna Państwa adres URL, może wymyślać zdarzenia. W PHP nie muszą Państwo pisać tego samodzielnie: SDK wykonuje kontrolę w jednej linii, wraz ze sprawdzeniem okna czasowego, które blokuje ponowne użycie przechwyconego wywołania.
Nieudane wywołania są ponawiane
Jeśli Państwa endpoint nie odpowie kodem 2xx, próbujemy ponownie w rosnących odstępach — po minucie, pięciu minutach, pół godziny, dwóch godzinach i sześciu godzinach. W portalu widzą Państwo przy każdej próbie kod odpowiedzi i komunikat błędu, dzięki czemu mogą namierzyć wadliwy endpoint bez kontaktu z nami.
Jakie zdarzenia
Dostarczono, odroczono, odbito, odrzucono, otwarto, przyjęto i nie powiodło się. Dla każdego webhooka wybierają Państwo, które typy chcą odbierać, albo zostawiają puste, aby odbierać wszystkie.
Klucze i dostęp
Klucz API pokazywany jest jednorazowo, a potem przechowywany wyłącznie jako skrót. Jeśli go Państwo zgubią, unieważniają go i tworzą nowy — nie możemy pokazać go ponownie.
Klucz wysyłkowy
Należy do jednej skrzynki i może wyłącznie wysyłać i śledzić własne wiadomości: wysłać wiadomość, sprawdzić jej status, anulować ją, dopóki czeka w kolejce, i pobrać własny log zdarzeń. Każdy inny endpoint odpowie kodem 403. To ten klucz umieszczają Państwo w sklepie albo aplikacji.
Klucz administracyjny
Dla tych, którzy chcą programowo tworzyć skrzynki, domeny i użytkowników SMTP — na przykład partnera wdrażającego klientów we własnym zakresie. Tego klucza nie tworzą Państwo sami: prosimy zwrócić się o niego do nas.
Klucze wysyłkowe tworzą Państwo i zarządzają nimi sami w portalu klienta, w sekcji Ustawienia. Widzą tam Państwo również, kiedy każdy klucz był ostatnio używany.
Pełna dokumentacja
Każdy endpoint, każde pole i każdy kod błędu znajdują się w interaktywnej referencji. Można tam także od razu spróbować: prosimy kliknąć Authorize, wkleić swój klucz i wykonać prawdziwe wywołanie.
Specyfikacja jest publiczna i można ją zaimportować do Postmana albo Insomnii, a także wykorzystać do wygenerowania klienta. Interaktywna referencja również jest swobodnie dostępna — klucz będzie potrzebny dopiero wtedy, gdy zechcą Państwo naprawdę wykonać wywołanie.
Do dzieła
API jest wliczone w każdy pakiet 2mail; nie ma osobnej licencji ani modułu. Mają Państwo pytanie o integrację albo chcą wiedzieć, czy Państwa scenariusz pasuje? Prosimy dać nam znać — chętnie pomyślimy razem, zanim zaczną Państwo budować.