Dokumentacioni i API

Referenca e API

Integro MailAudit në aplikacionin tënd: kontrolle DNS, të listave të zeza dhe të reputacionit, si dhe teste të plota të dorëzueshmërisë së email-it përmes një API REST.

Rate limit

60 kërkesa / minutë, 1.000 / ditë për çelës

Base URL

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

Autentikimi

Çdo kërkesë ka nevojë për një çelës API. Dërgoje në header-in Authorization si token Bearer (ose në header-in X-API-Key). Mbaje çelësin sekret — mos e vendos në kod që ekzekutohet në shfletues.

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

Çdo përgjigje përmban header-at X-RateLimit-Remaining dhe X-RateLimit-Daily-Remaining. Kur tejkalohet një kufi, merr HTTP 429 me një header Retry-After.

Merr një çelës API

Endpoints

Kontroll i rekordit MX

GET/tools/mx-check

Pyet rekordet MX të një domeni, si dhe cilësimet SPF dhe DMARC.

Parametrat

domainstringe detyrueshme
Emri i domenit për t’u kontrolluar (p.sh. example.com)

Shembull kërkese

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

Shembull përgjigjeje

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}

Kontroll liste të zezë

GET/tools/blacklist-check

Kontrollo nëse një adresë IP ose domen është në listat kryesore të bllokimit për spam (32 DNSBL).

Parametrat

querystringe detyrueshme
Adresë IP (p.sh. 192.168.1.1) ose emër domeni

Shembull kërkese

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

Shembull përgjigjeje

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}

Kontroll reputacioni domeni

GET/tools/reputation

Llogaritje gjithëpërfshirëse e pikëzimit të reputacionit të domenit. Kontrollon SPF, DKIM, DMARC, regjistrat MX, statusin në listat e zeza, mbështetjen STARTTLS, moshën e domenit dhe reverse DNS.

Parametrat

domainstringe detyrueshme
Emri i domenit për t’u kontrolluar (p.sh. gmail.com)

Shembull kërkese

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

Shembull përgjigjeje

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}

Testi i dorëzueshmërisë së email-it

Krijo një adresë testi, dërgo email-in tënd në të nga serveri që do të testosh, pastaj kontrollo rezultatin periodikisht derisa statusi të jetë completed (zakonisht brenda një minute). Adresat e testit skadojnë pas një ore.

POST/test/generate

Krijon një adresë të re email-i testi.

Shembull kërkese

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

Shembull përgjigjeje

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}

Merr statusin dhe rezultatet e një testi. Statusi: pending → processing → completed (ose expired / error). Pikët janë nga 0 deri në 10.

Parametrat

testIdstringe detyrueshme
ID e testit e kthyer nga /test/generate

Shembull kërkese

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

Shembull përgjigjeje

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

Ekzekuton sërish të gjitha kontrollet mbi një email që është marrë tashmë, pa dërguar një të ri.

Parametrat

testIdstringe detyrueshme
ID e testit e kthyer nga /test/generate

Shembull përgjigjeje

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

Kutia postare e zhvilluesit

Çdo llogari ka adresën e vet të përkohshme ([email protected], me çfarëdo +tag). Email-et e dërguara në të ruhen për 24 orë dhe mund të lexohen përmes API-së, në panel ose përmes një lidhjeje ndarjeje. Përdore në testet end-to-end në vend të një kutie postare reale.

GET/inbox/wait

Pret (long-poll, deri në 60 s) derisa të mbërrijë një mesazh që përputhet dhe e kthen me tekst, HTML, lidhje dhe kode njëpërdorimshe. Kthen 408 nëse nuk mbërrin asgjë në kohë.

Parametrat

tagstring
Vetëm email-et e dërguara te dev-xxxxxx+{tag}@…
timeoutnumber
Sekonda pritjeje, 1-60 (parazgjedhja 30)
sinceISO 8601
Vetëm email-et e marra pas këtij momenti (parazgjedhja: tani)

Shembull kërkese

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"

Gjithashtu në dispozicion:

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

Shembull përgjigjeje

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}

Përdore nga një agjent AI (MCP)

E njëjta kuti postare është edhe server MCP, kështu që Claude Code, Cursor dhe klientë të tjerë MCP mund të krijojnë adresa, të presin email-e dhe t’i lexojnë vetë:

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

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

Kodet HTTP Status

KodiStatusiPërshkrimi
200OKKërkesë e suksesshme
400Bad RequestParametër që mungon ose i pavlefshëm
401UnauthorizedÇelës API që mungon, i pavlefshëm ose i revokuar
404Not FoundTesti nuk u gjet
429Too Many RequestsU tejkalua kufiri i kërkesave (60/minutë ose 1.000/ditë)
500Internal Server ErrorGabim nga ana e serverit

Përgjigjet e gabimit

Në rast gabimi, përgjigja përmban një fushë error me përshkrimin e gabimit:

json
{
  "error": "Domain është i detyrueshëm"
}

Shembuj kodi

JavaScript / Node.js

javascript
1// Pyet rekordet 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('Rekordet MX:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Asnjë');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Asnjë');
12}

Python

python
1import os
2import requests
3
4# Kontroll liste të zezë
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"Të kontrolluara: {data['totalChecked']} lista")
13print(f"I listuar në: {data['totalListed']} vende")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: I LISTUAR")

Python - Reputation Check

python
1import os
2import requests
3
4# Kontroll reputacioni domeni
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("\nFaktorët:")
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 i plotë i dorëzueshmërisë
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// Kontroll 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']} (prioritet: {$mx['priority']})\n";
15    }
16}
17?>

Do ta provosh API-n?

Provo mjetet tona në ndërfaqen web ose nis zhvillimin direkt me API.