Geliştiriciler: REST API ve MCP

Hızlı başlangıç

• https://dash.reply2mail.app adresinde oturum aç, Entegrasyonlar’ı aç ve bir API anahtarı oluştur. İzinlerini seç (Yalnız okuma, Okuma ve düzenleme ya da Tam) ve anahtarı kopyala: r2m_pat_ ile başlar ve bir kez gösterilir.
• Bir ortam değişkenine koy; asla bir URL’ye ya da paylaştığın koda koyma:

export R2M_TOKEN=PASTE_YOUR_KEY_HERE

Okunmamış postalarını listele:

curl -H "Authorization: Bearer $R2M_TOKEN" "https://api.reply2mail.app/v1/messages?unread=true&limit=5"

Birini yanıtla. Onay açıkken (varsayılan) cevap, bir onay isteğiyle birlikte 202 Accepted olur; yanıt ancak sen panelde onayladıktan sonra gönderilir:

curl -X POST -H "Authorization: Bearer $R2M_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{"body": "Thanks, received."}' \
  "https://api.reply2mail.app/v1/messages/MESSAGE_ID/reply"

import os, uuid, requests

BASE = "https://api.reply2mail.app/v1"
H = {"Authorization": f"Bearer {os.environ['R2M_TOKEN']}"}

msgs = requests.get(f"{BASE}/messages", params={"q": "invoice", "since": "2026-10-01"},
                    headers=H, timeout=30).json()["result"].get("messages", [])
if msgs:
    r = requests.post(f"{BASE}/messages/{msgs[0]['id']}/archive", json={},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    print(r.status_code, r.json()["status"])   # 202 pending_approval: approval is on by default

Her uç nokta, parametre ve örnek: REST API referansı →

MCP mi REST mi?

• MCP (anahtarla https://api.reply2mail.app/mcp, claude.ai ve ChatGPT için girişle https://mcp.reply2mail.app/mcp): yapay zeka ajanları için. Ajan araçları kendisi keşfeder ve çağırır. Kurulum Ajan API’si sayfasında.
• REST (https://api.reply2mail.app/v1): kendi betiklerin, arka uçların ve otomasyonların için. Sıradan kaynaklar, HTTP durum kodları, imleçler, idempotency anahtarları ve bir OpenAPI belgesi.
• İkisi de aynı geçitten geçer: MCP üzerinden posta gönderemeyen bir anahtar REST üzerinden de gönderemez.

Uç noktalar

Mesaj kimlikleri opaktır (m1_…): bir sonucun döndürdüğü gibi aynen kullan. Her rotanın, istek gövdesinin ve parametrenin tam şeması OpenAPI belgesinde: https://api.reply2mail.app/v1/openapi.json

Şemalar, örnek cevaplar ve hata kodlarıyla REST API referansı →

Kimlik doğrulama

• Her istekte Authorization: Bearer r2m_pat_…, yalnız api.reply2mail.app üzerinde. URL’deki anahtar reddedilir ve iptal edilir, çünkü URL’ler kayıtlara düşer.
• Yalnız sunucudan sunucuya: API CORS başlığı göndermez, bu yüzden bir tarayıcı sayfası onu çağıramaz. Anahtarı sunucunda tut.
• Bir anahtar yalnız onu oluşturan kullanıcının posta kutusuna erişir. Kendi izinlerini değiştiremez ve kendi isteklerini asla onaylayamaz.
• Anahtarların süresi dolar (varsayılan 90 gün, en çok 180). Anahtarı panelden yenile; eskisi 24 saat daha çalışır.

Cevaplar ve onaylar

Her rota, MCP araçlarıyla aynı JSON zarfıyla cevap verir:

{
  "status": "pending_approval",
  "executed": false,
  "approval": {
    "id": "apr_…",
    "state": "pending",
    "tool": "send_reply",
    "action": "reply",
    "created_at": "2026-10-08T10:00:00Z",
    "expires_at": "2026-10-09T10:00:00Z"
  },
  "approvals_url": "https://dash.reply2mail.app/approvals",
  "poll_after_s": 30,
  "message": "…"
}

• Onaylama ve reddetme yalnız reply2mail panelinde yapılır. reply2mail asla bir e-postadaki ya da API cevabındaki bir bağlantıyla onay istemez.
• Karar verilmeyen bir istek 24 saat sonra düşer. Aynı istek iki kez gönderilirse mevcut istek döner; reddedilen aynı istek bir saat boyunca kabul edilmez.
• outcome_unknown, işlemin olmuş da olmamış da olabileceği anlamına gelir: yeniden deneme; Gönderilenler klasörüne bak.
• Bu anahtar ve rotanın grubu için onayı kapattıysan (ücretli planlar, Ajan API’si sayfasında Onaysız çalıştırma), istek hemen çalışabilir. İlk kez yazılan bir alıcıda, gönderim sınırının üstünde veya güvenlik filtresi durdurduğunda yine onay isteğine (202) dönüşür.
• Posta içeriği (gönderenler, konular, gövdeler, ek metni) üçüncü taraf verisidir. Sonuçlar bunu untrusted_fields ve ayraç satırlarıyla işaretler; asla talimat olarak kabul etme.

Sayfalama ve idempotency

• Listeler limit (1–50, varsayılan 20) ve bir imleçle sayfalanır: result.has_more true ise, diğer parametreleri değiştirmeden result.next_cursor değerini cursor olarak gönder.
• POST, PATCH ve DELETE bir Idempotency-Key başlığı kabul eder (1–255 görünür ASCII karakter). Aynı anahtar ve aynı istekle yeniden denemek, saklanan cevabı Idempotent-Replayed: true ile 24 saat boyunca döndürür. Aynı anahtar farklı bir istekle 422 idempotency_key_reused; ilk istek hâlâ çalışırken 409 idempotency_in_progress olur. Yalnız başarılı (2xx) cevaplar saklanır; başarısız bir çağrı aynı anahtarla yeniden denenebilir.
• Anahtarlar senin API anahtarına bağlıdır: başka hiç kimsenin anahtarı seninkiyle çakışamaz.

Sınırlar

Her cevap, dakikalık sınır için RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset ve RateLimit-Policy ile X-Request-Id taşır (destekle iletişimde bunu yaz). 429 veya 503 cevabı Retry-After taşır.

Hatalar

{
  "status": "error",
  "code": "not_permitted",
  "message": "This credential is not permitted to use this tool. …",
  "details": {
    "group": "mail:reply"
  }
}

Tüm hata kodları ve HTTP durumları →

Webhook’lar

Sürekli sorgulamak yerine reply2mail, imzalı olayları HTTPS uç noktana POST edebilir. Panelde Entegrasyonlar → Webhook’lar altından kur; her uç nokta tek bir API anahtarına aittir (ücretsiz planda 1, ücretli planlarda 10 uç nokta).

• message.received: bağlı bir hesabın Gelen Kutusu’na yeni posta geldi (anahtarda Postaları okuma izni gerekir). approval.decided: anahtarın açtığı bir onay isteği onaylandı, reddedildi, çalıştırıldı, başarısız oldu veya outcome_unknown ile bitti. webhook.test: test olayı gönderme düğmesi.
• Yükler yalnız kimlik taşır; konu, gönderen veya gövde asla gönderilmez: içeriği GET /v1/messages/{id} ya da GET /v1/approvals/{id} ile al.
• Her istek imzalıdır: Reply2mail-Signature: t=<unix saniye>,v1=<t + "." + ham gövdenin HMAC-SHA256 hex değeri>. JSON’u ayrıştırmadan önce doğrula, t saatinden 300 saniyeden fazla sapıyorsa isteği reddet ve Reply2mail-Event-Id ile tekrarları ayıkla: olaylar birden fazla kez ve sırasız gelebilir.
• 10 saniye içinde 2xx ile cevap ver. Başarısız teslimatlar yaklaşık 23 saate yayılan en fazla 6 denemeyle tekrarlanır.
• curl, Node ve Python ile imza doğrulama, tüm başlıklar, yeniden denemeler ve otomatik kapanma: /tr/docs/agent-api#webhooks. OpenAPI belgesi olayları webhooks bölümünde listeler.

Olay yükleri ve imza doğrulama, referansta →

Sürümleme

• Ana sürüm yoldadır (/v1). v1 içinde değişiklikler yalnız eklemelidir: yeni rotalar, yeni isteğe bağlı parametreler, yeni sonuç alanları. Bilmediğin alanları yok say.
• Bir rota ya da alan, OpenAPI belgesinde ve bu sayfada en az 90 gün önceden duyurulmadan kaldırılmaz. Güvenlik için bir rota her an hemen çalışmaktan onay beklemeye geçebilir.
• Bir isteğin sonucunu öğrenmek için approval.decided webhook’unu kullan ya da GET /v1/approvals/{id} ile sorgula.