Documentație API

Referință API

Integrează MailAudit în propria aplicație: verificări DNS, blacklist și de reputație, precum și teste complete de livrabilitate a emailurilor, printr-un API REST.

Limită de request-uri

60 de cereri / minut, 1.000 / zi per cheie

URL de bază

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

Autentificare

Fiecare cerere necesită o cheie API. Trimite-o în headerul Authorization ca token Bearer (sau în headerul X-API-Key). Păstrează cheia secretă — nu o include în cod care rulează în browser.

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

Fiecare răspuns include headerele X-RateLimit-Remaining și X-RateLimit-Daily-Remaining. Când o limită este depășită, primești HTTP 429 cu un header Retry-After.

Obține o cheie API

Endpoint-uri

Verificare înregistrări MX

GET/tools/mx-check

Interoghează înregistrările MX ale unui domeniu, precum și setările SPF și DMARC.

Parametri

domainstringobligatoriu
Numele domeniului de verificat (ex. example.com)

Exemplu de request

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

Exemplu de răspuns

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}

Verificare blacklist

GET/tools/blacklist-check

Verifică dacă o adresă IP sau un domeniu este în principalele liste de blocare pentru spam (32 de DNSBL-uri).

Parametri

querystringobligatoriu
Adresă IP (ex. 192.168.1.1) sau nume de domeniu

Exemplu de request

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

Exemplu de răspuns

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}

Verificare reputație domeniu

GET/tools/reputation

Calcul complet al scorului de reputație al domeniului. Verifică SPF, DKIM, DMARC, înregistrări MX, stare blacklist, suport STARTTLS, vechimea domeniului și reverse DNS.

Parametri

domainstringobligatoriu
Numele domeniului de verificat (ex. gmail.com)

Exemplu de request

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

Exemplu de răspuns

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 de livrabilitate a emailurilor

Creează o adresă de test, trimite-i emailul de pe serverul pe care vrei să îl testezi, apoi interoghează rezultatul până când statusul devine completed (de obicei în mai puțin de un minut). Adresele de test expiră după o oră.

POST/test/generate

Creează o nouă adresă de email de test.

Exemplu de request

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

Exemplu de răspuns

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}

Obține statusul și rezultatele unui test. Status: pending → processing → completed (sau expired / error). Scorul este între 0 și 10.

Parametri

testIdstringobligatoriu
ID-ul testului returnat de /test/generate

Exemplu de request

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

Exemplu de răspuns

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

Rulează din nou toate verificările pe un email deja primit, fără a trimite unul nou.

Parametri

testIdstringobligatoriu
ID-ul testului returnat de /test/generate

Exemplu de răspuns

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

Inbox de dezvoltare

Fiecare cont are propria adresă de unică folosință ([email protected], cu orice +tag). Emailurile trimise la ea sunt păstrate 24 de ore și pot fi citite prin API, în panoul de control sau printr-un link de partajare. Folosește-o în testele end-to-end în locul unei căsuțe de email reale.

GET/inbox/wait

Așteaptă (long-poll, până la 60 s) sosirea unui mesaj potrivit și îl returnează cu text, HTML, linkuri și coduri de unică folosință. Returnează 408 dacă nu sosește nimic la timp.

Parametri

tagstring
Doar emailurile trimise la dev-xxxxxx+{tag}@…
timeoutnumber
Secunde de așteptare, 1-60 (implicit 30)
sinceISO 8601
Doar emailurile primite după acest moment (implicit: acum)

Exemplu de request

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"

Disponibile de asemenea:

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

Exemplu de răspuns

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}

Folosește-l dintr-un agent AI (MCP)

Același inbox este și un server MCP, așa că Claude Code, Cursor și alți clienți MCP pot crea adrese, pot aștepta emailuri și le pot citi singuri:

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

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

Coduri de stare HTTP

CodStareDescriere
200OKRequest reușit
400Bad RequestParametru lipsă sau invalid
401UnauthorizedCheie API lipsă, invalidă sau revocată
404Not FoundTestul nu a fost găsit
429Too Many RequestsLimita de cereri a fost depășită (60/minut sau 1.000/zi)
500Internal Server ErrorEroare de server

Răspunsuri de eroare

În caz de eroare, răspunsul conține un câmp error cu descrierea erorii:

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

Exemple de cod

JavaScript / Node.js

javascript
1// Interogare înregistrări 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('Înregistrări MX:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Niciuna');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Niciuna');
12}

Python

python
1import os
2import requests
3
4# Verificare 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"Verificate: {data['totalChecked']} liste")
13print(f"Listat în: {data['totalListed']} locuri")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: LISTAT")

Python - Reputation Check

python
1import os
2import requests
3
4# Verificare reputație domeniu
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("\nFactori:")
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 complet de livrabilitate
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// Verificare 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']} (prioritate: {$mx['priority']})\n";
15    }
16}
17?>

Vrei să încerci API-ul?

Testează instrumentele noastre din interfața web sau începe direct dezvoltarea cu API-ul.