API dokumentacija

API referenca

Vključite MailAudit v svojo aplikacijo: preverjanja DNS, črnih list in ugleda ter celotni testi dostavljivosti e‑pošte prek REST API-ja.

Omejitev zahtevkov

60 zahtevkov / minuto, 1000 / dan na ključ

Osnovni URL

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

Preverjanje pristnosti

Vsak zahtevek potrebuje API ključ. Pošljite ga v glavi Authorization kot žeton Bearer (ali v glavi X-API-Key). Ključ hranite na varnem – ne vgrajujte ga v kodo, ki se izvaja v brskalniku.

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

Vsak odgovor vsebuje glavi X-RateLimit-Remaining in X-RateLimit-Daily-Remaining. Ko je omejitev presežena, prejmete HTTP 429 z glavo Retry-After.

Pridobite API ključ

Endpoints

Preverjanje MX zapisov

GET/tools/mx-check

Poizvedba za MX zapisi domene ter SPF in DMARC nastavitvami.

Parametri

domainstringobvezno
Ime domene za preverjanje (npr. example.com)

Primer zahtevka

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

Primer odziva

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}

Preverjanje črnih list

GET/tools/blacklist-check

Preverite, ali je IP naslov ali domena na glavnih spam bloklistah (32 seznamov DNSBL).

Parametri

querystringobvezno
IP naslov (npr. 192.168.1.1) ali ime domene

Primer zahtevka

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

Primer odziva

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}

Preverjanje ugleda domene

GET/tools/reputation

Celovit izračun ugleda domene. Preveri SPF, DKIM, DMARC, MX zapise, stanje na črnih listah, podporo STARTTLS, starost domene in reverse DNS.

Parametri

domainstringobvezno
Ime domene za preverjanje (npr. gmail.com)

Primer zahtevka

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

Primer odziva

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 dostavljivosti e‑pošte

Ustvarite testni naslov, nanj pošljite e‑pošto s strežnika, ki ga želite preizkusiti, nato pa poizvedujte po rezultatu, dokler stanje ni completed (običajno v eni minuti). Testni naslovi potečejo po eni uri.

POST/test/generate

Ustvari nov testni e‑poštni naslov.

Primer zahtevka

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

Primer odziva

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}

Pridobi stanje in rezultate testa. Stanje: pending → processing → completed (ali expired / error). Ocena je od 0 do 10.

Parametri

testIdstringobvezno
ID testa, ki ga vrne /test/generate

Primer zahtevka

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

Primer odziva

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

Ponovno zažene vsa preverjanja na že prejetem sporočilu, ne da bi bilo treba poslati novo.

Parametri

testIdstringobvezno
ID testa, ki ga vrne /test/generate

Primer odziva

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

Razvijalski predal

Vsak račun ima svoj naslov za enkratno uporabo ([email protected], s poljubno +oznako). Pošta, poslana nanj, se hrani 24 ur in jo lahko preberete prek API-ja, na nadzorni plošči ali prek povezave za deljenje. Uporabite ga v testih end-to-end namesto pravega poštnega predala.

GET/inbox/wait

Čaka (long-poll, do 60 s), dokler ne prispe ustrezno sporočilo, in ga vrne z besedilom, HTML-jem, povezavami in enkratnimi kodami. Če v tem času ne prispe nič, vrne 408.

Parametri

tagstring
Samo pošta, poslana na dev-xxxxxx+{tag}@…
timeoutnumber
Čas čakanja v sekundah, 1-60 (privzeto 30)
sinceISO 8601
Samo pošta, prejeta po tem času (privzeto: zdaj)

Primer zahtevka

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"

Na voljo so tudi:

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

Primer odziva

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}

Uporaba iz agenta AI (MCP)

Isti predal je tudi strežnik MCP, zato lahko Claude Code, Cursor in drugi odjemalci MCP sami ustvarjajo naslove, čakajo na pošto in jo berejo:

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

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

HTTP statusne kode

KodaStanjeOpis
200OKUspešen zahtevek
400Bad RequestManjkajoč ali neveljaven parameter
401UnauthorizedAPI ključ manjka, je neveljaven ali razveljavljen
404Not FoundTest ni bil najden
429Too Many RequestsOmejitev zahtevkov je presežena (60/minuto ali 1000/dan)
500Internal Server ErrorNapaka na strežniku

Odzivi ob napakah

V primeru napake odziv vsebuje polje error z opisom napake:

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

Primeri kode

JavaScript / Node.js

javascript
1// Poizvedba za MX zapise
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 zapisi:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Brez');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Brez');
12}

Python

python
1import os
2import requests
3
4# Preverjanje črnih list
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"Preverjenih: {data['totalChecked']} seznamov")
13print(f"Naveden na: {data['totalListed']} mestih")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: NAVEDEN")

Python - Reputation Check

python
1import os
2import requests
3
4# Preverjanje ugleda domene
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("\nDejavniki:")
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# Celoten test dostavljivosti
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 preverjanje
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']} (prioriteta: {$mx['priority']})\n";
15    }
16}
17?>

Želite preizkusiti API?

Preizkusite naša orodja v spletni aplikaciji ali pa začnite razvoj z API‑jem.