API Reference
Ενσωμάτωσε το MailAudit στη δική σου εφαρμογή: έλεγχοι DNS, blacklist και φήμης, καθώς και πλήρη τεστ παραδοσιμότητας email μέσω REST API.
Απαιτείται κλειδί API
Δωρεάν — δημιούργησέ το στον πίνακα ελέγχουRate limit
60 αιτήματα / λεπτό, 1.000 / ημέρα ανά κλειδί
Base URL
https://api.mailaudit.io/api/v1
Αυθεντικοποίηση
Κάθε αίτημα χρειάζεται κλειδί API. Στείλ’ το στην κεφαλίδα Authorization ως Bearer token (ή στην κεφαλίδα X-API-Key). Κράτα το κλειδί σου μυστικό — μην το ενσωματώνεις σε κώδικα που εκτελείται στον browser.
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.
Endpoints
Έλεγχος MX εγγραφών
/tools/mx-checkΕρώτημα για τις MX εγγραφές ενός domain, καθώς και τις ρυθμίσεις SPF και DMARC.
Parameters
domainstringυποχρεωτικόΠαράδειγμα request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/tools/mx-check?domain=gmail.com"Παράδειγμα response
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
/tools/blacklist-checkΈλεγχος αν μια διεύθυνση IP ή ένα domain βρίσκεται σε βασικές spam blocklists (32 DNSBL).
Parameters
querystringυποχρεωτικόΠαράδειγμα request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/tools/blacklist-check?query=8.8.8.8"Παράδειγμα response
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
/tools/reputationΟλοκληρωμένος υπολογισμός βαθμολογίας φήμης domain. Ελέγχει SPF, DKIM, DMARC, MX εγγραφές, κατάσταση blacklist, υποστήριξη STARTTLS, ηλικία domain και reverse DNS.
Parameters
domainstringυποχρεωτικόΠαράδειγμα request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/tools/reputation?domain=gmail.com"Κλίμακα βαθμολόγησης
Παράδειγμα response
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 (συνήθως μέσα σε ένα λεπτό). Οι δοκιμαστικές διευθύνσεις λήγουν μετά από μία ώρα.
/test/generateΔημιουργεί νέα δοκιμαστική διεύθυνση email.
Παράδειγμα request
curl -X POST -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/test/generate"Παράδειγμα response
1{
2 "testId": "k3v9x2m1qa",
3 "email": "[email protected]",
4 "expiresAt": "2026-09-24T18:44:14.762Z",
5 "checkUrl": "/test/k3v9x2m1qa"
6}/test/{testId}Επιστρέφει την κατάσταση και τα αποτελέσματα ενός τεστ. Κατάσταση: pending → processing → completed (ή expired / error). Η βαθμολογία είναι 0–10.
Parameters
testIdstringυποχρεωτικόΠαράδειγμα request
curl -H "Authorization: Bearer $MAILAUDIT_API_KEY" \
"https://api.mailaudit.io/api/v1/test/k3v9x2m1qa"Παράδειγμα response
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}/test/{testId}/recheckΕκτελεί ξανά όλους τους ελέγχους σε email που έχει ήδη ληφθεί, χωρίς να στείλεις νέο.
Parameters
testIdstringυποχρεωτικόΠαράδειγμα response
1{
2 "success": true,
3 "testId": "k3v9x2m1qa",
4 "message": "Recheck initiated - checks are running"
5}Γραμματοκιβώτιο προγραμματιστών
Κάθε λογαριασμός έχει τη δική του προσωρινή διεύθυνση ([email protected], με οποιοδήποτε +tag). Τα μηνύματα που στέλνονται σε αυτήν διατηρούνται για 24 ώρες και μπορείς να τα διαβάσεις μέσω του API, στον πίνακα ελέγχου ή μέσω συνδέσμου κοινοποίησης. Χρησιμοποίησέ τη σε end-to-end τεστ αντί για πραγματικό γραμματοκιβώτιο.
/inbox/waitΠεριμένει (long-poll, έως 60 s) μέχρι να φτάσει ένα αντίστοιχο μήνυμα και το επιστρέφει με κείμενο, HTML, συνδέσμους και κωδικούς μίας χρήσης. Επιστρέφει 408 αν δεν φτάσει τίποτα εγκαίρως.
Parameters
tagstringtimeoutnumbersinceISO 8601Παράδειγμα request
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
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 μπορούν να δημιουργούν διευθύνσεις, να περιμένουν μηνύματα και να τα διαβάζουν μόνοι τους:
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
| Κωδικός | Κατάσταση | Περιγραφή |
|---|---|---|
| 200 | OK | Επιτυχές αίτημα |
| 400 | Bad Request | Λείπει ή είναι άκυρη κάποια παράμετρος |
| 401 | Unauthorized | Κλειδί API που λείπει, δεν είναι έγκυρο ή έχει ανακληθεί |
| 404 | Not Found | Το τεστ δεν βρέθηκε |
| 429 | Too Many Requests | Υπέρβαση ορίου αιτημάτων (60/λεπτό ή 1.000/ημέρα) |
| 500 | Internal Server Error | Σφάλμα στον server |
Responses σφαλμάτων
Σε περίπτωση σφάλματος, το response περιέχει πεδίο error με την περιγραφή:
{
"error": "Απαιτείται domain"
}Παραδείγματα κώδικα
JavaScript / Node.js
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
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
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
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
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.