REST API

أرسل رسائل البريد الإلكتروني التحويلية عبر POST /v1/transactional/send. هذه هي الطريقة الأساسية لإرسال البريد الإلكتروني من خلال MailLand.

المصادقةنسخ رابط القسم

أدرج مفتاح API الخاص بك في رأس X-API-Key:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

يجب أن تحتوي بيانات الاعتماد على قناة Api مُفعَّلة وأن تكون بيانات اعتماد منتج Sending.

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

POST https://api.mail.land/v1/transactional/send

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

نص الطلبنسخ رابط القسم

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

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

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

يتطلب كل مرفق ثلاثة حقول:

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

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

الحالة: 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

المستلمون المرفوضوننسخ رابط القسم

يمكن رفض المستلمين لعدة أسباب:

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

أسباب الرفض الشائعة:

• Suppressed: العنوان موجود في قائمة القمع (ارتدادات أو شكاوى سابقة)
• disposable_domain: تم اكتشاف مزود بريد إلكتروني مؤقت
• domain_typo: خطأ مطبعي محتمل في النطاق (يتضمن حقل suggestion)

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

تحقق من قدرتك على الإرسال قبل تقديم الطلب الفعلي:

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

إذا كان canSend يساوي false، يوضح حقل reason السبب (حد المعدل أو الحصة أو حالة الحساب وما إلى ذلك).

قابلية التكرار (Idempotency)نسخ رابط القسم

إعادة محاولة الإرسال بعد انتهاء مهلة الشبكة يجب ألا تُسلّم البريد مرتين. عند تمرير مفتاح تكرار، تُعيد المحاولة الاستجابة الأصلية بدلاً من الإرسال من جديد.

أرسل المفتاح كترويسة (مستحسن):

X-Idempotency-Key: order-12345-shipped-v1

أو استخدم الحقل idempotencyKey في الجسم. كلاهما مقبول، ويمكن إرسالهما معاً فقط إذا تطابقت القيمتان.

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

• النطاق. تُقبل X-Idempotency-Key على POST /v1/transactional/send وPOST /v1/transactional/send-batch فقط، ولا تقرأها أي نقطة نهاية أخرى.
• الصيغة. من 1 إلى 255 محرفاً: حروف وأرقام و_ و-. تُقارن المفاتيح تماماً دون اقتطاع أو توحيد لحالة الأحرف.
• النافذة. يبقى المفتاح قابلاً للتكرار 24 ساعة، وبعدها يُعامل المفتاح نفسه كطلب جديد.
• التكرار. إعادة المحاولة ضمن النافذة تُعيد الاستجابة الأصلية حرفياً، الأرقام نفسها والحالة نفسها، ولا تُرسل شيئاً.
• التفرّد. المفاتيح فريدة لكل حساب. إعادة استخدام مفتاح لنقطة نهاية مختلفة تُرفض بالرمز 409؛ استخدم مفتاحاً مستقلاً لكل عملية.

معرّف الارتباطنسخ رابط القسم

تتبع الطلبات عبر الأنظمة بتضمين معرّف ارتباط:

X-Correlation-ID: my-app-order-12345

أو

X-Request-ID: my-app-order-12345

يظهر معرّف الارتباط في السجلات وسجل النشاط.

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

تتضمن الاستجابات الناجحة معلومات حد المعدل لكل عنوان IP:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

عند تطبيق محرك سياسة الإرسال لحد المعدل (429)، يشير رأس Retry-After إلى ثواني الانتظار:

Retry-After: 30

يمكن أن يتضمن الطلب التعاملي ما يصل إلى 5 مستلمين، ويُحتسب كل منهم ضمن حدود المعدل لديك. إذا تجاوز ذلك حدّك في الثانية (مثلًا 1 في الثانية في خطة بمعدل 60 في الدقيقة)، يُقبل الطلب عندما لا يكون أي طلب آخر قد قُبل في الثانية نفسها؛ وإلا فإنه يتلقى 429 مع Retry-After: 1 وينجح عند إعادة المحاولة في الثانية التالية، ضمن حدّك في الدقيقة. انظر حدود المعدل.

تتضمن استجابة 429 على مستوى IP أيضاً X-RateLimit-Reset كوقت UTC بصيغة ISO-8601.

استجابات الأخطاءنسخ رابط القسم

تُرجع جميع الأخطاء نصاً بتنسيق JSON:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

رموز الأخطاءنسخ رابط القسم

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

تفرض بيانات الاعتماد التحويلية حداً أقصى قدره 5 مستلمين لكل طلب إرسال. هذا يمنع إساءة استخدام تدفقات التحويلية للإرسال الجماعي. إذا كنت تحتاج إلى مستلمين أكثر، استخدم بيانات اعتماد التسويق مع الإرسال الجماعي.

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

بدلاً من HTML المضمَّن، أشر إلى قالب مخزَّن:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

يأتي subject من القالب. عند تكرار المفاتيح، تفوز قيمة to[].variables الخاصة بالمستلم على variables العامة، نفس قاعدة المحتوى المضمَّن. راجع القوالب لإنشاء القوالب وإدارتها.

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

• الإرسال الجماعي: الإرسال إلى مستلمين متعددين دفعة واحدة
• مرحّل SMTP: الإرسال عبر SMTP بدلاً من REST
• القوالب: إنشاء قوالب بريد إلكتروني قابلة لإعادة الاستخدام
• رسائل البريد الإلكتروني المجدولة: جدولة رسائل البريد الإلكتروني للتسليم المستقبلي