MailAudit
Dokumentazzjoni tal-API

Referenza tal-API

Integra MailAudit fl-applikazzjoni tiegħek: verifiki DNS, tal-blacklist u tar-reputazzjoni, u testijiet sħaħ tal-konsenja tal-email permezz ta’ REST API.

Rate limit

60 talba / minuta, 1,000 / jum għal kull ċavetta

Base URL

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

Awtentikazzjoni

Kull talba teħtieġ ċavetta API. Ibgħatha fil-header Authorization bħala Bearer token (jew fil-header X-API-Key). Żomm iċ-ċavetta tiegħek sigrieta — iddaħħalhiex f’kodiċi tal-browser.

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

Kull risposta tinkludi l-headers X-RateLimit-Remaining u X-RateLimit-Daily-Remaining. Meta jinqabeż limitu, tirċievi HTTP 429 b’header Retry-After.

Ikseb ċavetta API

Endpoints

Verifika tar-rekord MX

GET/tools/mx-check

Fittex ir-rekords MX tad-dominju, kif ukoll is-settings SPF u DMARC.

Parametri

domainstringmeħtieġ
Id-dominju li trid tivverifika (eż. example.com)

Talba ta’ eżempju

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

Eżempju ta’ risposta

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}

Verifika blacklist

GET/tools/blacklist-check

Iċċekkja jekk indirizz IP jew dominju jinsabx fuq blocklists ewlenin tal-ispam (32 DNSBL).

Parametri

querystringmeħtieġ
Indirizz IP (eż. 192.168.1.1) jew isem dominju

Talba ta’ eżempju

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

Eżempju ta’ risposta

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}

Verifika tar-reputazzjoni tad-dominju

GET/tools/reputation

Kalkolu komprensiv tal-punteġġ tar-reputazzjoni tad-dominju. Iċċekkja SPF, DKIM, DMARC, rekords MX, status tal-blacklist, appoġġ STARTTLS, età tad-dominju u reverse DNS.

Parametri

domainstringmeħtieġ
Id-dominju li trid tivverifika (eż. gmail.com)

Talba ta’ eżempju

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

Eżempju ta’ risposta

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 tal-konsenja tal-email

Oħloq indirizz tal-prova, ibgħatlu l-email tiegħek mis-server li trid tittestja, imbagħad staqsi għar-riżultat sakemm l-istatus ikun completed (normalment fi żmien minuta). L-indirizzi tal-prova jiskadu wara siegħa.

POST/test/generate

Oħloq indirizz tal-email tal-prova ġdid.

Talba ta’ eżempju

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

Eżempju ta’ risposta

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}

Ikseb l-istatus u r-riżultati ta’ test. Status: pending → processing → completed (jew expired / error). Il-punteġġ huwa 0–10.

Parametri

testIdstringmeħtieġ
L-ID tat-test mogħti minn /test/generate

Talba ta’ eżempju

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

Eżempju ta’ risposta

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

Erġa’ ħaddem il-verifiki kollha fuq email li diġà waslet, mingħajr ma tibgħat oħra.

Parametri

testIdstringmeħtieġ
L-ID tat-test mogħti minn /test/generate

Eżempju ta’ risposta

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

Inbox tal-iżviluppatur

Kull kont għandu l-indirizz temporanju tiegħu ([email protected], bi kwalunkwe +tag). Il-posta mibgħuta lilu tinżamm għal 24 siegħa u tista’ tinqara permezz tal-API, fid-dashboard jew permezz ta’ link għall-qsim. Użah fit-testijiet end-to-end minflok mailbox reali.

GET/inbox/wait

Jistenna (long-poll, sa 60 s) sakemm jasal messaġġ li jaqbel u jirritornah bit-test, l-HTML, il-links u l-kodiċijiet ta’ użu wieħed. Jirritorna 408 jekk ma jasal xejn fil-ħin.

Parametri

tagstring
Biss posta mibgħuta lil dev-xxxxxx+{tag}@…
timeoutnumber
Sekondi ta’ stennija, 1-60 (default 30)
sinceISO 8601
Biss posta li waslet wara dan il-ħin (default: issa)

Talba ta’ eżempju

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"

Disponibbli wkoll:

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

Eżempju ta’ risposta

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}

Użah minn aġent tal-AI (MCP)

L-istess inbox huwa server MCP, għalhekk Claude Code, Cursor u klijenti MCP oħra jistgħu joħolqu indirizzi, jistennew il-posta u jaqrawha waħedhom:

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

Għodod: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

Kodiċijiet tal-Istatus HTTP

KodiċiStatusDeskrizzjoni
200OKTalba rnexxiet
400Bad RequestParametru nieqes jew invalidu
401UnauthorizedĊavetta API nieqsa, invalida jew revokata
404Not FoundIt-test ma nstabx
429Too Many RequestsInqabeż il-limitu tar-rata (60/minuta jew 1,000/jum)
500Internal Server ErrorŻball min-naħa tas-server

Risposti ta’ Żball

F’każ ta’ żball, ir-risposta tinkludi qasam error b’deskrizzjoni tal-problema:

json
{
  "error": "Domain hu meħtieġ"
}

Eżempji ta’ Kodiċi

JavaScript / Node.js

javascript
1// Query tar-rekords MX
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('Rekords MX:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Xejn');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Xejn');
12}

Python

python
1import os
2import requests
3
4# Verifika blacklist
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"Iċċekkjati: {data['totalChecked']} listi")
13print(f"Elenkat fuq: {data['totalListed']} postijiet")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: ELENKAT")

Python - Reputation Check

python
1import os
2import requests
3
4# Verifika tar-reputazzjoni tad-dominju
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("\nFatturi:")
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# Test sħiħ tal-konsenja
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// Verifika MX
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']} (prijorità: {$mx['priority']})\n";
15    }
16}
17?>

Tixtieq tipprova l-API?

Ipprova l-għodod tagħna mill-interface tal-web, jew ibda tiżviluppa bl-API.