مفاتيح API

تُصادق مفاتيح API (بيانات الاعتماد) تطبيقك مع واجهة برمجة تطبيقات MailLand. يكون كل مفتاح محدداً بالمنتج والوضع والتدفق والقناة، وبشكل اختياري مقيداً بالنطاق وعنوان IP.

في لوحة التحكم، أنشئ المفاتيح وأدِرها من Credentials في الشريط الجانبي (قسم Global). تتوفر العمليات نفسها عبر واجهة /v1/credentials الموضحة أدناه.

تستخدم أمثلة Authorization: Bearer في هذه الصفحة رمز الوصول JWT الذي يعيده POST /v1/auth/login (راجع Login). مفاتيح API مختلفة: أرسلها في الترويسة X-API-Key وليس كرمز Bearer.

تنسيق المفتاحنسخ رابط القسم

تتبع جميع مفاتيح API في MailLand هذا التنسيق:

ml_{mode}{product}{stream?}_{random45chars}

• ml_: البادئة لجميع المفاتيح
• الوضع: p (Production) أو s (Sandbox)
• المنتج: e (Sending)، i (Inbound)، v (Validation)
• التدفق (Sending فقط): t (Transactional) أو m (Marketing)
• ٤٥ حرفاً عشوائياً

أمثلة:

ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...  → Production Sending Transactional
ml_sem_Xn7Kp2qR4tW9yB1cD6eF...  → Sandbox Sending Marketing
ml_pi_Mn5Jp8kL3rV6wA2xC4fG...   → Production Inbound
ml_pv_Qw9Er3tY6uI1oP5aS8dF...   → Production Validation

خصائص بيانات الاعتمادنسخ رابط القسم

عند إنشاء بيانات اعتماد، تقوم بتكوين ما يلي:

channels سلسلة نصية واحدة وليست مصفوفة أبداً. أرسل "channels": "Api, Smtp" للسماح بالقناتين؛ يُرفض ["Api", "Smtp"] برمز 400.

إنشاء بيانات اعتمادنسخ رابط القسم

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Transactional",
    "product": "Sending",
    "mode": "Production",
    "stream": "Transactional",
    "channels": "Api",
    "scope": "AllDomains",
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000
  }'

{
  "id": "n4k9pq2rt8mwxa",
  "name": "Production Transactional",
  "key": "ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...",
  "keyPrefix": "ml_pet_Ab3Kx9mN",
  "product": "sending",
  "mode": "production",
  "stream": "transactional",
  "channels": "api",
  "scope": "allDomains",
  "sandboxBehavior": "logOnly",
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "isActive": true,
  "createdAt": "2026-02-17T10:00:00Z"
}

النطاق: قيود النطاقنسخ رابط القسم

بشكل افتراضي، يمكن لبيانات الاعتماد الإرسال من أي نطاق موثق في مساحة العمل الخاصة بك (AllDomains). لتقييد بيانات الاعتماد بنطاقات محددة:

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing - notifications.com only",
    "product": "Sending",
    "mode": "Production",
    "stream": "Marketing",
    "channels": "Api",
    "scope": "SelectedDomains",
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

يمكنك أيضاً تحديث تعيينات النطاق بعد الإنشاء:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

قيود IPنسخ رابط القسم

قيّد بيانات الاعتماد بعناوين IP أو نطاقات CIDR محددة:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/allowed-ips \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      { "ipAddress": "203.0.113.10", "description": "Production server" },
      { "ipAddress": "198.51.100.0/24", "description": "Office network" }
    ]
  }'

عند تكوين قيود IP، تُعيد طلبات API من عناوين IP غير المدرجة 403 IP_NOT_ALLOWED.

تكوين القنواتنسخ رابط القسم

يتحكم حقل channels في مكان مصادقة بيانات الاعتماد:

لاستخدام بيانات الاعتماد لـ SMTP relay، تأكد من تضمين Smtp في القنوات. عند المصادقة عبر SMTP، استخدم أي اسم مستخدم ومفتاح API ككلمة مرور.

تدوير المفاتيحنسخ رابط القسم

قم بتدوير مفتاح API لبيانات الاعتماد دون توقف باستخدام فترة سماح:

curl -X POST https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 24
  }'

{
  "key": "ml_pet_Yn8Lq3rS5uW0zA4bC7dE...",
  "oldKeyExpiresAt": "2026-02-18T10:00:00Z"
}

خلال فترة السماح (الافتراضية 24 ساعة)، يكون كل من المفتاح القديم والجديد صالحَين. بعد انتهاء فترة السماح، يتوقف المفتاح القديم عن العمل.

وضع Sandboxنسخ رابط القسم

كلمة «Sandbox» تعني شيئين منفصلين يجتمعان:

1. بيانات اعتماد Sandbox (mode: Sandbox). للتطوير وCI/CD والتجريب. يعتمد مصير الإرسال على قيمة sandboxBehavior لبيانات الاعتماد:

• LogOnly (الافتراضي): يُتحقق من الطلب ويُجاب بـ 202، لكن لا يُسلَّم شيء ولا تُنشأ رسالة. تتضمن الاستجابة isSandboxed: true وsandboxReason: "credential_sandbox_mode" وmessageIds فارغة.
• AllowListOnly: المستلمون المطابقون لـقائمة السماح الخاصة بـ Sandbox في مساحة عملك يستلمون الرسالة فعلاً؛ أما البقية فتُعاد في rejectedRecipients بالسبب recipient_not_in_sandbox_allowlist. وإذا لم يكن أي مستلم مسموحاً، تبقى الاستجابة 202 مع acceptedRecipients: [] وsandboxReason: "all_recipients_not_in_sandbox_allowlist".

عبر SMTP لا تُسلّم بيانات اعتماد Sandbox أبداً: تُقبل الرسالة وتُسجَّل دون إرسال، أياً كانت قيمة sandboxBehavior.

2. مساحات عمل Sandbox. تبدأ مساحة العمل الجديدة بمستوى التحقق Sandbox (انظر مساحات العمل). إلى أن يتم التحقق منها، يقتصر الإرسال على مستلمي قائمة السماح حتى مع بيانات اعتماد Production. يُرفض أي مستلم آخر بـ 429 SENDING_BLOCKED («Recipient '…' is not in sandbox allowlist. Add to allowlist or complete verification.»).

أدِر قائمة السماح من لوحة التحكم عبر الإعدادات ← Sandbox Allow List. الإدخال عنوان ([email protected]) أو نطاق كامل (*@example.com). القائمة نفسها متاحة عبر GET /v1/account/settings/sandbox-allowlist, POST /v1/account/settings/sandbox-allowlist, DELETE /v1/account/settings/sandbox-allowlist/{email} (رمز bearer الخاص بلوحة التحكم؛ يقبل POST الحقل email وdescription اختيارياً).

إدارة بيانات الاعتمادنسخ رابط القسم

سرد بيانات الاعتمادنسخ رابط القسم

curl "https://api.mail.land/v1/credentials?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

التصفية حسب المنتج أو الوضع:

curl "https://api.mail.land/v1/credentials?product=Sending&mode=Production" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تحديث بيانات اعتمادنسخ رابط القسم

curl -X PATCH https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "rateLimitPerHour": 10000,
    "isActive": false
  }'

جميع الحقول اختيارية: أدرج فقط ما تريد تغييره.

حذف بيانات اعتمادنسخ رابط القسم

curl -X DELETE https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تُعيد 204 No Content عند النجاح. تتوقف بيانات الاعتماد المحذوفة فوراً عن المصادقة. يؤدي الحذف إلى إلغاء المفتاح: تبقى بيانات الاعتماد ظاهرة في GET /v1/credentials مع isActive: false.

حدود المعدلنسخ رابط القسم

لكل بيانات اعتماد حدود معدلها المستقلة عن بيانات الاعتماد الأخرى:

عند تجاوز حد المعدل، تُعيد API 429 مع ترويسات X-RateLimit-*:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708171800
Retry-After: 45

الخطوات التاليةنسخ رابط القسم

• البدء السريع: أرسل أول بريد إلكتروني
• REST API: مرجع API الإرسال الكامل
• SMTP Relay: المصادقة بمفتاح API عبر SMTP