الانتقال من Mailgun
احتفظ بـ SDK من Mailgun وأرسل عبر OpenEmail. غيّر عنوان URL الأساسي والمفتاح، وتبقى شيفرة الإرسال لديك كما هي.
ما الذي تغيّره
وجّه الـ SDK إلى https://api.openemail.uk/compat/mailgun وأعطه بدلاً من مفتاح Mailgun مفتاح API من OpenEmail يحمل الإذن emails:send. ينتقل المفتاح بوصفه كلمة مرور لتسجيل الدخول نفسه عبر HTTP Basic، ولا يُتحقق من اسم المستخدم. يجب أن يكون النطاق في المسار أحد نطاقات مساحة العمل، ويقرر عنوان From إن كان يجوز للرسالة أن تخرج، كما في كل مكان في OpenEmail.
import formData from 'form-data'import Mailgun from 'mailgun.js' const mailgun = new Mailgun(formData)const mg = mailgun.client({ username: 'api', key: process.env.OPENEMAIL_API_KEY, url: 'https://api.openemail.uk/compat/mailgun',}) await mg.messages.create('acme.com', { from: 'Acme Billing <[email protected]>', to: ['[email protected]'], subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})في Ruby، الوسيط الثاني هو المضيف والمسار دون مخطط. وفي PHP، لا يحتفظ الـ SDK إلا بمضيف نقطة النهاية التي يُعطاها، لذا يدخل المسار عبر AddPathPlugin من php-http، الذي يثبّته الـ SDK أصلاً. وقد تسجّل حزمة Python الرسمية تحذيراً بأن المضيف ليس لـ Mailgun، ثم ترسل على أي حال. وهي تعيد أيضاً محاولة الطلب الذي فشل بـ 429 أو بخطأ 5xx، لذا يجيب OpenEmail بـ 400 بدل 5xx بمجرد خروج جزء من الدفعة.
ما الذي يقابل ماذا
نقطة النهاية المخدومة هي POST /v3/{domain}/messages، بصيغة multipart/form-data التي تحتاجها المرفقات، أو بصيغة application/x-www-form-urlencoded. واسم الحقل الذي ينتهي بـ [] يُقرأ دونها.
| Mailgun | في OpenEmail |
|---|---|
| from | المرسل مع اسمه. |
| to | مستلمون مكررون أو تفصل بينهم فواصل. ومع cc وbcc حتى 50 لكل رسالة. |
| subject | الموضوع. |
| html | جزء HTML. يصبح text الجزء النصي، وأحدهما، أو template، مطلوب. |
| attachment | ملفات، 20 على الأكثر و5 ميغابايت إجمالاً. |
| inline | الصورة التي يستخدمها HTML بصيغة cid: مع اسم ملفها تُدمج حيث تظهر. وأي ملف مضمّن آخر يصل مرفقاً عادياً. |
| o:tag | وسوم باسم tag وtag_2 وهكذا، يحمل كلٌّ منها وسماً واحداً. |
| v: | يصبح كل متغير وسماً باسمه وقيمته. ومع o:tag بحد أقصى 10 لكل رسالة. |
| o:deliverytime | إرسال مجدول حتى سنة مقدماً. والوقت الذي مضى يرسل فوراً. |
| o:tracking | يشغّل مع o:tracking-clicks وo:tracking-opens التتبع للرسالة أو يوقفه. وتُحسب htmlonly تشغيلاً. |
| o:testmode | تسجّل yes الرسالة مرسلةً دون تسليمها، كما يفعل مفتاح oe_test_. |
| h:Reply-To | عنوان الرد. وكل حقل h: آخر يصبح ترويسة مخصصة: X-* وList-* وPrecedence وAuto-Submitted وImportance وPriority وFeedback-ID. |
| recipient-variables | إرسال دفعي. يتلقى كل عنوان في to رسالته الخاصة، يُملأ فيها %recipient.key% من متغيراته و%recipient% بعنوانه، وتُضاف cc وbcc إلى كل واحدة. والعنصر النائب الذي لا قيمة له يبقى كما هو. |
| template | الـ slug أو المعرّف (tpl_...) لقالب من OpenEmail، تُملأ قيمه من t:variables، وإلا فمن h:X-Mailgun-Variables. ويختار t:version إصداراً برقمه. |
ما الذي يُرفض، ولماذا
templateمعhtmlأوtext، لأن قالب OpenEmail يوفر المتن كله، وt:versionليس رقم إصدار.o:deliverytime-optimize-periodوo:time-zone-localize، لأن OpenEmail لا يختار وقت إرسال لكل مستلم. وترويساتh:X-Mailgun-الأخرى، وهي تعليمات موجهة إلى Mailgun: استخدم خيارo:المقابل بدلاً منها.amp-htmlوحده. وإلى جانبhtmlأوtextيُترك جانباً، لأنهما يحملان الرسالة أصلاً.- أكثر من عنوان رد واحد، وأكثر من 10 وسوم، واسم وسم فيه غير الحروف والأرقام و
_و-، ودفعة فيها أكثر من 100 مستلم. يقبل Mailgun حتى 1000، فقسّم الدفعات الأكبر.
تُقبل o:dkim وo:require-tls وo:skip-verification وo:sending-ip وo:sending-ip-pool وo:tracking-pixel-location-top وo:archive-to وo:deliver-within وt:text ولا تغيّر شيئاً.
الردود والأخطاء
- يجيب الإرسال بـ 200 مع الرسالة
Queued. Thank you.وid: معرّف رسالة OpenEmail بين قوسين زاويين، يستخدمهGET /emails/{id}وخطافات الويب من دونهما. ويُنشئ الإرسال الدفعي رسالة لكل مستلم، لكل منها معرّفها، ويجيب بالأولى. وتعمل ترويسةIdempotency-Keyكما في بقية الـ API. - المفتاح المفقود أو المجهول يحصل على 401 مع النص العادي
Forbidden، والنطاق الذي لا تملكه مساحة العمل يحصل على 404 معDomain not found. وكل ما سوى ذلك يعود فيmessage: 400 لرسالة لا يمكن إرسالها، و403 لمفتاح بلاemails:sendأو لعنوان From لا يجوز للمفتاح استخدامه أو لنطاق لا يستطيع الإرسال بعد أو لمساحة عمل استنفدت حصة الإرسال، و413 لمتن يتجاوز 25 ميغابايت أو مرفقات تتجاوز 5 ميغابايت. - حين يفشل مستلم في دفعة بعد قبول غيره، يذكر الخطأ الرسائل التي أُرسلت بالفعل ويجيب بـ 400، كي لا ترسلها مرتين حزمة SDK تعيد المحاولة.