MailAudit
API-documentatie

API-referentie

Integreer MailAudit in je eigen applicatie: DNS-, blacklist- en reputatiecontroles en volledige tests van e-mailaflevering via een REST API.

Rate limit

60 verzoeken / minuut, 1.000 / dag per sleutel

Basis-URL

https://api.mailaudit.io/api/v1

Authenticatie

Elk verzoek heeft een API-sleutel nodig. Stuur deze in de Authorization-header als Bearer-token (of in de X-API-Key-header). Houd je sleutel geheim – neem hem niet op in browsercode.

bash
curl -H "Authorization: Bearer ma_live_xxxxxxxxxxxx" \
  "https://api.mailaudit.io/api/v1/tools/mx-check?domain=example.com"

Elk antwoord bevat de headers X-RateLimit-Remaining en X-RateLimit-Daily-Remaining. Als een limiet wordt overschreden, krijg je HTTP 429 met een Retry-After-header.

API-sleutel aanvragen

Endpoints

MX-recordcontrole

GET/tools/mx-check

Vraag de MX-records van een domein op, plus SPF- en DMARC-instellingen.

Parameters

domainstringvereist
De te controleren domeinnaam (bijv. example.com)

Voorbeeldverzoek

bash
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
  "https://api.mailaudit.io/api/v1/tools/mx-check?domain=gmail.com"

Voorbeeldrespons

json
1{
2  "domain": "gmail.com",
3  "hasMx": true,
4  "records": [
5    {
6      "exchange": "gmail-smtp-in.l.google.com",
7      "priority": 5,
8      "ip": ["142.250.150.27"]
9    },
10    {
11      "exchange": "alt1.gmail-smtp-in.l.google.com",
12      "priority": 10,
13      "ip": ["142.250.141.26"]
14    }
15  ],
16  "hasSpf": true,
17  "spfRecord": "v=spf1 redirect=_spf.google.com",
18  "hasDmarc": true,
19  "dmarcRecord": "v=DMARC1; p=none; sp=quarantine; rua=mailto:..."
20}

Blacklistcontrole

GET/tools/blacklist-check

Controleer of een IP-adres of domein op belangrijke spamblocklists (32 DNSBL's) staat.

Parameters

querystringvereist
IP-adres (bijv. 192.168.1.1) of domeinnaam

Voorbeeldverzoek

bash
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
  "https://api.mailaudit.io/api/v1/tools/blacklist-check?query=8.8.8.8"

Voorbeeldrespons

json
1{
2  "query": "8.8.8.8",
3  "queryType": "ip",
4  "totalChecked": 32,
5  "totalListed": 0,
6  "results": [
7    {
8      "name": "Spamhaus ZEN",
9      "zone": "zen.spamhaus.org",
10      "listed": false,
11      "responseTime": 45
12    },
13    {
14      "name": "Barracuda",
15      "zone": "b.barracudacentral.org",
16      "listed": false,
17      "responseTime": 32
18    }
19    // ...
20  ]
21}

Domeinreputatiecontrole

GET/tools/reputation

Berekening van een uitgebreide domeinreputatiescore. Controleert SPF, DKIM, DMARC, MX-records, blackliststatus, STARTTLS-ondersteuning, domeinleeftijd en reverse DNS.

Parameters

domainstringvereist
De te controleren domeinnaam (bijv. gmail.com)

Voorbeeldverzoek

bash
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
  "https://api.mailaudit.io/api/v1/tools/reputation?domain=gmail.com"
Beoordelingsschaal
90-100 = A+
80-89 = A
70-79 = B
60-69 = C
50-59 = D
0-49 = F

Voorbeeldrespons

json
1{
2  "domain": "gmail.com",
3  "ip": "142.250.150.27",
4  "score": 100,
5  "grade": "A+",
6  "factors": [
7    { "name": "SPF", "status": "pass", "detail": "Policy: present", "impact": 15 },
8    { "name": "DKIM", "status": "warn", "detail": "Not found", "impact": 0 },
9    { "name": "DMARC", "status": "warn", "detail": "Policy: none", "impact": 5 },
10    { "name": "MX Records", "status": "pass", "detail": "5 record(s)", "impact": 10 },
11    { "name": "Blacklists", "status": "pass", "detail": "Clean (39 checked)", "impact": 20 },
12    { "name": "STARTTLS", "status": "pass", "detail": "Supported", "impact": 10 },
13    { "name": "Domain Age", "status": "pass", "detail": "30.3 years", "impact": 10 },
14    { "name": "Reverse DNS", "status": "pass", "detail": "wa-in-f27.1e100.net", "impact": 5 }
15  ],
16  "details": {
17    "mx": { "valid": true, "count": 5, "primary": "gmail-smtp-in.l.google.com" },
18    "spf": { "valid": true, "record": "v=spf1 redirect=_spf.google.com" },
19    "dkim": { "valid": false, "selectors": [] },
20    "dmarc": { "valid": true, "policy": "none", "rua": ["mailto:..."] },
21    "blacklists": { "checked": 10, "listed": 0, "clean": true },
22    "tls": { "valid": true, "starttls": true },
23    "domainAge": { "valid": true, "years": 30.3, "registrationDate": "1995-08-13" },
24    "rdns": { "valid": true, "hostname": "wa-in-f27.1e100.net" }
25  },
26  "checkedAt": "2025-12-03T07:05:46.232Z",
27  "cached": false
28}

Test van e-mailaflevering

Maak een testadres aan, stuur je e-mail ernaartoe vanaf de server die je wilt testen, en vraag het resultaat op totdat de status completed is (meestal binnen een minuut). Testadressen verlopen na een uur.

POST/test/generate

Maak een nieuw test-e-mailadres aan.

Voorbeeldverzoek

bash
curl -X POST -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
  "https://api.mailaudit.io/api/v1/test/generate"

Voorbeeldrespons

json
1{
2  "testId": "k3v9x2m1qa",
3  "email": "[email protected]",
4  "expiresAt": "2026-09-24T18:44:14.762Z",
5  "checkUrl": "/test/k3v9x2m1qa"
6}
GET/test/{testId}

Haal de status en resultaten van een test op. Status: pending → processing → completed (of expired / error). De score loopt van 0 tot 10.

Parameters

testIdstringvereist
Test-ID die door /test/generate is teruggegeven

Voorbeeldverzoek

bash
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
  "https://api.mailaudit.io/api/v1/test/k3v9x2m1qa"

Voorbeeldrespons

json
1{
2  "testId": "k3v9x2m1qa",
3  "status": "completed",
4  "score": 9.2,
5  "createdAt": "2026-09-24T17:44:14.763Z",
6  "receivedAt": "2026-09-24T17:45:02.118Z",
7  "expiresAt": "2026-09-24T18:44:14.762Z",
8  "email": {
9    "from": "[email protected]",
10    "subject": "Our September newsletter",
11    "bounceAddress": null
12  },
13  "checks": {
14    "spf": { "status": "pass", ... },
15    "dkim": { "status": "pass", ... },
16    "dmarc": { "status": "pass", ... },
17    "blacklist": { "status": "pass", ... },
18    "spamassassin": { "status": "pass", ... }
19  }
20}
POST/test/{testId}/recheck

Voer alle controles opnieuw uit op een e-mail die al is ontvangen, zonder een nieuwe te sturen.

Parameters

testIdstringvereist
Test-ID die door /test/generate is teruggegeven

Voorbeeldrespons

json
1{
2  "success": true,
3  "testId": "k3v9x2m1qa",
4  "message": "Recheck initiated - checks are running"
5}

Ontwikkelaarsinbox

Elk account heeft een eigen wegwerpadres ([email protected], met een willekeurige +tag). E-mail die ernaartoe wordt gestuurd, wordt 24 uur bewaard en kan via de API, op het dashboard of via een deellink worden gelezen. Gebruik het in end-to-end-tests in plaats van een echte mailbox.

GET/inbox/wait

Wacht (long-poll, tot 60 s) tot er een passend bericht binnenkomt en geeft het terug met tekst, HTML, links en eenmalige codes. Geeft 408 terug als er op tijd niets binnenkomt.

Parameters

tagstring
Alleen e-mail die naar dev-xxxxxx+{tag}@… is gestuurd
timeoutnumber
Aantal seconden wachten, 1-60 (standaard 30)
sinceISO 8601
Alleen e-mail die na dit tijdstip is ontvangen (standaard: nu)

Voorbeeldverzoek

bash
1curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
2  "https://api.mailaudit.io/api/v1/inbox/address?tag=signup-42"
3# → { "address": "[email protected]", … }
4
5curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
6  "https://api.mailaudit.io/api/v1/inbox/wait?tag=signup-42&timeout=60"

Ook beschikbaar:

  • GET /inbox · GET /inbox/address · GET /inbox/messages?tag=&since=
  • GET /inbox/messages/{id} · GET /inbox/messages/{id}/raw · DELETE /inbox/messages/{id}

Voorbeeldrespons

json
1{
2  "id": "81ab56fe-9546-41a1-b7d1-b0f1a594ad37",
3  "to": "[email protected]",
4  "tag": "signup-42",
5  "from": { "address": "[email protected]", "name": "YourApp" },
6  "subject": "Confirm your email address",
7  "receivedAt": "2026-09-24T19:53:43.624Z",
8  "expiresAt": "2026-09-25T19:53:43.624Z",
9  "links": ["https://yourapp.dev/confirm?t=abc"],
10  "codes": ["482913"],
11  "shareUrl": "https://mailaudit.io/m/UjKgBYNGYXjTaGLe…",
12  "text": "Your code: 482 913 …",
13  "html": "<p>Your code: <b>482 913</b></p>…",
14  "headers": { "subject": "Confirm your email address", … }
15}

Gebruik vanuit een AI-agent (MCP)

Dezelfde inbox is ook een MCP-server, zodat Claude Code, Cursor en andere MCP-clients zelfstandig adressen kunnen aanmaken, op e-mail kunnen wachten en die kunnen lezen:

bash
claude mcp add --transport http mailaudit https://api.mailaudit.io/mcp \
  --header "Authorization: Bearer $MAILAUDIT_API_KEY"

Tools: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

HTTP-statuscodes

CodeStatusBeschrijving
200OKVerzoek geslaagd
400Bad RequestOntbrekende of ongeldige parameter
401UnauthorizedOntbrekende, ongeldige of ingetrokken API-sleutel
404Not FoundTest niet gevonden
429Too Many RequestsRate limit overschreden (60/minuut of 1.000/dag)
500Internal Server ErrorServerfout

Foutresponses

Bij een fout bevat de response een error-veld met de foutbeschrijving:

json
{
  "error": "Domain is required"
}

Codevoorbeelden

JavaScript / Node.js

javascript
1// MX-records opvragen
2const response = await fetch(
3  'https://api.mailaudit.io/api/v1/tools/mx-check?domain=example.com',
4  { headers: { Authorization: `Bearer ${process.env.MAILAUDIT_API_KEY}` } }
5);
6const data = await response.json();
7
8if (data.hasMx) {
9  console.log('MX-records:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Geen');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Geen');
12}

Python

python
1import os
2import requests
3
4# Blacklistcontrole
5response = requests.get(
6    'https://api.mailaudit.io/api/v1/tools/blacklist-check',
7    params={'query': '192.168.1.1'},
8    headers={'Authorization': f"Bearer {os.environ['MAILAUDIT_API_KEY']}"},
9)
10data = response.json()
11
12print(f"Gecontroleerd: {data['totalChecked']} lijsten")
13print(f"Vermeld op: {data['totalListed']} plaatsen")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: VERMELD")

Python - Reputation Check

python
1import os
2import requests
3
4# Domeinreputatiecontrole
5response = requests.get(
6    'https://api.mailaudit.io/api/v1/tools/reputation',
7    params={'domain': 'example.com'},
8    headers={'Authorization': f"Bearer {os.environ['MAILAUDIT_API_KEY']}"},
9)
10data = response.json()
11
12print(f"Score: {data['score']}/100 ({data['grade']})")
13print("\nFactoren:")
14for factor in data['factors']:
15    icon = "✅" if factor['status'] == 'pass' else "⚠️" if factor['status'] == 'warn' else "❌"
16    print(f"  {icon} {factor['name']}: {factor['detail']} ({factor['impact']:+d})")

Python - Email deliverability test

python
1import os
2import time
3import requests
4
5# Volledige afleverbaarheidstest
6api = 'https://api.mailaudit.io/api/v1'
7headers = {'Authorization': f"Bearer {os.environ['MAILAUDIT_API_KEY']}"}
8
9test = requests.post(f'{api}/test/generate', headers=headers).json()
10print('Send your email to:', test['email'])
11
12while True:
13    result = requests.get(f"{api}/test/{test['testId']}", headers=headers).json()
14    if result['status'] in ('completed', 'expired', 'error'):
15        break
16    time.sleep(10)
17
18print(f"Status: {result['status']}, score: {result['score']}/10")

PHP

php
1<?php
2// MX-check
3$domain = 'example.com';
4$url = "https://api.mailaudit.io/api/v1/tools/mx-check?domain=" . urlencode($domain);
5
6$context = stream_context_create(['http' => [
7    'header' => 'Authorization: Bearer ' . getenv('MAILAUDIT_API_KEY'),
8]]);
9$response = file_get_contents($url, false, $context);
10$data = json_decode($response, true);
11
12if ($data['hasMx']) {
13    foreach ($data['records'] as $mx) {
14        echo "MX: {$mx['exchange']} (prioriteit: {$mx['priority']})\n";
15    }
16}
17?>

Wil je de API uitproberen?

Probeer onze tools in de webinterface of ga direct aan de slag met de API.