MailAudit
API Documentation

API Reference

Ενσωμάτωσε το MailAudit στη δική σου εφαρμογή: έλεγχοι DNS, blacklist και φήμης, καθώς και πλήρη τεστ παραδοσιμότητας email μέσω REST API.

Rate limit

60 αιτήματα / λεπτό, 1.000 / ημέρα ανά κλειδί

Base URL

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

Αυθεντικοποίηση

Κάθε αίτημα χρειάζεται κλειδί API. Στείλ’ το στην κεφαλίδα Authorization ως Bearer token (ή στην κεφαλίδα X-API-Key). Κράτα το κλειδί σου μυστικό — μην το ενσωματώνεις σε κώδικα που εκτελείται στον browser.

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 εγγραφές ενός domain, καθώς και τις ρυθμίσεις SPF και DMARC.

Parameters

domainstringυποχρεωτικό
Το domain που θα ελεγχθεί (π.χ. example.com)

Παράδειγμα request

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

Παράδειγμα response

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}

Έλεγχος blacklist

GET/tools/blacklist-check

Έλεγχος αν μια διεύθυνση IP ή ένα domain βρίσκεται σε βασικές spam blocklists (32 DNSBL).

Parameters

querystringυποχρεωτικό
IP διεύθυνση (π.χ. 192.168.1.1) ή όνομα domain

Παράδειγμα request

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

Παράδειγμα response

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}

Έλεγχος φήμης domain

GET/tools/reputation

Ολοκληρωμένος υπολογισμός βαθμολογίας φήμης domain. Ελέγχει SPF, DKIM, DMARC, MX εγγραφές, κατάσταση blacklist, υποστήριξη STARTTLS, ηλικία domain και reverse DNS.

Parameters

domainstringυποχρεωτικό
Το domain που θα ελεγχθεί (π.χ. gmail.com)

Παράδειγμα request

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

Παράδειγμα response

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}

Τεστ παραδοσιμότητας email

Δημιούργησε μια δοκιμαστική διεύθυνση, στείλε σε αυτήν το email σου από τον server που θέλεις να ελέγξεις και μετά κάνε polling στο αποτέλεσμα μέχρι η κατάσταση να γίνει completed (συνήθως μέσα σε ένα λεπτό). Οι δοκιμαστικές διευθύνσεις λήγουν μετά από μία ώρα.

POST/test/generate

Δημιουργεί νέα δοκιμαστική διεύθυνση email.

Παράδειγμα request

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

Παράδειγμα response

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.

Parameters

testIdstringυποχρεωτικό
ID τεστ που επιστράφηκε από το /test/generate

Παράδειγμα request

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

Παράδειγμα response

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

Εκτελεί ξανά όλους τους ελέγχους σε email που έχει ήδη ληφθεί, χωρίς να στείλεις νέο.

Parameters

testIdstringυποχρεωτικό
ID τεστ που επιστράφηκε από το /test/generate

Παράδειγμα response

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

Γραμματοκιβώτιο προγραμματιστών

Κάθε λογαριασμός έχει τη δική του προσωρινή διεύθυνση ([email protected], με οποιοδήποτε +tag). Τα μηνύματα που στέλνονται σε αυτήν διατηρούνται για 24 ώρες και μπορείς να τα διαβάσεις μέσω του API, στον πίνακα ελέγχου ή μέσω συνδέσμου κοινοποίησης. Χρησιμοποίησέ τη σε end-to-end τεστ αντί για πραγματικό γραμματοκιβώτιο.

GET/inbox/wait

Περιμένει (long-poll, έως 60 s) μέχρι να φτάσει ένα αντίστοιχο μήνυμα και το επιστρέφει με κείμενο, HTML, συνδέσμους και κωδικούς μίας χρήσης. Επιστρέφει 408 αν δεν φτάσει τίποτα εγκαίρως.

Parameters

tagstring
Μόνο μηνύματα που στάλθηκαν στο dev-xxxxxx+{tag}@…
timeoutnumber
Δευτερόλεπτα αναμονής, 1-60 (προεπιλογή 30)
sinceISO 8601
Μόνο μηνύματα που ελήφθησαν μετά από αυτή τη χρονική στιγμή (προεπιλογή: τώρα)

Παράδειγμα request

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}

Παράδειγμα response

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 agent (MCP)

Το ίδιο γραμματοκιβώτιο είναι MCP server, οπότε το Claude Code, το Cursor και άλλοι MCP clients μπορούν να δημιουργούν διευθύνσεις, να περιμένουν μηνύματα και να τα διαβάζουν μόνοι τους:

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 Status Codes

ΚωδικόςΚατάστασηΠεριγραφή
200OKΕπιτυχές αίτημα
400Bad RequestΛείπει ή είναι άκυρη κάποια παράμετρος
401UnauthorizedΚλειδί API που λείπει, δεν είναι έγκυρο ή έχει ανακληθεί
404Not FoundΤο τεστ δεν βρέθηκε
429Too Many RequestsΥπέρβαση ορίου αιτημάτων (60/λεπτό ή 1.000/ημέρα)
500Internal Server ErrorΣφάλμα στον server

Responses σφαλμάτων

Σε περίπτωση σφάλματος, το response περιέχει πεδίο error με την περιγραφή:

json
{
  "error": "Απαιτείται domain"
}

Παραδείγματα κώδικα

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# Έλεγχος 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"Ελέγχθηκαν: {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# Έλεγχος φήμης domain
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 check
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;

Δοκίμασε τα εργαλεία μας από το web interface ή ξεκίνα ανάπτυξη με το API.