الانتقال من SendGrid
احتفظ بـ SDK من SendGrid وأرسل عبر OpenEmail. غيّر عنوان URL الأساسي والمفتاح، وتبقى شيفرة الإرسال لديك كما هي.
ما الذي تغيّره
وجّه الـ SDK إلى https://api.openemail.uk/compat/sendgrid وأعطه بدلاً من مفتاح SendGrid مفتاح API من OpenEmail يحمل الإذن emails:send. ينتقل المفتاح في الترويسة نفسها Authorization: Bearer. تبقى استدعاءاتك التي ترسل البريد كما هي، ويقرر عنوان From إن كان يجوز للرسالة أن تخرج، كما في كل مكان في OpenEmail.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})في Node، اضبط المفتاح على العميل أولاً، ثم عنوان URL الأساسي، ثم سلّم العميل إلى حزمة البريد. لا تستدعِ sgMail.setApiKey بعد ذلك، لأنها تعيد عنوان URL الأساسي إلى SendGrid. ينبّه الـ SDK إلى أن المفتاح لا يبدأ بـ SG.، وهذا لا يضر. في Python وRuby وPHP، اكتب المضيف دون شرطة مائلة في آخره.
ما الذي يقابل ماذا
نقطة النهاية المخدومة هي POST /v3/mail/send. يصبح كل عنصر في personalizations رسالة مستقلة من OpenEmail بمعرّف خاص بها، لذا يرسل الطلب الواحد 100 رسالة على الأكثر.
| SendGrid | في OpenEmail |
|---|---|
| from | المرسل مع اسمه. يمكن لكل تخصيص أن يحدد from خاصاً به. |
| personalizations | رسالة لكل تخصيص. تتسع to وcc وbcc فيه لـ 50 مستلماً معاً، وتنطبق subject وheaders وcustom_args وsend_at وsubstitutions الخاصة به على تلك الرسالة وحدها. |
| subject | الموضوع، ما لم يضع التخصيص موضوعاً خاصاً به. |
| content | يصبح text/plain الجزء النصي وtext/html جزء HTML. يُترك text/x-amp-html جانباً، لأن جزء HTML يحمل الرسالة أصلاً. |
| attachments | ملفات، 20 على الأكثر و5 ميغابايت إجمالاً. الصورة المضمّنة التي يستخدم HTML معرّفها content_id بصيغة cid: تُدمج حيث تظهر. وأي ملف مضمّن آخر يصل مرفقاً عادياً. |
| reply_to | عنوان الرد. يعمل reply_to_list أيضاً ما دام يحمل عنواناً واحداً. |
| headers | ترويسات مخصصة: X-* وList-* وReply-To وPrecedence وAuto-Submitted وImportance وPriority وFeedback-ID. ويضيف التخصيص ترويساته الخاصة. |
| categories | وسوم باسم category وcategory_2 وهكذا، يحمل كلٌّ منها فئة واحدة. |
| custom_args | وسوم بالأسماء والقيم نفسها. وتتقدم قيم التخصيص. |
| send_at | إرسال مجدول حتى سنة مقدماً. والوقت الذي مضى يرسل فوراً. |
| substitutions | يُستبدل كل مفتاح بقيمته في الموضوع والجزء النصي وجزء HTML لتلك الرسالة. |
| template_id | معرّف (tpl_...) أو slug قالب من OpenEmail، تُملأ قيمه من dynamic_template_data. |
| tracking_settings | يشغّل open_tracking.enable وclick_tracking.enable تتبّع الفتح والنقر للرسالة أو يوقفانه. |
| mail_settings | يفحص sandbox_mode.enable الطلب والمرسل والقالب، ثم يجيب بـ 200 دون إرسال شيء. |
تحمل الرسالة 10 وسوم على الأكثر، بحساب الفئات وcustom_args معاً. والطلب الذي يحتاج أكثر يُرفض بدل أن يُقتطع، فلا يضيع شيء مما أرسلته دون إشعار.
ما الذي يُرفض، ولماذا
- معرّف قالب من SendGrid في
template_id، مثلd-…. تبقى القوالب في SendGrid، فأعد إنشاء القالب في OpenEmail وأرسل معرّفه أو الـ slug الخاص به. contentإلى جانبtemplate_id، لأن قالب OpenEmail يوفر المتن كله. وsubstitutionsمع قالب للسبب نفسه: مرّر القيم فيdynamic_template_data.- أكثر من عنوان رد واحد، و
reply_toوreply_to_listمعاً، وأنواع المحتوى غير النص وHTML. أرسل دعوة التقويم مرفقاً بصيغة.ics. - تشغيل
mail_settings.footer، وsections، لأن OpenEmail لا يكتب نصاً في رسالتك. - أكثر من 10 وسوم، واسم وسم فيه غير الحروف والأرقام و
_و-، وترويسة خارج القائمة أعلاه، وأكثر من 100 تخصيص في طلب واحد.
تُقبل asm وbatch_id وip_pool_name وإعدادات التجاوز في mail_settings وsubscription_tracking وganalytics وclick_tracking.enable_text وopen_tracking.substitution_tag ولا تغيّر شيئاً. وتُتخطى العناوين الموجودة في قائمة الحظر لمساحة العمل دائماً، أياً كان ما يقوله إعداد التجاوز.
الردود والأخطاء
- يجيب الإرسال بـ 202 بمتن فارغ وبمعرّف رسالة OpenEmail في
X-Message-Id، وهو المعرّف الذي يستخدمهGET /emails/{id}وخطافات الويب. ومع عدة تخصيصات يحمل معرّف الرسالة الأولى. وتعمل ترويسةIdempotency-Keyكما في بقية الـ API. - تعود الأخطاء في
errors، وهي قائمة منmessageوfieldوhelp: 400 لطلب لا يمكن إرساله، و401 لمفتاح مفقود أو مجهول، و403 لمفتاح بلاemails:sendأو لعنوان From لا يجوز للمفتاح استخدامه أو لا يستطيع نطاقه الإرسال بعد، و413 لمتن يتجاوز 30 ميغابايت أو مرفقات تتجاوز 5 ميغابايت، و429 حين تستنفد مساحة العمل حصة الإرسال. - حين يفشل تخصيص بعد قبول ما قبله، يذكر الخطأ الرسائل التي أُرسلت بالفعل، كي تتركها إعادة المحاولة جانباً.