الإرسال عبر SMTP
الإرسال نفسه الذي يجريه POST /emails، للبرامج التي تتحدث SMTP.
الاتصال
كل ما يرسل البريد عبر خادم SMTP يستطيع الإرسال عبر OpenEmail: مرسِل البريد في إطار عمل، أو CMS، أو أداة مراقبة، أو طابعة. سجّل الدخول باسم المستخدم openemail ومفتاح API بوصفه كلمة المرور. يحتاج المفتاح إلى الصلاحية emails:send، والرسالة التي يقدّمها هي الإرسال نفسه الذي يجريه POST /emails بذلك المفتاح.
| الإعداد | القيمة |
|---|---|
| المضيف | smtp.openemail.uk |
| المنفذ | 465 مع SSL/TLS، أو 587 مع STARTTLS |
| اسم المستخدم | openemail |
| كلمة المرور | مفتاح API يحمل الصلاحية emails:send |
| تسجيل الدخول | PLAIN أو LOGIN، وهو ما تسمّيه أغلب البرامج كلمة مرور عادية |
لا يُقبل شيء دون تشفير، وعلى المنفذ 587 لا يُفتح تسجيل الدخول إلا بعد STARTTLS. ومفتاح API يسجّل الدخول للإرسال فقط. أما قراءة صندوق بريد عبر IMAP أو POP3 فتتطلب كلمة مرور تطبيق.
إرسال رسالة اختبار
احفظ رسالة باسم message.eml وقدّمها عبر curl. ويجب أن يكون From عنوانًا يحق للمفتاح الإرسال باسمه.
From: Acme <[email protected]>To: [email protected]Subject: Hello over SMTPMessage-ID: <[email protected]> It works.curl --url "smtps://smtp.openemail.uk:465" \ --user "openemail:$OPENEMAIL_API_KEY" \ --mail-from "[email protected]" \ --mail-rcpt "[email protected]" \ --upload-file message.eml --crlfcurl --ssl-reqd --url "smtp://smtp.openemail.uk:587" \ --user "openemail:$OPENEMAIL_API_KEY" \ --mail-from "[email protected]" \ --mail-rcpt "[email protected]" \ --upload-file message.eml --crlfالجواب على رسالة مقبولة هو 250 2.0.0 OK queued as متبوعًا بمعرّفها. وهذا المعرّف هو الذي يأخذه GET /emails/{id}، فتُقرأ الرسالة وأحداثها وتتبعها كما في أي إرسال آخر.
كيف تتحول الرسالة إلى إرسال
تُقرأ الرسالة وتُرسَل عبر الطريق نفسه الذي يسلكه إرسال REST، فيُعاد بناؤها من أجزائها ولا تُمرَّر بايتًا ببايت.
| في الرسالة | في الإرسال |
|---|---|
| From | from. وهو مطلوب، وهو المرسِل الذي يُفحَص المفتاح في مقابله. أما العنوان في MAIL FROM فيكفي أن يكون موجودًا. |
| RCPT TO | من تُسلَّم إليهم الرسالة، 50 على الأكثر. المستلِم المذكور في To هو to، والمذكور في Cc هو cc، ومن لم يُذكر في أيٍّ منهما هو bcc. ويجب أن يكون واحد على الأقل في To. |
| Reply-To | replyTo، العنوان الأول. |
| Subject | subject. |
| جزء النص وجزء HTML | text وhtml. الصورة التي يستخدمها HTML بصيغة cid: تُدمج حيث تظهر. |
| المرفقات | attachments: 20 ملفًا على الأكثر و5 MB إجمالًا. |
| ترويسات أخرى | تبقى X-* وList-* وPrecedence وAuto-Submitted وImportance وPriority وFeedback-ID. وتُستبعَد كل ترويسة أخرى. |
| X-OpenEmail-Stream | stream: transactional أو broadcast. وتُزال الترويسة قبل خروج الرسالة. |
ما يسري
كل ما يُلزَم به إرسال REST يسري هنا أيضًا، لأنه طريق واحد.
- صلاحيات المفتاح، والعناوين والنطاقات المقيَّد بها.
- فحص المرسِل:
Fromعنوان على نطاق يستطيع الإرسال، وعنوان يحق للمفتاح الإرسال باسمه. - حصة الإرسال لمساحة العمل وقائمة المنع الخاصة بها.
- التوقيع وتتبع الفتح والنقر للعنوان الذي تُرسَل منه، كما في إرسال REST لا يضبط
signatureولاtracking. - المسار: ما دام مسار الرسائل الجماعية موقوفًا، تُرفض الرسالة التي تحمل
X-OpenEmail-Stream: broadcast. - خطافات الويب وأحداث التسليم، وهي تسمّي الرسالة بالمعرّف الوارد في الرد
250.
إعادات المحاولة
الرسالة التي تحمل Message-ID تُرسَل مرة واحدة. وتقديم Message-ID نفسه للمستلِمين أنفسهم مرة أخرى يُجاب عنه بمعرّف الرسالة الأولى ولا يُرسَل شيء، فلا يستطيع البرنامج الذي يعيد المحاولة بعد انقطاع الاتصال أن يرسلها مرتين. والرسالة نفسها لمستلِمين آخرين إرسال آخر. انظر عدم التكرار.
الردود والحدود
| الرد | متى |
|---|---|
| 250 2.0.0 | وُضعت الرسالة في الطابور، ويليها معرّفها. |
| 535 5.7.8 | فشل تسجيل الدخول: مفتاح خاطئ أو مُبطَل أو منتهي الصلاحية، أو مفتاح بلا emails:send، أو مفتاح API تحت اسم مستخدم آخر. |
| 452 4.5.3 | أكثر من 50 مستلِمًا في رسالة واحدة. ويرسل برنامج البريد البقية في رسالة أخرى من تلقاء نفسه. |
| 552 5.3.4 | الرسالة أكبر من 25 MB. |
| 550 5.6.0 | لا يمكن إرسال الرسالة كما كُتبت: لا يوجد From، أو لا أحد في To، أو المرفقات كثيرة جدًا أو كبيرة جدًا، أو المسار غير معروف. ويبيّن النص أيّها. |
| 550 5.7.1 | رُفض الإرسال: لا يحق للمفتاح الإرسال باسم ذلك العنوان، أو النطاق لا يستطيع الإرسال بعد، أو مسار الرسائل الجماعية موقوف. |
| 452 4.7.0 | استُنفدت حصة الإرسال لمساحة العمل. |
| 451 4.7.1 | أكثر من 300 رسالة من مفتاح واحد في دقيقة. ينتظر برنامج البريد ثم يعيد المحاولة. |
| 451 4.3.0 | خلل من جهتنا. أعد المحاولة بعد قليل. |
يُغلق الاتصال الذي ليس لديه ما يرسله بعد خمس دقائق. ويمكن أن يحمل اتصال واحد أي عدد من الرسائل، واحدة تلو الأخرى.
في سجل الطلبات
كل رسالة يقدّمها مفتاح هي سطر في سجل طلباته، بالطريقة SMTP والمسار /emails والحالة التي كان سيحملها إرسال REST: 202 حين توضع في الطابور، و403 أو 422 أو 429 مع code الخطأ نفسه حين تُرفض. يسرد GET /keys/{id}/requests?path=/emails هذه السطور بجانب إرسالات REST. وتسجيل الدخول الذي يفشل بمفتاح حقيقي يظهر في نشاط ذلك المفتاح.