DLA PROGRAMISTÓW

API weryfikacji adresów e-mail.

Sprawdzaj pojedyncze adresy w formularzach lub używaj zadań asynchronicznych dla list klientów. Zachowaj obecnego dostawcę poczty.

ZACZNIJ OD JEDNEGO ADRESU

Twoje pierwsze żądanie.

Użyj bezpłatnego endpointu demonstracyjnego bez klucza. Ma limit żądań i służy do wypróbowania usługi.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Aby korzystać z płatnej weryfikacji, kup pakiet i użyj /v1/fast-verify z kluczem w X-API-Key. Nie umieszczaj kluczy w adresach URL, repozytoriach kodu ani narzędziach analitycznych.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Przykład w Pythonie

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Przykład w Node.js

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

PRZEŚLIJ LISTĘ, ODBIERZ WYNIKI

Sprawdź większą listę.

POST /v1/tasks

Prześlij do 10 000 adresów w jednym zadaniu. Zachowaj zwrócony identyfikator zadania i sprawdź accepted, skipped i invalids: nie każdy adres wejściowy musi trafić do kolejki. Duplikaty, adresy o błędnym formacie i adresy z listy wykluczeń mogą zostać usunięte, a niskie saldo może spowodować częściowe przyjęcie listy.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Odpytuj o status, a następnie pobierz każdą stronę wyników. Odpowiedź zawierająca wyłącznie nieprawidłowe dane wejściowe może mieć pusty identyfikator zadania; nie odpytuj o takie zadanie.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Wyniki ukończonych zadań są w formacie JSON. Pobieraj kolejne strony, aż odbierzesz całą przyjętą listę. Aby automatycznie otrzymać informację o zakończeniu, przekaż webhook za pomocą mode: "completed" podczas tworzenia zadania.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Przed włączeniem webhooka w środowisku produkcyjnym sprawdź w schemacie zasady konfiguracji i weryfikacji podpisu.

ZROZUM ODPOWIEDŹ

Poprawny format nie oznacza istnienia skrzynki.

To odrębne sygnały. Adres o poprawnym formacie może nie istnieć, być tymczasowy lub niemożliwy do potwierdzenia.

Pole	Znaczenie
`valid`	Adres przeszedł walidację składni. Samo to nie potwierdza istnienia skrzynki.
`exists`	Wynik sprawdzenia skrzynki. Interpretuj go łącznie z błędami i sygnałami catch-all.
`disposable`	Domena została rozpoznana jako dostawca tymczasowych adresów e-mail.
`accept_all`	Serwer akceptuje dowolne adresy; nie można wiarygodnie potwierdzić konkretnej skrzynki.
`error_category`	Wyjaśnia błąd lub ryzyko, np. no_mx, risky albo przejściowy problem z serwerem.
`permanent_error`	Podczas sprawdzania zwrócono trwały błąd. Błędu przejściowego nie należy traktować jako trwałego odrzucenia.
`ttl`	Wskazówka dotycząca ponowienia lub pamięci podręcznej, wyrażona w sekundach, jeśli jest zwracana.

Weryfikacja nie gwarantuje dostarczenia, nie eliminuje skarg ani nie potwierdza własności skrzynki.

Sprawdź swoje saldo.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Odpowiedź zawiera pozostałe, zarezerwowane i wykorzystane kredyty, typ klucza oraz datę wygaśnięcia. Standardowa weryfikacja zużywa jeden kredyt; rzeczywiste filtrowanie i naliczanie opłat zależą od endpointu i przyjęcia zadania. Sprawdź odpowiedź, zanim uznasz całą przesłaną listę za przetworzoną.

Odpowiedź 429 oznacza ograniczenie liczby żądań. Odczekaj przed ponowieniem. Inne błędy w obecnym API mogą być zwracane jako JSON lub tekst; nie interpretuj błędów HTTP jako wyników weryfikacji.

Specyfikacja weryfikacji.

Pobierz OpenAPI JSON

Publiczna specyfikacja obejmuje demo, szybką weryfikację, zadania, ich status, wyniki i saldo. Endpointy wysyłki i administracji nie należą do tego opisu weryfikacji.

Potrzebujesz pomocy z podłączeniem platformy? support@zbounce.net