واجهة الإصدار v1

مرجع واجهة API.

المصادقة ونطاقات المطورين والصناديق والرسائل وWebhooks والأخطاء وأمثلة SDK.

المصادقة: Authorization: Bearer md_test_…. احفظ المفتاح في مدير أسرار. المفتاح الكامل يظهر مرة واحدة فقط.

توثيق API الكامل

الرابط الأساسي: https://api.maildrop.online/v1

المجال	الاستخدام
`inboxes:read`	عرض الصناديق
`inboxes:write`	إنشاء وحذف الصناديق
`messages:read`	عرض الرسائل والرموز
`webhooks:write`	إدارة نقاط Webhook

GET/accountأي مفتاح API صالح

إرجاع المؤسسة والاشتراك النشط والصلاحيات.

curl -X GET "https://api.maildrop.online/v1/account" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/account", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/account",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/account"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/limitsusage:read

إرجاع حدود الخطة الفعلية والتعديلات الخاصة بالحساب.

curl -X GET "https://api.maildrop.online/v1/limits" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/limits", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/limits",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/limits"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/usageusage:read

إرجاع استخدام الشهر الحالي.

curl -X GET "https://api.maildrop.online/v1/usage" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/usage"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/domainsinboxes:read

اعرض نطاقات صناديق المطورين المتاحة للخطة النشطة.

curl -X GET "https://api.maildrop.online/v1/domains" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/domains", { headers: { Authorization: `Bearer ${process.env.MAILDROP_API_KEY}` } });
console.log(await response.json());

import os, requests
response = requests.get("https://api.maildrop.online/v1/domains", headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"}, timeout=20)
response.raise_for_status()
print(response.json())

using var domains = await client.ListDomainsAsync();
Console.WriteLine(domains.RootElement);

GET/inboxes?limit=100inboxes:read

عرض صناديق البريد الخاصة بالمساحة.

curl -X GET "https://api.maildrop.online/v1/inboxes?limit=100" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes?limit=100", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/inboxes?limit=100",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/inboxes?limit=100"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST/inboxesinboxes:write

إنشاء صندوق خاص. استخدم Idempotency-Key لإعادة المحاولة بأمان.

curl -X POST "https://api.maildrop.online/v1/inboxes" \
  -H "Authorization: Bearer $MAILDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-001" \
  -d '{"local":"checkout-qa","domain":"tests.maildrop.online","lifetime_hours":24}'

const response = await fetch("https://api.maildrop.online/v1/inboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",\n    "Idempotency-Key": crypto.randomUUID()
  },\n  body: JSON.stringify({"local":"checkout-qa","domain":"tests.maildrop.online","lifetime_hours":24})
});
console.log(await response.json());

import os, requests
response = requests.request(
    "POST",
    "https://api.maildrop.online/v1/inboxes",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    json={"local":"checkout-qa","domain":"tests.maildrop.online","lifetime_hours":24},
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.PostAsJsonAsync("https://api.maildrop.online/v1/inboxes", new { local = "checkout-qa", domain = "tests.maildrop.online", lifetime_hours = 24 });
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/inboxes/{inbox_id}inboxes:read

عرض صندوق بريد خاص واحد.

curl -X GET "https://api.maildrop.online/v1/inboxes/123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes/123", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/inboxes/123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/inboxes/123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE/inboxes/{inbox_id}inboxes:write

حذف منطقي لصندوق بريد خاص.

curl -X DELETE "https://api.maildrop.online/v1/inboxes/123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes/123", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "DELETE",
    "https://api.maildrop.online/v1/inboxes/123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Delete, "https://api.maildrop.online/v1/inboxes/123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/inboxes/{inbox_id}/messages?limit=100&after_id=0messages:read

عرض الرسائل وملخصات رموز التحقق.

curl -X GET "https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/messages/{message_id}messages:read

عرض الرسالة الكاملة وبيانات رمز التحقق.

curl -X GET "https://api.maildrop.online/v1/messages/456" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/messages/456", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/messages/456",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/messages/456"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE/messages/{message_id}messages:delete

حذف منطقي لرسالة واحدة.

curl -X DELETE "https://api.maildrop.online/v1/messages/456" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/messages/456", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "DELETE",
    "https://api.maildrop.online/v1/messages/456",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Delete, "https://api.maildrop.online/v1/messages/456"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/messages/{message_id}/attachmentsattachments:read

عرض بيانات المرفقات. تنزيل الملفات يحتاج إلى R2.

curl -X GET "https://api.maildrop.online/v1/messages/456/attachments" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/messages/456/attachments", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/messages/456/attachments",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/messages/456/attachments"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/webhookswebhooks:read

عرض نقاط Webhook الموقعة.

curl -X GET "https://api.maildrop.online/v1/webhooks" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/webhooks"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST/webhookswebhooks:write

إنشاء نقطة Webhook ويظهر سر التوقيع مرة واحدة.

curl -X POST "https://api.maildrop.online/v1/webhooks" \
  -H "Authorization: Bearer $MAILDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-001" \
  -d '{"name":"CI receiver","url":"https://example.com/maildrop-events","events":["message.received"]}'

const response = await fetch("https://api.maildrop.online/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",\n    "Idempotency-Key": crypto.randomUUID()
  },\n  body: JSON.stringify({"name":"CI receiver","url":"https://example.com/maildrop-events","events":["message.received"]})
});
console.log(await response.json());

import os, requests
response = requests.request(
    "POST",
    "https://api.maildrop.online/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    json={"name":"CI receiver","url":"https://example.com/maildrop-events","events":["message.received"]},
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Post, "https://api.maildrop.online/v1/webhooks"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

PATCH/webhooks/{webhook_id}webhooks:write

تحديث الرابط والأحداث والاسم أو الحالة.

curl -X PATCH "https://api.maildrop.online/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks/wh_123", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "PATCH",
    "https://api.maildrop.online/v1/webhooks/wh_123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Patch, "https://api.maildrop.online/v1/webhooks/wh_123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE/webhooks/{webhook_id}webhooks:write

حذف نقطة Webhook.

curl -X DELETE "https://api.maildrop.online/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks/wh_123", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "DELETE",
    "https://api.maildrop.online/v1/webhooks/wh_123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Delete, "https://api.maildrop.online/v1/webhooks/wh_123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST/webhooks/{webhook_id}/testwebhooks:write

إرسال حدث اختبار موقع.

curl -X POST "https://api.maildrop.online/v1/webhooks/wh_123/test" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks/wh_123/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "POST",
    "https://api.maildrop.online/v1/webhooks/wh_123/test",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Post, "https://api.maildrop.online/v1/webhooks/wh_123/test"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

الأخطاء المنظمة

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Missing messages:read scope.",
    "request_id": "cf-ray-or-uuid",
    "details": {}
  }
}

الأكواد الأساسية: 400 و401 و403 و404 و409 و429 و500.

التحقق من توقيع Webhook

كوّن HMAC-SHA256 من الطابع الزمني ونقطة ثم جسم الطلب الخام.

signed = timestamp + "." + raw_request_body
signature = HMAC_SHA256(signing_secret, signed)
X-MailDrop-Signature: t=TIMESTAMP,v1=HEX_SIGNATURE

إدارة الفريق والصلاحيات

تتيح واجهة الفريق للمالك والمسؤول دعوة الأعضاء، وضبط الأدوار، ونمط الموارد، والصلاحيات وحدود كل عضو. لا يمكن لحدود العضو تجاوز حدود الخطة.

GET/teamteam:read

POST/team/invitationsteam:write

PATCH/team/members/{user_id}team:write

{
  "action": "policy",
  "role": "developer",
  "resource_mode": "shared",
  "permissions": { "inboxes.shared.read": true, "api_keys.create": true },
  "limits": { "max_active_inboxes": 10, "max_api_keys": 2 }
}