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.
Cheie API obligatorie
Gratuită — creeaz-o în panoul de controlLimită 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.
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.
Endpoint-uri
Verificare înregistrări MX
/tools/mx-checkInteroghează înregistrările MX ale unui domeniu, precum și setările SPF și DMARC.
Parametri
domainstringobligatoriuExemplu de request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/tools/mx-check?domain=gmail.com"Exemplu de răspuns
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
/tools/blacklist-checkVerifică dacă o adresă IP sau un domeniu este în principalele liste de blocare pentru spam (32 de DNSBL-uri).
Parametri
querystringobligatoriuExemplu de request
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
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
/tools/reputationCalcul 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
domainstringobligatoriuExemplu de request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/tools/reputation?domain=gmail.com"Scală de notare
Exemplu de răspuns
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ă.
/test/generateCreează o nouă adresă de email de test.
Exemplu de request
curl -X POST -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/test/generate"Exemplu de răspuns
1{
2 "testId": "k3v9x2m1qa",
3 "email": "[email protected]",
4 "expiresAt": "2026-09-24T18:44:14.762Z",
5 "checkUrl": "/test/k3v9x2m1qa"
6}/test/{testId}Obține statusul și rezultatele unui test. Status: pending → processing → completed (sau expired / error). Scorul este între 0 și 10.
Parametri
testIdstringobligatoriuExemplu de request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/test/k3v9x2m1qa"Exemplu de răspuns
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}/test/{testId}/recheckRulează din nou toate verificările pe un email deja primit, fără a trimite unul nou.
Parametri
testIdstringobligatoriuExemplu de răspuns
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.
/inbox/waitAș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
tagstringtimeoutnumbersinceISO 8601Exemplu de request
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
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:
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
| Cod | Stare | Descriere |
|---|---|---|
| 200 | OK | Request reușit |
| 400 | Bad Request | Parametru lipsă sau invalid |
| 401 | Unauthorized | Cheie API lipsă, invalidă sau revocată |
| 404 | Not Found | Testul nu a fost găsit |
| 429 | Too Many Requests | Limita de cereri a fost depășită (60/minut sau 1.000/zi) |
| 500 | Internal Server Error | Eroare de server |
Răspunsuri de eroare
În caz de eroare, răspunsul conține un câmp error cu descrierea erorii:
{
"error": "Domain is required"
}Exemple de cod
JavaScript / Node.js
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
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
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
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
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.