MailAudit
API документация

API референция

Интегрирайте MailAudit в собственото си приложение: DNS проверки, проверки в черни списъци и на репутация, както и пълни тестове за доставяемост на имейли чрез REST API.

Ограничение

60 заявки / минута, 1000 / ден на ключ

Базов URL

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

Удостоверяване

Всяка заявка изисква API ключ. Изпращайте го в заглавката Authorization като Bearer токен (или в заглавката X-API-Key). Пазете ключа си в тайна — не го вграждайте в код, който се изпълнява в браузъра.

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

Всеки отговор съдържа заглавките X-RateLimit-Remaining и X-RateLimit-Daily-Remaining. При превишаване на ограничение получавате HTTP 429 със заглавка Retry-After.

Вземете API ключ

Endpoints

Проверка на MX записи

GET/tools/mx-check

Заявка за MX записите на домейн, както и SPF и DMARC настройките.

Параметри

domainstringзадължителен
Името на домейна за проверка (напр. example.com)

Примерна заявка

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

Примерен отговор

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}

Проверка в черни списъци

GET/tools/blacklist-check

Проверете дали IP адрес или домейн е в основните спам блокиращи списъци (32 DNSBL).

Параметри

querystringзадължителен
IP адрес (напр. 192.168.1.1) или име на домейн

Примерна заявка

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

Примерен отговор

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}

Проверка на репутацията на домейн

GET/tools/reputation

Подробно изчисляване на репутационна оценка на домейн. Проверява SPF, DKIM, DMARC, MX записи, статус в черни списъци, поддръжка на STARTTLS, възраст на домейна и обратен DNS.

Параметри

domainstringзадължителен
Името на домейна за проверка (напр. gmail.com)

Примерна заявка

bash
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
  "https://api.mailaudit.io/api/v1/tools/reputation?domain=gmail.com"
Скала за оценка
90-100 = A+
80-89 = A
70-79 = B
60-69 = C
50-59 = D
0-49 = F

Примерен отговор

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}

Тест за доставяемост на имейл

Създайте тестов адрес, изпратете имейла си до него от сървъра, който искате да тествате, след това проверявайте резултата, докато статусът стане completed (обикновено до минута). Тестовите адреси изтичат след един час.

POST/test/generate

Създава нов тестов имейл адрес.

Примерна заявка

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

Примерен отговор

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}

Връща статуса и резултатите от тест. Статус: pending → processing → completed (или expired / error). Оценката е от 0 до 10.

Параметри

testIdstringзадължителен
ID на теста, върнат от /test/generate

Примерна заявка

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

Примерен отговор

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

Изпълнява отново всички проверки върху вече получен имейл, без да се изпраща нов.

Параметри

testIdstringзадължителен
ID на теста, върнат от /test/generate

Примерен отговор

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

Пощенска кутия за разработчици

Всеки акаунт има собствен временен адрес ([email protected], с произволен +таг). Пощата, изпратена до него, се пази 24 часа и може да се чете чрез API, в таблото или чрез линк за споделяне. Използвайте го в end-to-end тестове вместо истинска пощенска кутия.

GET/inbox/wait

Изчаква (long-poll, до 60 s), докато пристигне съответстващо съобщение, и го връща с текст, HTML, линкове и еднократни кодове. Връща 408, ако нищо не пристигне навреме.

Параметри

tagstring
Само поща, изпратена до dev-xxxxxx+{tag}@…
timeoutnumber
Секунди за изчакване, 1-60 (по подразбиране 30)
sinceISO 8601
Само поща, получена след този момент (по подразбиране: сега)

Примерна заявка

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"

Налични са също:

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

Примерен отговор

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}

Използване от AI агент (MCP)

Същата пощенска кутия е и MCP сървър, така че Claude Code, Cursor и други MCP клиенти могат сами да създават адреси, да изчакват поща и да я четат:

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

Инструменти: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

HTTP статус кодове

КодСтатусОписание
200OKУспешна заявка
400Bad RequestЛипсващ или невалиден параметър
401UnauthorizedЛипсващ, невалиден или отменен API ключ
404Not FoundТестът не е намерен
429Too Many RequestsПревишено ограничение на заявките (60/минута или 1000/ден)
500Internal Server ErrorСървърна грешка

Грешки в отговорите

При грешка, отговорът съдържа поле error с описание на грешката:

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

Примери с код

JavaScript / Node.js

javascript
1// Заявка за 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('MX записи:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Няма');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Няма');
12}

Python

python
1import os
2import requests
3
4# Проверка в черни списъци
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"Проверени: {data['totalChecked']} списъка")
13print(f"Включен в: {data['totalListed']} списъци")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: LISTED")

Python - Reputation Check

python
1import os
2import requests
3
4# Проверка на репутация на домейн
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("\nФактори:")
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# Пълен тест за доставяемост
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 проверка
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']} (приоритет: {$mx['priority']})\n";
15    }
16}
17?>

Искате да пробвате API?

Изпробвайте инструментите през уеб интерфейса или започнете интеграция с API.