MailAudit
API dokumentatsioon

API viide

Liida MailAudit oma rakendusega: DNS-, blokinimekirja- ja reputatsioonikontrollid ning täielikud e-kirjade kohaletoimetatavuse testid REST API kaudu.

Päringute limiit

60 päringut minutis, 1000 päevas võtme kohta

Baas-URL

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

Autentimine

Iga päring vajab API-võtit. Saada see päises Authorization Bearer-tokenina (või päises X-API-Key). Hoia võti salajas – ära lisa seda brauseris töötavasse koodi.

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

Iga vastus sisaldab päiseid X-RateLimit-Remaining ja X-RateLimit-Daily-Remaining. Limiidi ületamisel saad vastuseks HTTP 429 koos päisega Retry-After.

Hangi API-võti

Lõpp-punktid

MX-kirjete kontroll

GET/tools/mx-check

Pärib domeeni MX-kirjed ning SPF- ja DMARC-seaded.

Parameetrid

domainstringkohustuslik
Kontrollitav domeeninimi (nt example.com)

Päringu näide

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

Vastuse näide

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}

Blokinimekirjade kontroll

GET/tools/blacklist-check

Kontrolli, kas IP-aadress või domeen on suuremates rämpsposti blokinimekirjades (32 DNSBL-i).

Parameetrid

querystringkohustuslik
IP-aadress (nt 192.168.1.1) või domeeninimi

Päringu näide

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

Vastuse näide

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}

Domeeni reputatsiooni kontroll

GET/tools/reputation

Põhjalik domeeni reputatsiooni skoori arvutus. Kontrollib SPF-, DKIM-, DMARC-kirjeid, MX-kirjeid, blokinimekirju, STARTTLS-i tuge, domeeni vanust ja pöörd-DNS-i.

Parameetrid

domainstringkohustuslik
Kontrollitav domeeninimi (nt gmail.com)

Päringu näide

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

Vastuse näide

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}

E-kirja kohaletoimetatavuse test

Loo testaadress, saada sinna e-kiri serverist, mida soovid testida, ja päri tulemust seni, kuni olek on completed (tavaliselt minuti jooksul). Testaadressid aeguvad ühe tunni pärast.

POST/test/generate

Loo uus test-e-posti aadress.

Päringu näide

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

Vastuse näide

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}

Hangi testi olek ja tulemused. Olek: pending → processing → completed (või expired / error). Skoor on 0–10.

Parameetrid

testIdstringkohustuslik
Testi ID, mille tagastas /test/generate

Päringu näide

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

Vastuse näide

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

Käivita kõik kontrollid juba saabunud e-kirjal uuesti, ilma uut saatmata.

Parameetrid

testIdstringkohustuslik
Testi ID, mille tagastas /test/generate

Vastuse näide

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

Arenduspostkast

Igal kontol on oma ühekordne aadress ([email protected], mis tahes +sildiga). Sinna saadetud kirju hoitakse 24 tundi ja neid saab lugeda API kaudu, töölaual või jagamislingi abil. Kasuta seda otsast lõpuni testides päris postkasti asemel.

GET/inbox/wait

Ootab (long-poll, kuni 60 s), kuni saabub sobiv kiri, ja tagastab selle koos teksti, HTML-i, linkide ja ühekordsete koodidega. Tagastab 408, kui õigeks ajaks midagi ei saabu.

Parameetrid

tagstring
Ainult aadressile dev-xxxxxx+{tag}@… saadetud kirjad
timeoutnumber
Ooteaeg sekundites, 1–60 (vaikimisi 30)
sinceISO 8601
Ainult pärast seda aega saabunud kirjad (vaikimisi: praegu)

Päringu näide

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"

Saadaval on ka:

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

Vastuse näide

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}

Kasuta seda tehisintellekti agendist (MCP)

Sama postkast on ka MCP-server, nii et Claude Code, Cursor ja teised MCP-kliendid saavad ise aadresse luua, kirju oodata ja neid lugeda:

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

Tööriistad: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

HTTP olekukoodid

KoodStaatusKirjeldus
200OKPäring õnnestus
400Bad RequestPuuduv või vigane parameeter
401UnauthorizedAPI-võti puudub, on vigane või tühistatud
404Not FoundTesti ei leitud
429Too Many RequestsPäringute limiit ületatud (60 minutis või 1000 päevas)
500Internal Server ErrorServeri sisemine viga

Veavastused

Veateate korral sisaldab vastus välja error koos veakirjeldusega:

json
{
  "error": "Domeen on kohustuslik"
}

Koodinäited

JavaScript / Node.js

javascript
1// Pärib MX-kirjed
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-kirjed:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Puuduvad');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Puuduvad');
12}

Python

python
1import os
2import requests
3
4# Blokinimekirja kontroll
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"Kontrollitud: {data['totalChecked']} nimekirja")
13print(f"Kirjas: {data['totalListed']} nimekirjas")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: KIRJAS")

Python - Reputation Check

python
1import os
2import requests
3
4# Domeeni reputatsiooni kontroll
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("\nTegurid:")
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# Täielik kohaletoimetatavuse test
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-kontroll
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']} (prioriteet: {$mx['priority']})\n";
15    }
16}
17?>

Soovid API-d proovida?

Proovi meie tööriistu veebiliidese kaudu või alusta arendamist API abil.