API dokumentacija

API referenca

Integrirajte MailAudit u vlastitu aplikaciju: provjere DNS-a, blocklista i reputacije te potpuni testovi dostavljivosti emailova putem REST API-ja.

Rate limit

60 zahtjeva / minuta, 1.000 / dan po ključu

Osnovni URL

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

Autentifikacija

Svaki zahtjev zahtijeva API ključ. Pošaljite ga u zaglavlju Authorization kao Bearer token (ili u zaglavlju X-API-Key). Čuvajte ključ u tajnosti – nemojte ga ugrađivati u kod koji se izvršava u pregledniku.

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

Svaki odgovor sadrži zaglavlja X-RateLimit-Remaining i X-RateLimit-Daily-Remaining. Kada se ograničenje prekorači, dobit ćete HTTP 429 sa zaglavljem Retry-After.

Nabavite API ključ

Endpointi

Provjera MX zapisa

GET/tools/mx-check

Upit za MX zapise domene, kao i SPF i DMARC postavke.

Parametri

domainstringobavezno
Naziv domene za provjeru (npr. example.com)

Primjer zahtjeva

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

Primjer odgovora

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}

Provjera blocklista

GET/tools/blacklist-check

Provjerite nalazi li se IP adresa ili domena na glavnim spam blocklistama (32 DNSBL lista).

Parametri

querystringobavezno
IP adresa (npr. 192.168.1.1) ili naziv domene

Primjer zahtjeva

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

Primjer odgovora

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}

Provjera reputacije domene

GET/tools/reputation

Sveobuhvatni izračun reputacijskog rezultata domene. Provjerava SPF, DKIM, DMARC, MX zapise, status na blocklistama, STARTTLS podršku, starost domene i reverse DNS.

Parametri

domainstringobavezno
Naziv domene za provjeru (npr. gmail.com)

Primjer zahtjeva

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

Primjer odgovora

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 emaila

Izradite testnu adresu, pošaljite na nju email s poslužitelja koji želite testirati, a zatim dohvaćajte rezultat dok status ne bude completed (obično unutar minute). Testne adrese istječu nakon sat vremena.

POST/test/generate

Izradite novu testnu email adresu.

Primjer zahtjeva

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

Primjer odgovora

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}

Dohvatite status i rezultate testa. Status: pending → processing → completed (ili expired / error). Rezultat je od 0 do 10.

Parametri

testIdstringobavezno
ID testa koji vraća /test/generate

Primjer zahtjeva

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

Primjer odgovora

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 pokrenite sve provjere na emailu koji je već primljen, bez slanja novog.

Parametri

testIdstringobavezno
ID testa koji vraća /test/generate

Primjer odgovora

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

Razvojni sandučić

Svaki račun ima vlastitu jednokratnu adresu ([email protected], s bilo kojom +oznakom). Pošta poslana na nju čuva se 24 sata i može se čitati putem API-ja, na nadzornoj ploči ili putem poveznice za dijeljenje. Koristite je u end-to-end testovima umjesto stvarnog poštanskog sandučića.

GET/inbox/wait

Čeka (long-poll, do 60 s) dok ne stigne odgovarajuća poruka i vraća je s tekstom, HTML-om, poveznicama i jednokratnim kodovima. Vraća 408 ako ništa ne stigne na vrijeme.

Parametri

tagstring
Samo pošta poslana na dev-xxxxxx+{tag}@…
timeoutnumber
Broj sekundi čekanja, 1-60 (zadano 30)
sinceISO 8601
Samo pošta primljena nakon ovog vremena (zadano: sada)

Primjer zahtjeva

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"

Dostupno je i:

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

Primjer odgovora

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}

Korištenje iz AI agenta (MCP)

Isti sandučić je i MCP poslužitelj, pa Claude Code, Cursor i drugi MCP klijenti mogu samostalno izrađivati adrese, čekati poštu i čitati je:

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

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

HTTP status kodovi

KodStatusOpis
200OKZahtjev uspješan
400Bad RequestNedostaje ili je neispravan parametar
401UnauthorizedAPI ključ nedostaje, neispravan je ili je opozvan
404Not FoundTest nije pronađen
429Too Many RequestsPrekoračeno ograničenje broja zahtjeva (60/minuta ili 1.000/dan)
500Internal Server ErrorGreška na poslužitelju

Odgovori kod grešaka

U slučaju greške, odgovor sadrži polje error s opisom problema:

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

Primjeri koda

JavaScript / Node.js

javascript
1// Upit 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 : 'Nema');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Nema');
12}

Python

python
1import os
2import requests
3
4# Provjera blocklista
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"Provjereno: {data['totalChecked']} lista")
13print(f"Na listama: {data['totalListed']} puta")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: NA LISTI")

Python - Reputation Check

python
1import os
2import requests
3
4# Provjera reputacije 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("\nFaktori:")
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# Potpuni 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 provjera
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?>

Želite isprobati API?

Isprobajte naše alate preko web sučelja ili počnite integraciju putem API‑ja.