Validation API

API Validation pozwala weryfikować adresy email przed wysyłką by zmniejszyć odbicia i chronić reputację nadawcy.

Waliduj pojedynczy email

Waliduj pojedynczy adres email.

POST /v1/validate/single

Body żądania

Pole	Typ	Wymagane	Opis
email	string	Tak	Adres email do walidacji

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/validate/single \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Odpowiedź

{
  "email": "user@example.com",
  "valid": true,
  "result": "deliverable",
  "checks": {
    "syntax": "valid",
    "dns": "valid",
    "mx": "valid",
    "disposable": false,
    "role": false,
    "catch_all": false,
    "smtp": "valid"
  },
  "suggestion": null
}

Typy wyników

Wynik	Opis	Akcja
deliverable	Skrzynka istnieje	Bezpiecznie wysłać
undeliverable	Skrzynka nie istnieje	Nie wysyłać
risky	Może odbić	Wysyłać z ostrożnością
unknown	Nie udało się zweryfikować	Ręczny przegląd

Pola sprawdzeń

Pole	Opis
syntax	Format emaila prawidłowy
dns	Domena ma rekordy DNS
mx	Domena ma rekordy MX
disposable	Tymczasowa usługa email
role	Adres generyczny (info@, admin@)
catch_all	Domena przyjmuje dowolny adres
smtp	Skrzynka istnieje (sprawdzenie SMTP)

---

Walidacja z sugestią literówki

Gdy walidacja wykryje możliwą literówkę:

{
  "email": "user@gmial.com",
  "valid": false,
  "result": "undeliverable",
  "suggestion": "user@gmail.com"
}

---

Walidacja masowa

Waliduj wiele emaili w jednym żądaniu. Wyniki zwracane synchronicznie.

Uwaga: Dla żądań zawierających powyżej 50 adresów email, przetwarzanie odbywa się asynchronicznie. W odpowiedzi otrzymasz job_id, którego możesz użyć do sprawdzenia statusu za pomocą endpointu GET /v1/validate/job/{job_id}.

POST /v1/validate/batch

Body żądania

Pole	Typ	Wymagane	Opis
emails	array	Tak	Lista emaili (max 1 000)

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/validate/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "user1@example.com",
      "user2@example.com",
      "invalid@nieistniejaca.domena"
    ]
  }'

Odpowiedź

{
  "results": [
    {
      "email": "user1@example.com",
      "valid": true,
      "result": "deliverable",
      "checks": {
        "syntax": "valid",
        "dns": "valid",
        "mx": "valid",
        "disposable": false,
        "role": false
      }
    },
    {
      "email": "user2@example.com",
      "valid": true,
      "result": "deliverable",
      "checks": {
        "syntax": "valid",
        "dns": "valid",
        "mx": "valid",
        "disposable": false,
        "role": false
      }
    },
    {
      "email": "invalid@nieistniejaca.domena",
      "valid": false,
      "result": "undeliverable",
      "checks": {
        "syntax": "valid",
        "dns": "invalid",
        "mx": "invalid",
        "disposable": false,
        "role": false
      }
    }
  ],
  "summary": {
    "total": 3,
    "deliverable": 2,
    "undeliverable": 1,
    "risky": 0,
    "unknown": 0
  }
}

---

Szybka walidacja

Szybka walidacja adresu email — sprawdza tylko składnię i DNS, bez weryfikacji SMTP.

POST /v1/validate/quick

Body żądania

Pole	Typ	Wymagane	Opis
email	string	Tak	Adres email do szybkiej walidacji

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/validate/quick \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Odpowiedź

{
  "email": "user@example.com",
  "valid": true,
  "checks": {
    "syntax": "valid",
    "dns": "valid",
    "mx": "valid",
    "disposable": false,
    "role": false
  },
  "suggestion": null
}

---

Status job’a walidacji batch

Sprawdź status asynchronicznego zadania walidacji masowej.

GET /v1/validate/job/{job_id}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/validate/job/job_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź (w trakcie)

{
  "id": "job_abc123",
  "status": "processing",
  "progress": {
    "total": 500,
    "processed": 250
  },
  "created_at": "2024-01-20T15:00:00Z"
}

Odpowiedź (zakończone)

{
  "id": "job_abc123",
  "status": "completed",
  "progress": {
    "total": 500,
    "processed": 500
  },
  "results": {
    "deliverable": 450,
    "undeliverable": 30,
    "risky": 15,
    "unknown": 5
  },
  "created_at": "2024-01-20T15:00:00Z",
  "completed_at": "2024-01-20T15:02:30Z"
}

---

Kody błędów

Kod	Opis
invalid_email_format	Składnia emaila nieprawidłowa
job_not_found	ID zadania nie znalezione
file_too_large	Plik przekracza 100 MB
too_many_emails	Przekroczono limit 1 miliona
invalid_file_format	Niewspierany typ pliku
job_already_completed	Nie można anulować zakończonego zadania