MailAudit
API Dokümantasyonu

API Referansı

MailAudit’i kendi uygulamanıza entegre edin: DNS, kara liste ve itibar kontrolleri ile tam e‑posta teslim edilebilirlik testleri bir REST API üzerinden.

Oran sınırı

Anahtar başına dakikada 60, günde 1.000 istek

Temel URL

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

Kimlik doğrulama

Her istek bir API anahtarı gerektirir. Anahtarı Authorization başlığında Bearer token olarak (veya X-API-Key başlığında) gönderin. Anahtarınızı gizli tutun — tarayıcı koduna gömmeyin.

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

Her cevapta X-RateLimit-Remaining ve X-RateLimit-Daily-Remaining başlıkları bulunur. Bir sınır aşıldığında Retry-After başlığıyla birlikte HTTP 429 alırsınız.

API anahtarı alın

Endpoint’ler

MX kayıt kontrolü

GET/tools/mx-check

Bir alan adının MX kayıtlarını, ayrıca SPF ve DMARC ayarlarını sorgulayın.

Parametreler

domainstringzorunlu
Kontrol edilecek alan adı (örn. example.com)

Örnek istek

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

Örnek cevap

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}

Kara liste kontrolü

GET/tools/blacklist-check

Bir IP adresi veya alan adının büyük spam engel listelerinde (32 DNSBL) yer alıp almadığını kontrol edin.

Parametreler

querystringzorunlu
IP adresi (örn. 192.168.1.1) veya alan adı

Örnek istek

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

Örnek cevap

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}

Alan adı itibarı kontrolü

GET/tools/reputation

Kapsamlı alan adı itibar puanı hesaplaması. SPF, DKIM, DMARC, MX kayıtları, kara liste durumu, STARTTLS desteği, alan adı yaşı ve ters DNS’i kontrol eder.

Parametreler

domainstringzorunlu
Kontrol edilecek alan adı (örn. gmail.com)

Örnek istek

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

Örnek cevap

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}

E‑posta teslim edilebilirlik testi

Bir test adresi oluşturun, test etmek istediğiniz sunucudan e‑postanızı bu adrese gönderin, ardından durum completed olana kadar sonucu sorgulayın (genellikle bir dakika içinde). Test adreslerinin süresi bir saat sonra dolar.

POST/test/generate

Yeni bir test e‑posta adresi oluşturur.

Örnek istek

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

Örnek cevap

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}

Bir testin durumunu ve sonuçlarını getirir. Durum: pending → processing → completed (veya expired / error). Puan 0–10 arasındadır.

Parametreler

testIdstringzorunlu
/test/generate tarafından döndürülen test kimliği

Örnek istek

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

Örnek cevap

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

Daha önce alınmış bir e‑posta üzerinde, yenisini göndermeden tüm kontrolleri yeniden çalıştırır.

Parametreler

testIdstringzorunlu
/test/generate tarafından döndürülen test kimliği

Örnek cevap

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

Geliştirici gelen kutusu

Her hesabın kendine ait tek kullanımlık bir adresi vardır ([email protected], herhangi bir +etiketle). Bu adrese gönderilen postalar 24 saat saklanır ve API üzerinden, panelde veya bir paylaşım bağlantısıyla okunabilir. Uçtan uca testlerde gerçek bir posta kutusu yerine bunu kullanın.

GET/inbox/wait

Eşleşen bir ileti gelene kadar bekler (long-poll, en fazla 60 sn) ve iletiyi metin, HTML, bağlantılar ve tek kullanımlık kodlarla birlikte döndürür. Zamanında hiçbir şey gelmezse 408 döndürür.

Parametreler

tagstring
Yalnızca dev-xxxxxx+{tag}@… adresine gönderilen postalar
timeoutnumber
Beklenecek saniye, 1-60 (varsayılan 30)
sinceISO 8601
Yalnızca bu zamandan sonra alınan postalar (varsayılan: şimdi)

Örnek istek

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"

Ayrıca mevcut:

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

Örnek cevap

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}

Bir yapay zekâ ajanından kullanın (MCP)

Aynı gelen kutusu bir MCP sunucusudur; böylece Claude Code, Cursor ve diğer MCP istemcileri kendi başlarına adres oluşturabilir, posta bekleyebilir ve postaları okuyabilir:

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

Araçlar: new_address, wait_for_message, list_messages, get_message, extract, share_link, delete_message.

HTTP Durum Kodları

KodDurumAçıklama
200OKİstek başarılı
400Bad RequestEksik veya geçersiz parametre
401UnauthorizedAPI anahtarı eksik, geçersiz veya iptal edilmiş
404Not FoundTest bulunamadı
429Too Many RequestsOran sınırı aşıldı (dakikada 60 veya günde 1.000)
500Internal Server ErrorSunucu tarafı hata

Hata Cevapları

Hata durumunda cevapta hata açıklamasını içeren bir error alanı bulunur:

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

Kod Örnekleri

JavaScript / Node.js

javascript
1// MX kayıtlarını sorgula
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 kayıtları:', data.records);
10  console.log('SPF:', data.hasSpf ? data.spfRecord : 'Yok');
11  console.log('DMARC:', data.hasDmarc ? data.dmarcRecord : 'Yok');
12}

Python

python
1import os
2import requests
3
4# Kara liste kontrolü
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"Kontrol edilen: {data['totalChecked']} liste")
13print(f"Listede: {data['totalListed']} adet")
14
15for result in data['results']:
16    if result['listed']:
17        print(f"⚠️  {result['name']}: LİSTEDE")

Python - Reputation Check

python
1import os
2import requests
3
4# Alan adı itibarı kontrolü
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("\nFaktörler:")
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# Tam teslim edilebilirlik testi
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 kontrolü
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']} (öncelik: {$mx['priority']})\n";
15    }
16}
17?>

API’yi denemek ister misiniz?

Araçlarımızı web arayüzünden deneyin veya API ile geliştirmeye başlayın.