API inboxsink

Skrzynki jednorazowe sterowane kodem, do testowania rejestracji bez zależności od prawdziwej poczty. Pięć tras, jedna baza pod https://inboxsink.com, JSON.

Trasa, która coś zmienia, to wait: blokuje aż do nadejścia wiadomości. Bez niej test end-to-end zgaduje przez sleep i staje się niestabilny, gdy tylko kolejka wysyłki się opóźni.

Darmowy klucz API

Tysiąc wywołań miesięcznie, bez karty. Tyle, by wpiąć je w swój zestaw testów i sprawdzić, czy się trzyma.

Załóż darmowe konto Cennik

Później, gdy twoje testy zaczną być odrzucane: własna domena nigdzie nie jest publikowana, więc nie trafia na żadną czarną listę — 29 € miesięcznie.

Klient JavaScript

Pakiet bez żadnych zależności, dla Node 18 i nowszych. Kod na GitHubie.

npm i inboxsink

import { InboxSink } from 'inboxsink';
const sink = new InboxSink(process.env.INBOXSINK_API_KEY);

const inbox = await sink.createInbox();
const code = await sink.waitForOtp(inbox.id);   // '204815'

waitForOtp rzuca błąd zamiast zwracać null, gdy żaden kod nie dotrze: test ma padać głośno, a nie po cichu wypełniać puste pole.

Uwierzytelnianie

Nagłówek Authorization przy każdym wywołaniu. Klucze tworzy się w panelu i zaczynają się od ibsk_.

curl -H "Authorization: Bearer ibsk_…" \
  https://inboxsink.com/v1/domains

Klucz jawnym tekstem pokazujemy tylko przy tworzeniu. Potem widoczny jest wyłącznie jego prefiks — przechowujemy jedynie skrót.

Utworzyć skrzynkę

POST /v1/inboxes

Wszystkie parametry są opcjonalne: domain (domyślnie losowa domena z puli), prefix (domyślnie losowy), ttl_seconds (od 60 sekund do 30 dni).

curl -X POST https://inboxsink.com/v1/inboxes \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 900}'

→ 201
{ "id": "42", "address": "9f2c1a@mailhusk.com", "expires_at": "2026-09-01T15:12:00Z" }

Skrzynka utworzona przez API jest prywatna: może ją czytać wyłącznie klucz, który ją utworzył.

Czekać na wiadomość

GET /v1/inboxes/:id/wait

Blokuje aż do nadejścia wiadomości, potem odpowiada natychmiast. timeout w milisekundach (domyślnie 30 000, maksymalnie 120 000), since aby otrzymać tylko wiadomości po danym identyfikatorze.

Odpowiada 204 bez treści, jeśli czas minie bez wiadomości — to nie błąd, to normalna odpowiedź na «nic nie przyszło».

curl -H "Authorization: Bearer $KEY" \
  "https://inboxsink.com/v1/inboxes/42/wait?timeout=45000"

→ 200
{ "message": { "id": "913", "from": "no-reply@acme.com", "subject": "…",
               "otp": "204815", "link": "https://acme.com/confirm/9f3a" } }

otp i link są wyodrębnione za ciebie. Kod jest zgłaszany tylko wtedy, gdy wiadomość faktycznie go zapowiada («kod», «weryfikacja», «logowanie»…) — kwota faktury ani rok nigdy nie zostaną z nim pomylone.

Wypisać wiadomości

GET /v1/inboxes/:id/messages

Przyjmuje since i limit (domyślnie 50, maksymalnie 200). Zwraca podsumowania, bez treści wiadomości.

Przeczytać wiadomość

GET /v1/messages/:id

Pełna wiadomość: text, html, headers i lista załączników.

Usunąć skrzynkę

DELETE /v1/inboxes/:id

Kasuje skrzynkę i jej wiadomości natychmiast. Odpowiada 204.

Błędy

204	Brak treści — przy `wait` czas minął bez wiadomości
400	Nieprawidłowy parametr
401	Klucz brakujący, nieznany lub odwołany
403	Ta skrzynka należy do innego klucza
404	Skrzynka lub wiadomość nie istnieje albo wygasła
429	Zbyt wiele wywołań

Limity i czas życia

Skrzynki z publicznej puli żyją godzinę; utworzone przez API stosują się do swojego ttl_seconds, do trzydziestu dni. Po tym czasie skrzynka i wiadomości są usuwane — nie ma archiwum do odzyskania.

Wiadomości powyżej dziesięciu megabajtów są odrzucane przy odbiorze. Adresy z nieznanej domeny są odrzucane w trakcie sesji SMTP, bez generowania odbicia.

Te skrzynki nie mogą wysyłać poczty, i jest to zamierzone: wiadomość wysłana z domeny jednorazowej nigdzie by nie dotarła.