MailAudit
Dokumentacja API

Referencja API

Zintegruj MailAudit z własną aplikacją: sprawdzanie DNS, list blokujących i reputacji oraz pełne testy dostarczalności e‑maili przez REST API.

Limit zapytań

60 zapytań / minutę, 1000 / dzień na klucz

Bazowy URL

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

Uwierzytelnianie

Każde zapytanie wymaga klucza API. Wyślij go w nagłówku Authorization jako token Bearer (lub w nagłówku X-API-Key). Zachowaj klucz w tajemnicy – nie umieszczaj go w kodzie działającym w przeglądarce.

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

Każda odpowiedź zawiera nagłówki X-RateLimit-Remaining i X-RateLimit-Daily-Remaining. Po przekroczeniu limitu otrzymasz HTTP 429 z nagłówkiem Retry-After.

Uzyskaj klucz API

Endpointy

Sprawdzenie rekordu MX

GET/tools/mx-check

Zapytanie o rekordy MX domeny oraz ustawienia SPF i DMARC.

Parametry

domainstringwymagany
Nazwa domeny do sprawdzenia (np. example.com)

Przykładowe zapytanie

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

Przykład odpowiedzi

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}

Sprawdzenie blacklist

GET/tools/blacklist-check

Sprawdź, czy adres IP lub domena znajduje się na głównych listach blokujących spam (32 list DNSBL).

Parametry

querystringwymagany
Adres IP (np. 192.168.1.1) lub nazwa domeny

Przykładowe zapytanie

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

Przykład odpowiedzi

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}

Sprawdzenie reputacji domeny

GET/tools/reputation

Kompleksowe wyliczenie wyniku reputacji domeny. Sprawdza SPF, DKIM, DMARC, rekordy MX, status blacklist, wsparcie STARTTLS, wiek domeny oraz reverse DNS.

Parametry

domainstringwymagany
Nazwa domeny do sprawdzenia (np. gmail.com)

Przykładowe zapytanie

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

Przykład odpowiedzi

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 dostarczalności e‑maila

Utwórz adres testowy, wyślij na niego e‑mail z serwera, który chcesz przetestować, a następnie odpytuj o wynik, aż status będzie completed (zwykle w ciągu minuty). Adresy testowe wygasają po godzinie.

POST/test/generate

Utwórz nowy testowy adres e‑mail.

Przykładowe zapytanie

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

Przykład odpowiedzi

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}

Pobierz status i wyniki testu. Status: pending → processing → completed (lub expired / error). Wynik mieści się w skali 0–10.

Parametry

testIdstringwymagany
ID testu zwrócone przez /test/generate

Przykładowe zapytanie

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

Przykład odpowiedzi

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

Uruchom ponownie wszystkie sprawdzenia dla już odebranego e‑maila, bez wysyłania nowego.

Parametry

testIdstringwymagany
ID testu zwrócone przez /test/generate

Przykład odpowiedzi

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

Skrzynka deweloperska

Każde konto ma własny jednorazowy adres ([email protected], z dowolnym +tagiem). Wysłana na niego poczta jest przechowywana przez 24 godziny i można ją odczytać przez API, w panelu lub za pomocą linku do udostępnienia. Używaj go w testach end-to-end zamiast prawdziwej skrzynki pocztowej.

GET/inbox/wait

Czeka (long-poll, do 60 s), aż nadejdzie pasująca wiadomość, i zwraca ją z tekstem, HTML, linkami i kodami jednorazowymi. Zwraca 408, jeśli nic nie nadejdzie na czas.

Parametry

tagstring
Tylko poczta wysłana na dev-xxxxxx+{tag}@…
timeoutnumber
Czas oczekiwania w sekundach, 1-60 (domyślnie 30)
sinceISO 8601
Tylko poczta odebrana po tym czasie (domyślnie: teraz)

Przykładowe zapytanie

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"

Dostępne także:

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

Przykład odpowiedzi

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}

Używaj jej z agenta AI (MCP)

Ta sama skrzynka jest serwerem MCP, więc Claude Code, Cursor i inni klienci MCP mogą samodzielnie tworzyć adresy, czekać na pocztę i ją czytać:

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

Narzędzia: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

Kody statusu HTTP

KodStatusOpis
200OKZapytanie zakończone powodzeniem
400Bad RequestBrak lub nieprawidłowy parametr
401UnauthorizedBrak klucza API, klucz nieprawidłowy lub unieważniony
404Not FoundNie znaleziono testu
429Too Many RequestsPrzekroczono limit zapytań (60/minutę lub 1000/dzień)
500Internal Server ErrorBłąd po stronie serwera

Odpowiedzi błędów

W przypadku błędu odpowiedź zawiera pole error z opisem błędu:

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

Przykłady kodu

JavaScript / Node.js

javascript
1// Zapytanie o rekordy 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('Rekordy MX:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Brak');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Brak');
12}

Python

python
1import os
2import requests
3
4# Sprawdzenie 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"Sprawdzono: {data['totalChecked']} list")
13print(f"Na listach: {data['totalListed']} wpisów")
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# Sprawdzenie reputacji domeny
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("\nCzynniki:")
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# Pełny test dostarczalności
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// Sprawdzenie 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']} (priorytet: {$mx['priority']})\n";
15    }
16}
17?>

Chcesz wypróbować API?

Przetestuj nasze narzędzia w interfejsie webowym lub zacznij integrację z API.