Dla programistów

API do weryfikacji adresów e-mail, które po prostu działa

Weryfikuj jeden adres w czasie rzeczywistym lub wyślij całą listę jako partię. Wszystkie żądania używają HTTPS i zwracają JSON. Klucze API utworzysz w panelu, w sekcji Klucze API.

Uzyskaj klucz API Przeczytaj dokumentację

REST i JSON
Wywołania zwrotne dla partii
Te same kredyty co w panelu

Strona kluczy API w BounceBell z aktywnymi kluczami i formularzem tworzenia nowego klucza

verify.sh

# Verify one addresscurl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth@acme-foods.com" \  -H "Authorization: Bearer YOUR_API_KEY" { "status": "valid",  "reason": "mailbox_exists",  "did_you_mean": null }

Uwierzytelnianie

Przesyłaj klucz API jako token typu bearer w nagłówku Authorization każdego żądania. Przechowuj klucze na swoim serwerze. Nigdy nie umieszczaj ich w kodzie przeglądarki ani w aplikacjach mobilnych.

Authorization: Bearer YOUR_API_KEY

Bazowy URL każdego endpointu to https://bouncebell.com/api/v1.

Zweryfikuj jeden adres

GET https://bouncebell.com/api/v1/verify

Parametr	Wymagane	Opis
`email`	Tak	Adres do sprawdzenia. Zakoduj go w formacie URL.
`timeout`	Nie	Czas oczekiwania na serwer pocztowy w sekundach, od 3 do 30. Domyślnie 10. Jeśli czas minie, status to `unknown` i kredyt nie jest zużywany.

Przykład

curl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "rini.elizabeth@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

Pola wyniku

Pole	Typ	Opis
`email`	string	Adres w postaci, w jakiej został wysłany.
`status`	string	Werdykt. Zobacz statusy.
`reason`	string	Uzasadnienie werdyktu, na przykład `mailbox_not_found` lub `no_mail_server`.
`domain`	string	Część domenowa, małymi literami.
`mx_record`	string or null	Serwer pocztowy o najwyższym priorytecie.
`disposable`	boolean	True, jeśli domena jest usługą tymczasowych skrzynek.
`role`	boolean	True dla wspólnych skrzynek, takich jak info@ lub support@.
`free_provider`	boolean	True dla darmowych dostawców poczty, takich jak Gmail.
`catch_all`	boolean	True, gdy domena akceptuje każdy adres.
`did_you_mean`	string or null	Poprawiony adres, gdy domena wygląda na literówkę.
`checked_at`	string	Czas wykonania sprawdzenia w formacie ISO 8601 UTC.
`credits_used`	integer	1 lub 0, gdy status to `unknown`.

Statusy

Status	Znaczenie	Sugerowane działanie
`valid`	Skrzynka istnieje i przyjmuje pocztę.	Wyślij
`invalid`	Adres, domena lub skrzynka nie istnieje.	Usuń
`disposable`	Usługa tymczasowych skrzynek.	Usuń
`catch_all`	Domena akceptuje wszystkie adresy, więc nie można potwierdzić skrzynki.	Do sprawdzenia
`role`	Istniejąca wspólna skrzynka.	Do sprawdzenia
`unknown`	Serwer pocztowy nie odpowiedział na czas. Bez opłaty.	Spróbuj później

Partie

Wyślij do 100 000 adresów w jednym żądaniu. Partia przetwarza się w tle. Odpytuj o jej status lub podaj callback_url, a wywołamy go po zakończeniu partii.

Utwórz partię

POST https://bouncebell.com/api/v1/batches

curl -X POST "https://bouncebell.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q3m9x7w4p", "status": "queued", "total": 2, "done": 0 }

Kredyty za każdy unikalny adres są blokowane przy tworzeniu partii, a za nieznane wyniki zwracane po jej zakończeniu. Wywołanie zwrotne otrzymuje żądanie POST z {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}}. Adresy URL wywołań zwrotnych muszą używać HTTPS.

Postęp sprawdzania

GET https://bouncebell.com/api/v1/batches/{id}

{ "id": "bat_8f2k1q3m9x7w4p", "status": "running", "total": 2, "done": 1 }

Status to queued, running lub done. Gdy jest done, odpowiedź zawiera także counts według statusu.

Pobierz wyniki

GET https://bouncebell.com/api/v1/batches/{id}/results

Domyślnie zwraca JSON. Dodaj ?format=csv, aby otrzymać plik CSV. Każdy wiersz ma te same pola co pojedyncze sprawdzenie.

Kredyty

GET https://bouncebell.com/api/v1/credits

{ "credits_remaining": 33420 }

Błędy i limity

Błędy zwracają treść JSON z kodem error i czytelnym komunikatem message.

Kod HTTP	Błąd	Co zrobić
400	`bad_request`	Brakuje parametru lub jest nieprawidłowy. Przeczytaj komunikat.
401	`invalid_key`	Sprawdź, czy klucz jest poprawny i nie został unieważniony.
402	`no_credits`	Dokup kredyty.
403	`email_not_confirmed`	Otwórz link potwierdzający, który wysłaliśmy e-mailem przy rejestracji.
404	`not_found`	Partia nie istnieje lub została usunięta po 30 dniach.
429	`rate_limited`	Zwolnij. Odczekaj liczbę sekund podaną w nagłówku `Retry-After`.
500	`server_error`	Spróbuj ponownie po krótkiej przerwie. Jeśli problem nie ustąpi, skontaktuj się z pomocą.

Pojedyncze sprawdzenia są ograniczone do 20 żądań na sekundę na klucz. Jeśli potrzebujesz więcej, daj nam znać.