API-referentie e-mailcontrole

Authenticatie

POST /v1/email/validate accepteert een publiceerbare, origin-gebonden sleutel via de header X-Api-Key — hetzelfde sleuteltype en hetzelfde model van toegestane origins als GET /v1/geo. Alle andere endpoints op deze pagina (batch, lijstjobs, registratiecontrole) accepteren veel adressen of een willekeurig IP, vereisen daarom je geheime sleutel via Authorization: Bearer en mogen alleen vanuit je backend worden aangeroepen; een publiceerbare sleutel krijgt daar een 403.

Voorbeeld

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Oordelen en redencodes

Elke voorwaarde legt een minimaal oordeel op; de zwaarste wint, en reasons somt ze allemaal op, de zwaarste eerst. Of een adres bij een gratis aanbieder acceptabel is, bepaal je zelf — het verandert nooit het oordeel.

Batchcontrole

POST/v1/email/batch

Controleert 1–100 adressen in één verzoek met dezelfde controles en dezelfde resultaatvorm als POST /v1/email/validate, één resultaat per adres in de invoervolgorde. Stuur { "emails": [...] }. Adressen op hetzelfde domein delen één DNS-opzoeking. Telt één verzoek per adres mee voor de maandlimiet van je abonnement; een batch die de limiet zou overschrijden, wordt in zijn geheel afgewezen met 429 monthly_limit_exceeded. Voor de rate limit per minuut telt de hele aanroep als één verzoek. Alleen met geheime sleutel.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

E-maillijstjobs

POST/v1/email/jobs

Controleert tot 100.000 adressen op de achtergrond. Stuur JSON { "emails": [...], "filename": "..." } of een text/csv-body van maximaal 10 MB: de kolom met de kop email (ook e-mail, email address, email_address of mail, niet hoofdlettergevoelig) wordt gebruikt, of de eerste kolom als geen kop er een benoemt; komma, puntkomma en tab als scheidingsteken worden herkend. De job wordt bij het aanmaken in rekening gebracht — één verzoek per uniek adres (exacte overeenkomst), dus dubbele adressen worden gecontroleerd maar één keer gerekend — en een lijst die je maandlimiet zou overschrijden, wordt in zijn geheel afgewezen. Als een deel van een job na herhaalde pogingen niet verwerkt kan worden, wordt de job als failed gemarkeerd en worden de credits voor het niet-verwerkte deel teruggegeven. Antwoordt met 202 en het job-object. Alleen met geheime sleutel; dezelfde jobs kun je ook uploaden en downloaden via de dashboardpagina Email lists.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

Jobstatus

GET/v1/email/jobs/{id}

Geeft hetzelfde job-object terug. Vraag het periodiek op tot status completed is; opvragen wordt niet in rekening gebracht.

Jobresultaten

GET/v1/email/jobs/{id}/results

Downloadt een CSV met één rij per ingediende rij, in de volgorde van indienen — inclusief dubbele. Kolommen: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons is gescheiden door puntkomma's, lege cellen betekenen null en mx_status is leeg voor syntactisch ongeldige adressen (er is niets opgezocht). Een ongeldig adres dat begint met =, +, - of @ krijgt een apostrof ervoor, zodat spreadsheetprogramma's het niet als formule uitvoeren. 409 zolang de job niet voltooid is, 410 zodra hij verlopen is. Downloaden wordt niet in rekening gebracht.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Registratiecontrole

POST/v1/signup/check

Beoordeelt een registratie op basis van e-mailadres en IP in één aanroep, vanuit je backend wanneer het registratieformulier wordt verzonden (een in de browser berekend oordeel kan worden vervalst). Stuur { "email": "...", "ip": "...", "userAgent": "..." } — userAgent is optioneel. Het antwoord bevat het volledige resultaat van de e-mailcontrole (email), het land en ASN van het IP en — bij abonnementen met beveiligingsgegevens — de VPN-/Tor-/datacenter-/dreigingsindicatoren (ip), de leeftijd van het e-maildomein in dagen volgens openbare registratiegegevens (RDAP) (emailDomainAgeDays, null als onbekend en voor bekende consumentenaanbieders), een score van 0–100 (de som van de gewichten van de redenen hieronder, met een maximum van 100) en een oordeel: reject vanaf 60, review vanaf 25, anders accept. Bij een abonnement zonder beveiligingsgegevens is ip.security null, gebruikt de score alleen de e-mailsignalen en bevat reasons ip_security_unavailable. Telt als één verzoek. Alleen met geheime sleutel.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Limieten

Elk gecontroleerd adres telt als één verzoek voor de gedeelde maandlimiet van je abonnement — een enkele controle, elk adres in een batch, elk uniek adres in een lijstjob — en een registratiecontrole is één verzoek. Batches en lijstjobs worden in hun geheel geaccepteerd of afgewezen, nooit gedeeltelijk uitgevoerd. De rate limit per minuut telt HTTP-aanroepen, geen items: een batch van maximaal 100 IP's of e-mailadressen telt als één verzoek, terwijl elk item nog steeds apart meetelt voor de maandelijkse verzoeklimiet. Uploads en resultaten van lijstjobs worden 7 dagen na het aanmaken van de job verwijderd. DNS-opzoekingen hebben een kort tijdsbudget: als er een mislukt of verloopt, valt het resultaat terug op mx.status unknown en reden dns_unavailable in plaats van een fout. Gegevens over wegwerpdomeinen worden samengevoegd uit drie door de community onderhouden open-sourcelijsten, om de paar uur ververst en aangevuld met mailservers waarvan is waargenomen dat ze vermelde domeinen bedienen — zie gegevensbronnen. Een heel nieuwe wegwerpaanbieder wordt mogelijk nog niet gemarkeerd. Alle controles gebeuren op domein- en adresniveau: er wordt geen mailbox benaderd, dus geen enkel resultaat stelt vast dat een mailbox bestaat, van wie die is of dat e-mail er aankomt.