MailAudit
API dokumentacija

API nuoroda

Integruokite MailAudit į savo programą: DNS, juodųjų sąrašų ir reputacijos patikros bei išsamūs el. laiškų pristatomumo testai per REST API.

Užklausų limitas

60 užklausų per minutę, 1000 per dieną vienam raktui

Bazinis URL

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

Autentifikavimas

Kiekvienai užklausai reikalingas API raktas. Siųskite jį Authorization antraštėje kaip Bearer prieigos raktą (arba X-API-Key antraštėje). Laikykite raktą paslaptyje – neįterpkite jo į naršyklėje vykdomą kodą.

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

Kiekviename atsakyme yra antraštės X-RateLimit-Remaining ir X-RateLimit-Daily-Remaining. Viršijus limitą, gausite HTTP 429 su antrašte Retry-After.

Gauti API raktą

Endpoint’ai

MX įrašų patikra

GET/tools/mx-check

Užklausti domeno MX įrašus bei SPF ir DMARC nustatymus.

Parametrai

domainstringprivaloma
Domeno vardas, kurį tikrinsime (pvz. example.com)

Užklausos pavyzdys

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

Atsakymo pavyzdys

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}

Juodųjų sąrašų patikra

GET/tools/blacklist-check

Patikrinti, ar IP adresas arba domenas yra pagrindiniuose šlamšto blokavimo sąrašuose (32 DNSBL).

Parametrai

querystringprivaloma
IP adresas (pvz. 192.168.1.1) arba domeno vardas

Užklausos pavyzdys

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

Atsakymo pavyzdys

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}

Domeno reputacijos patikra

GET/tools/reputation

Išsamus domeno reputacijos balo skaičiavimas. Tikriname SPF, DKIM, DMARC, MX įrašus, juodųjų sąrašų būseną, STARTTLS palaikymą, domeno amžių ir reverse DNS.

Parametrai

domainstringprivaloma
Domeno vardas, kurį tikrinsime (pvz. gmail.com)

Užklausos pavyzdys

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

Atsakymo pavyzdys

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}

El. laiško pristatomumo testas

Sukurkite testinį adresą, išsiųskite juo laišką iš serverio, kurį norite patikrinti, ir tikrinkite rezultatą, kol būsena taps completed (paprastai per minutę). Testiniai adresai nustoja galioti po vienos valandos.

POST/test/generate

Sukurti naują testinį el. pašto adresą.

Užklausos pavyzdys

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

Atsakymo pavyzdys

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}

Gauti testo būseną ir rezultatus. Būsena: pending → processing → completed (arba expired / error). Balas – nuo 0 iki 10.

Parametrai

testIdstringprivaloma
Testo ID, grąžintas /test/generate

Užklausos pavyzdys

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

Atsakymo pavyzdys

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

Pakartotinai paleisti visas patikras jau gautam laiškui, nesiunčiant naujo.

Parametrai

testIdstringprivaloma
Testo ID, grąžintas /test/generate

Atsakymo pavyzdys

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

Kūrėjo pašto dėžutė

Kiekviena paskyra turi savo vienkartinį adresą ([email protected], su bet kokia +žyma). Juo išsiųsti laiškai saugomi 24 valandas ir juos galima skaityti per API, valdymo skydelyje arba per bendrinimo nuorodą. Naudokite jį visapusiuose (end-to-end) testuose vietoj tikros pašto dėžutės.

GET/inbox/wait

Laukia (long-poll, iki 60 s), kol ateis atitinkantis laiškas, ir grąžina jį su tekstu, HTML, nuorodomis ir vienkartiniais kodais. Jei laiku nieko neateina, grąžina 408.

Parametrai

tagstring
Tik laiškai, išsiųsti adresu dev-xxxxxx+{tag}@…
timeoutnumber
Laukimo trukmė sekundėmis, 1–60 (numatytoji 30)
sinceISO 8601
Tik po šio laiko gauti laiškai (numatytasis: dabar)

Užklausos pavyzdys

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"

Taip pat pasiekiama:

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

Atsakymo pavyzdys

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}

Naudokite jį iš DI agento (MCP)

Ta pati pašto dėžutė yra ir MCP serveris, todėl Claude Code, Cursor ir kiti MCP klientai patys gali kurti adresus, laukti laiškų ir juos skaityti:

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

Įrankiai: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

HTTP būsenos kodai

KodasBūsenaAprašymas
200OKUžklausa sėkminga
400Bad RequestTrūksta arba neteisingas parametras
401UnauthorizedAPI rakto trūksta, jis netinkamas arba atšauktas
404Not FoundTestas nerastas
429Too Many RequestsViršytas užklausų limitas (60 per minutę arba 1000 per dieną)
500Internal Server ErrorServerio klaida

Klaidų atsakymai

Klaidos atveju atsakyme bus pateiktas error laukas su klaidos aprašymu:

json
{
  "error": "Reikalingas domenas"
}

Kodo pavyzdžiai

JavaScript / Node.js

javascript
1// Užklausti MX įrašus
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 įrašai:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Nėra');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Nėra');
12}

Python

python
1import os
2import requests
3
4# Juodųjų sąrašų patikra
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"Patikrinta: {data['totalChecked']} sąrašų")
13print(f"Įtraukta į: {data['totalListed']} vietų")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: SĄRAŠE")

Python - Reputation Check

python
1import os
2import requests
3
4# Domeno reputacijos patikra
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("\nVeiksniai:")
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# Išsamus pristatomumo testas
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 patikra
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']} (prioritetas: {$mx['priority']})\n";
15    }
16}
17?>

Norite išbandyti API?

Išbandykite mūsų įrankius žiniatinklyje arba pradėkite kurti integraciją su API.