واجهة برمجة البريد الإلكتروني للمعاملات
استدعاء REST واحد لكل رسالة يرسلها منتجك
أرسل الإيصالات وإعادة تعيين كلمات المرور والتنبيهات وإشعارات الحساب عبر POST /v1/transactional/send. تتحقق MailLand من الطلب، وتوقّع كل رسالة بمفتاح DKIM الخاص بنطاقك، وتسلّمها إلى خوادم البريد لديها، ثم تُبلغك بما حدث لها. تعمل الخوادم لدى Hetzner في ألمانيا.
curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: ml_pet_..." \
-H "X-Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "Your App" },
"to": [{ "email": "[email protected]", "name": "Jane" }],
"subject": "Your receipt for order 1042",
"htmlContent": "<p>Thanks, Jane. Your payment was received.</p>",
"textContent": "Thanks, Jane. Your payment was received.",
"tags": ["receipt"]
}'ما الذي يحدث بعد استدعاء الواجهة
أربع مراحل، تظهر كل منها لك في الاستجابة أو سجل الرسائل أو عبر webhook.
التحقق
تتحقق الواجهة من نطاق المرسل، ومن نطاق صلاحيات مفتاحك وحدوده، ومن كل مستلم. تُرفض العناوين المدرجة في قائمة منع الإرسال وتُذكر في rejectedRecipients؛ وعند تفعيل الحماية من الأخطاء الإملائية والنطاقات المؤقتة، تُذكر هذه العناوين أيضًا، مع اقتراح تصحيح للخطأ الإملائي.
في قائمة الانتظار
تُكتب كل رسالة مقبولة في قاعدة بيانات MailLand قبل أن تردّ الواجهة بـ 202 Accepted، ثم تُسلَّم إلى قائمة انتظار التسليم. تحمل الاستجابة معرّف المهمة ومعرّف رسالة لكل مستلم ووقت إدراجها في قائمة الانتظار؛ أما الإرسال المجدول فيعيد معرّف جدولة بدلًا من ذلك.
التوقيع والإرسال
يتلقى كل مستلم نسخة منفصلة بمعرّف رسالة خاص بها ومن دون Cc ظاهر، موقّعة بمفتاح DKIM الخاص بنطاقك ومرسلة من عناوين IP المشتركة التي ترسل منها MailLand.
الإبلاغ
تصل أحداث التسليم والتأجيل والارتداد والفشل والشكوى إلى webhook الخاص بك وإلى سجل الرسائل. يحمل كل حدث رقم إصدار للحالة، حتى تتمكن من تطبيق الأحداث بالترتيب الصحيح.
ما تقدمه لك الواجهة
كل ميزة هنا حقل أو ترويسة أو نقطة نهاية، موثّقة بأمثلة.
قوالب مخزنة بمتغيرات
احتفظ بقوالب HTML والنص في MailLand واملأ {{placeholders}} لكل مستلم. إذا لم تكن لمتغير قيمة، فلن تُرسل الرسالة وفيها العنصر النائب الخام: تردّ الواجهة بـ 422 وتسمّي القيمة الناقصة.
مفاتيح idempotency
أرسل ترويسة X-Idempotency-Key مع طلب الإرسال. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة الأصلية ولا ترسل شيئًا، فلا تؤدي إعادة المحاولة بعد انقطاع الشبكة إلى إرسال نسخة أخرى.
الإرسال المجدول
أضف scheduledAt لجدولة الإرسال حتى 7 أيام مقدمًا. يمكنك عرض الرسالة المجدولة أو تغيير موعدها أو إلغاؤها عبر الواجهة قبل إرسالها.
المرفقات والصور المضمّنة
أرفق حتى 10 ملفات و10 MiB لكل رسالة، بما في ذلك الصور المضمّنة التي يشير إليها HTML الخاص بك عبر Content-ID.
الوسوم والترويسات المخصصة
ضع وسومًا على الرسائل لتصفيتها في التحليلات والسجلات وwebhooks، وأضف ترويساتك الخاصة، وحدد عنوان reply-to لكل رسالة.
فحص ما قبل الإرسال
تخبرك GET /v1/transactional/send/check إن كان حسابك قادرًا على الإرسال الآن، مع الاستهلاك الحالي لحد المعدل والحصة الشهرية. ولا يفحص مرسلًا أو مستلمًا بعينه.
مفاتيح sandbox
يقبل مفتاح sandbox الطلبات ويسجلها دون تسليمها، أو يسلّم فقط إلى قائمة سماح تتحكم فيها، فلا تصل رسائل الاختبار إلا إلى العناوين التي تختارها.
مفاتيح بصلاحيات قابلة للتحديد
اقصر كل مفتاح على مسار واحد، أو على نطاقات إرسال مختارة، أو على قائمة سماح لعناوين IP، أو على حدود بالدقيقة والساعة واليوم، أو على تاريخ انتهاء. وبدّله من لوحة التحكم أو عبر الواجهة.
اعرف ما حدث لكل رسالة
قبول الطلب ليس سوى نصف المهمة. تخبرك MailLand بما جرى بعده.
Webhooks موقّعة
اشترك في أحداث التسليم والتأجيل والارتداد والفشل والشكوى. كل طلب موقّع بـ HMAC-SHA256 في ترويسة X-MLND-Signature، وتُعاد محاولته عندما تفشل نقطة النهاية لديك.
سجل الرسائل
ابحث عن أي رسالة بمعرّفها واطّلع على كل حدث في تاريخها. تُحفظ السجلات 30 أو 90 أو 180 يومًا بحسب خطتك.
منع الإرسال تلقائيًا
يُضاف الارتداد الدائم والشكاوى إلى قائمة منع الإرسال لديك تلقائيًا، وتُرفض عمليات الإرسال اللاحقة إلى تلك العناوين قبل خروجها.
إصدار v1 لا يتغير إلا بالإضافة
الإصدار 1 من الواجهة يقبل الإضافة فقط: قد تظهر حقول وأحداث جديدة، لكن لا يُحذف شيء ولا يتغير معنى شيء. أي تغيير غير متوافق يصدر بوصفه /v2، ويُعلن عنه قبل 180 يومًا على الأقل، ويستمر /v1 في العمل إلى جانبه مدة 180 يومًا.
HTTPS عادي، بأي لغة
لا توفّر MailLand أي SDK حتى الآن. الواجهة JSON عبر HTTPS مع ترويسة X-API-Key، والوثائق المتاحة بسبع لغات تعرض كل طلب بـ curl وJavaScript وNode.js وPython وPHP وC# وJava وGo.
مستضافة في الاتحاد الأوروبي
تعمل خوادم MailLand لدى Hetzner في ألمانيا، أساسًا في نورنبرغ، وتُحفظ نسخة احتياطية مشفرة في وارسو ببولندا. قد يعالج عدد قليل من المعالجين الفرعيين، مثل Cloudflare وStripe، بيانات محدودة خارج الاتحاد الأوروبي بموجب البنود التعاقدية القياسية للاتحاد الأوروبي. وتسرد اتفاقية معالجة البيانات (DPA) كلًّا منهم.
اقرأ اتفاقية معالجة البياناتأسئلة حول واجهة برمجة البريد الإلكتروني للمعاملات
هل توجد خطة مجانية؟
نعم. تشمل خطة Free 1,000 رسالة شهريًا دون أي تكلفة، مع واجهة REST ومرحّل SMTP نفسيهما المتوفرين في الخطط المدفوعة. لا حاجة إلى بطاقة ائتمان للبدء.
هل لديكم SDK؟
ليس بعد. الواجهة JSON عبر HTTPS، لذا يعمل معها أي عميل HTTP. وتضم الوثائق أمثلة جاهزة للنسخ بـ curl وJavaScript وNode.js وPython وPHP وC# وJava وGo.
كيف أتأكد أن إعادة المحاولة لا ترسل الرسالة مرتين؟
أرسل ترويسة X-Idempotency-Key (أو الحقل idempotencyKey) مع POST /v1/transactional/send أو send-batch. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة الأصلية ولا ترسل شيئًا. وهاتان النقطتان هما الوحيدتان اللتان تقبلان المفتاح.
هل يمكن أن يذهب طلب واحد إلى مستلمين كثيرين؟
يقبل طلب المعاملات حتى 5 مستلمين، ويتلقى كل منهم نسخة منفصلة. وللإرسال الجماعي، استخدم مفتاح تسويق مع POST /v1/transactional/send-batch، الذي يقبل حتى 10,000 مستلم في الطلب الواحد.
ماذا يحدث عند ارتداد رسالة؟
يضيف الارتداد الدائم أو الشكوى العنوان إلى قائمة منع الإرسال لديك، ويُرسل إلى webhook الخاص بك بوصفه حدثًا. وتُرفض عمليات الإرسال اللاحقة إلى ذلك العنوان وتُذكر في rejectedRecipients.
ما حدود الإرسال؟
تحدد كل خطة حجمًا شهريًا ومعدل إرسال بالدقيقة، كما يظهر في صفحة الأسعار. ويمكن أن يحمل المفتاح حدودًا أدنى خاصة به. عند تجاوز حد ما، تردّ الواجهة بـ 429 مع ترويسة Retry-After.
أرسل أول رسالة لك اليوم
أنشئ حسابًا مجانيًا، وتحقق من نطاقك، واستدعِ الواجهة. 1,000 رسالة شهريًا مجانًا.