الانتقال من Postmark
احتفظ بمكتبة Postmark وأرسل عبر OpenEmail. غيّر المضيف ورمز الخادم، وتبقى شيفرة الإرسال لديك كما هي.
ما الذي تغيّره
وجّه المكتبة إلى https://api.openemail.uk/compat/postmark وضع في مكان رمز الخادم مفتاح API من OpenEmail يحمل الإذن emails:send. ينتقل المفتاح في الترويسة نفسها X-Postmark-Server-Token. تبقى استدعاءاتك التي ترسل البريد كما هي، ويقرر عنوان From إن كان يجوز للرسالة أن تخرج، كما في كل مكان في OpenEmail.
import { ServerClient } from 'postmark' const client = new ServerClient(process.env.OPENEMAIL_API_KEY, { requestHost: 'api.openemail.uk/compat/postmark',}) await client.sendEmail({ From: '[email protected]', To: '[email protected]', Subject: 'Your invoice', HtmlBody: '<p>Your invoice is attached.</p>', MessageStream: 'outbound',})في Node، يجمع requestHost المضيف والمسار معاً، دون مخطط ودون شرطة مائلة في آخره. وفي Ruby، يحتاج path_prefix إلى شرطة مائلة في طرفيه. وفي Python، استخدم الحزمة الرسمية postmark-python مع base_url. أما الحزمة المجتمعية postmarker فلا تستطيع بلوغ مسار تحت مضيف، لذا لا تعمل هنا. وفي PHP، يأخذ PostmarkClient::$BASE_URL المخطط والمضيف والمسار دون شرطة مائلة في آخره. وهو ثابت (static)، لذا ينطبق على كل عميل Postmark في العملية، بما فيه PostmarkAdminClient.
ما الذي يقابل ماذا
نقاط النهاية المخدومة هي POST /email و/email/batch و/email/withTemplate و/email/batchWithTemplates. تتطابق أسماء الحقول بأي حالة أحرف، كما في Postmark، والسلسلة الفارغة تُعد غير موجودة.
| Postmark | في OpenEmail |
|---|---|
| From | المرسل مع اسمه. |
| To | مستلمون تفصل بينهم فواصل. ومع Cc وBcc حتى 50 لكل رسالة. |
| ReplyTo | عنوان رد واحد. |
| Subject | الموضوع. |
| HtmlBody | جزء HTML. يصبح TextBody الجزء النصي، وأحدهما مطلوب. |
| Headers | ترويسات مخصصة تُعطى بـ Name وValue: X-* وList-* وReply-To وPrecedence وAuto-Submitted وImportance وPriority وFeedback-ID. |
| Attachments | ملفات، 20 على الأكثر و5 ميغابايت إجمالاً. الصورة التي يستخدم HTML معرّفها ContentID بصيغة cid: تُدمج حيث تظهر. وأي ملف آخر يصل مرفقاً عادياً. |
| Tag | وسم باسم tag. |
| Metadata | وسوم بالأسماء والقيم نفسها. ومع Tag بحد أقصى 10 لكل رسالة. |
| TrackOpens | يشغّل تتبّع الفتح للرسالة أو يوقفه. |
| TrackLinks | يشغّل HtmlAndText وHtmlOnly تتبّع النقر، ويوقفه None. |
| MessageStream | outbound، أو معرّف أي تدفق معاملات آخر، يرسل الرسالة كالمعتاد. |
| TemplateAlias | الـ slug أو المعرّف (tpl_...) لقالب من OpenEmail، تُملأ قيمه من TemplateModel. ويُقبل InlineCss ولا يغيّر شيئاً. |
ما الذي يُرفض، ولماذا
TemplateId، مع ErrorCode 1101. لا يعني معرّف قالب Postmark شيئاً هنا، فأعد إنشاء القالب في OpenEmail وأرسل الـ slug أو المعرّف الخاص به فيTemplateAlias.- تدفق
broadcast، مع ErrorCode 1236. ترسل نقاط النهاية هذه بريد المعاملات، أما النشرات فتخرج كبثّ من OpenEmail. SubjectأوHtmlBodyأوTextBodyفي رسالة بقالب، مع ErrorCode 1123، لأن القالب يوفرها. وTrackLinksبالقيمةTextOnly، لأن OpenEmail يتتبع الروابط في جزء HTML.- أكثر من عنوان رد واحد، وترويسة مكررة أو خارج القائمة أعلاه، وأكثر من 10 وسوم، واسم وسم أو اسم في
Metadataفيه غير الحروف والأرقام و_و-. - دفعة فيها أكثر من 100 رسالة، مع ErrorCode 410. يقبل Postmark حتى 500، فقسّم الدفعات الأكبر.
الردود والأخطاء
- يجيب الإرسال بـ 200 مع
ToوSubmittedAtوMessageIDوErrorCodeبقيمة 0 وMessageبقيمة OK. وMessageIDهو معرّف رسالة OpenEmail الذي يستخدمهGET /emails/{id}وخطافات الويب. وتعمل ترويسةIdempotency-Keyكما في بقية الـ API. - تجيب الدفعة بـ 200 مع نتيجة واحدة لكل رسالة بالترتيب نفسه. والرسالة التي فشلت لا تحمل إلا
ErrorCodeوMessageالخاصين بها، وتخرج البقية على أي حال. - تعود الأخطاء في
ErrorCodeوMessage. المفتاح المفقود أو المجهول، أو الذي لا يملكemails:send، يحصل على HTTP 401 مع ErrorCode 10. ويحصل الباقي على HTTP 422: ErrorCode 300 للرسالة نفسها، و400 لعنوان From لا يجوز للمفتاح استخدامه، و401 لنطاق لا يستطيع الإرسال بعد، و402 لمتن ليس JSON، و405 لمساحة عمل استنفدت حصة الإرسال. ويعني HTTP 413 أن المتن يتجاوز 10 ميغابايت، أو 50 ميغابايت في الدفعة، أو أن المرفقات تتجاوز 5 ميغابايت.