Proper Check
Developer Hub · REST API v1

API weryfikacji adresów e-mail

Weryfikuj listy mailingowe programowo — mniej bounce’ów, lepsza dostarczalność

Połącz formularze, CRM i landing page z silnikiem EmailVerifier. Sprawdzaj adresy e-mail przez REST API w czasie rzeczywistym lub w jobach bulk — z przejrzystym modelem 1 żądanie = 1 kredyt.

  • Weryfikacja real-time
  • Bulk do 50 000 adresów
  • 1 request = 1 kredyt
Wygeneruj klucz APIZałóż kontoOpenAPI / Redoc

Przykład żądania

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_…" \
  -d '{"email":"user@company.com"}'

Baza wiedzy API

Wybierz temat — od autoryzacji i kredytów po bulk, webhooki i kody błędów.

APIWeryfikacja e-mail API

POST /verify — pojedynczy adres, wynik w sekundę, status valid/invalid/risky.

Czytaj więcej
APIBulk email verification

Masowa weryfikacja list CSV — job, postęp i eksport wyników.

Czytaj więcej
APIKredyty i płatności

Saldo, zużycie API, model 1 kredyt = 1 weryfikacja, HTTP 402.

Czytaj więcej
APIKlucze API i autoryzacja

Bearer ev_live_, panel tokenów, bezpieczne przechowywanie klucza.

Czytaj więcej
APIWebhooki i integracje

verification.completed, podpis HMAC, CRM i marketing automation.

Czytaj więcej
APIReferencja OpenAPI

Pełna specyfikacja YAML, Redoc i kody błędów HTTP.

Czytaj więcej

Czym jest API weryfikacji e-mail?

Interfejs REST do walidacji adresów przed wysyłką kampanii.

Email Verification API pozwala sprawdzić, czy adres e-mail istnieje, czy domena przyjmuje pocztę i czy skrzynka nie jest jednorazowa ani catch-all. Dzięki temu ograniczasz bounce rate, chronisz reputację nadawcy i poprawiasz deliverability.

API działa przez HTTPS pod adresem /api/v1. Autoryzujesz żądania kluczem Bearer (ev_live_…) lub sesją z panelu. Każde udane POST /verify zużywa jeden kredyt — bez abonamentu i bez ukrytych opłat za zapytania GET.

Kiedy używać API weryfikacji email?

Typowe scenariusze integracji w produktach B2B i marketingu.

Formularz rejestracji

Waliduj email w czasie rzeczywistym przy zapisie — odrzuć invalid i disposable przed dodaniem do listy.

CRM i lead gen

Oczyść leady z landing page’y i webhooków — tylko poprawne adresy trafiają do pipeline sprzedaży.

Czyszczenie list mailingowych

Bulk API przed kampanią newsletter — mniej odbić, wyższy open rate i niższe koszty ESP.

SaaS i platformy

Osadź weryfikację email w swoim produkcie — model kredytowy ułatwia rozliczenia z klientami.

Model kredytów API

Proste rozliczenie: jeden request weryfikacji = jeden kredyt.

  • POST /verify pobiera 1 kredyt za każde udane żądanie (HTTP 200) z kluczem ev_live_, także gdy ten sam adres był wcześniej weryfikowany przez API. Klucze sandbox (ev_test_) zwracają mock bez pobierania kredytów.
  • Operacje GET — saldo, historia, status bulk job, eksport CSV — są bezpłatne.
  • Brak kredytów zwraca HTTP 402 (insufficient_credits). Błąd silnika (503) nie pobiera kredytu — saldo pozostaje bez zmian.

Autoryzacja i klucze API

Bezpieczny dostęp przez nagłówek Authorization.

  1. Zaloguj się do panelu i przejdź do sekcji Tokeny API (/konto/api).
  2. Utwórz klucz produkcyjny (ev_live_) lub testowy sandbox (ev_test_) w panelu — pełny secret widzisz tylko raz.
  3. Wysyłaj klucz w nagłówku: Authorization: Bearer ev_live_… — nigdy w URL ani w frontendzie.
Authorization: Bearer ev_live_YOUR_API_KEY
Content-Type: application/json

Szybki start — email verification API

Dwa wywołania: saldo i pierwsza weryfikacja.

1. Sprawdź saldo kredytów

curl https://propercheck.pl/api/v1/credits \
  -H "Authorization: Bearer ev_live_YOUR_KEY"

2. Zweryfikuj pojedynczy adres e-mail

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@company.com"}'

Weryfikacja pojedyncza (real-time)

Endpoint POST /api/v1/verify przyjmuje JSON z polem email. Odpowiedź zawiera status, score 0–100, provider (Google, Microsoft, polskie hostingi) i enrichment (MX, catch-all).

POST /api/v1/verify

Struktura odpowiedzi JSON

Pola zwracane po udanej weryfikacji.

{
  "verificationId": "ver_abc123",
  "email": "john@company.com",
  "status": "valid",
  "score": 92,
  "provider": "google",
  "enrichment": { "mxRecords": ["aspmx.l.google.com"], "catchAll": false },
  "creditsRemaining": 149
}

Statusy weryfikacji e-mail

Klasyfikacja używana w API, panelu i eksporcie CSV.

valid

valid — adres istnieje i może przyjmować pocztę; bezpieczny do wysyłki.

invalid

invalid — adres nie istnieje lub domena nie obsługuje poczty; usuń z listy.

risky

risky — niska pewność (np. disposable, role account); ostrożnie w kampanii.

catch_all

catch_all — serwer akceptuje wszystkie adresy w domenie; wyższe ryzyko bounce.

unknown

unknown — serwer nie odpowiedział jednoznacznie; rozważ ponowną weryfikację.

Referencja endpointów REST

Pełna lista ścieżek API v1 z kosztem kredytów.

MetodaŚcieżkaKredytyOpis
POST/verify1Weryfikacja pojedyncza w czasie rzeczywistym
GET/verify/:id0Pobranie wyniku po verificationId
GET/verifications0Historia weryfikacji i statystyki 30 dni
GET/credits0Aktualne saldo kredytów konta
POST/bulkNUtworzenie joba masowego (N kredytów)
GET/bulk/:id0Status i postęp joba bulk
GET/bulk/:id/export0Pobranie wyników jako CSV
GET/POST/PATCH/DELETE/api-keys0Zarządzanie tokenami API (sesja)
GET/POST/DELETE/webhooks0Konfiguracja webhooków (sesja)
GET/usage0Statystyki zużycia API i kredytów

Bulk email verification API

Weryfikacja tysięcy adresów w jednym jobie — idealne przed kampanią.

  1. POST /bulk z tablicą emails lub tekstem CSV — kredyty rezerwowane za N unikalnych adresów.
  2. GET /bulk/:id — polling statusu (queued → processing → completed).
  3. GET /bulk/:id/export — pobierz CSV z kolumnami email, status, score, provider.
curl -X POST https://propercheck.pl/api/v1/bulk \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@b.co","c@d.co"]}'

Webhooki — verification.completed

Po zakończeniu weryfikacji możesz otrzymać POST na swój URL. Nagłówek X-EV-Signature zawiera HMAC-SHA256 body — zweryfikuj podpis przed przetwarzaniem.

X-EV-Event: verification.completed
X-EV-Signature: <hmac-sha256 of body>

Limity żądań (rate limiting)

Domyślnie 60 żądań na minutę na klucz API. Przekroczenie zwraca HTTP 429 z kodem rate_limit_exceeded. Limity są per klucz — rozdziel integracje na osobne tokeny.

Opcjonalny nagłówek na POST /verify — bezpieczne retry bez podwójnego debitu kredytu przy tym samym kluczu (TTL 24h).

X-Request-Id

Każda odpowiedź API zawiera nagłówek X-Request-Id — podaj go w zgłoszeniu do supportu przy debugowaniu integracji.

Kody błędów HTTP

HTTPKodOpis
401unauthorizedBrak sesji lub klucza API w żądaniu.
401invalid_api_keyKlucz nieprawidłowy, wygasły lub unieważniony w panelu.
400invalid_requestNieprawidłowy JSON, brak pola email lub format adresu.
402insufficient_creditsZa mało kredytów — doładuj saldo w panelu /konto/kredyty.
429rate_limit_exceededPrzekroczony limit 60 żądań/min na klucz API.
503engine_unavailableSilnik weryfikacji niedostępny — kredyt nie jest pobierany.

Przykłady integracji

Ten sam flow weryfikacji w popularnych językach.

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@company.com"}'

FAQ — API weryfikacji e-mail

Najczęstsze pytania developerów i marketerów.

OpenAPI 3.1 i Redoc

Maszynowo czytelna specyfikacja do codegen, testów kontraktowych i CI.

Pobierz openapi-v1.yamlInteraktywna referencja Redoc

Zacznij weryfikować emaile przez API

Darmowe kredyty testowe po rejestracji. Klucz API w panelu w minutę.

Załóż kontoTokeny API

Wygeneruj klucz w panelu konta.