بوابة SMTP

تقبل بوابة SMTP إرسال البريد القياسي وتعيد توجيه كل رسالة إلى Notify في Messaging API v2 كبريد إلكتروني للمعاملات. استخدمها عندما يكون توصيل أداة بريد موجودة — مثل MTA أو mailer لإطار عمل أو SDK — أسهل من إرسال طلب JSON إلى API.

ملاحظة

البوابة مخصصة للمعاملات فقط. بالنسبة لشرائح الجمهور أو الجدولة أو حملات A/B، استدعِ Notify مباشرة.

كيف تعمل

   any SMTP client          smtp gateway              Messaging API v2
   ──────────────── ──────> ──────────────── ──────> ─────────────────
       submission            STARTTLS                gRPC Notify
       AUTH PLAIN            + AUTH PLAIN            Authorization: Token

1. يتصل العميل بـ smtp.pushwoosh.com على المنفذ 587، ويقوم بترقية الاتصال إلى TLS باستخدام STARTTLS، ثم يصادق باستخدام AUTH PLAIN.
2. تقوم البوابة بتحليل رسالة MIME وإنشاء طلب Notify مع platforms: ["EMAIL"] و message_type: TRANSACTIONAL.
3. يتم إعادة توجيه رمز API من AUTH PLAIN إلى Messaging API كترويسة Authorization. يتم التحقق من صحة الرمز، ومطابقة التطبيق، وهوية الإرسال، ومعالجة الارتداد كلها على جانب API.

نقطة النهاية

الإعداد	القيمة
المضيف	smtp.pushwoosh.com
المنفذ	587 (إرسال SMTP)
TLS	STARTTLS — إلزامي قبل AUTH
المصادقة	AUTH PLAIN

المصادقة

يستخدم AUTH PLAIN اثنين من بيانات اعتماد Pushwoosh.

حقل AUTH	قيمة Pushwoosh
username	رمز التطبيق، على سبيل المثال XXXXX-XXXXX
password	رمز API للخادم

يتم رفض AUTH خارج TLS. لا يظهر الرمز أبدًا في الرسالة — يتم استخدامه فقط لتفويض استدعاء Notify المصدر.

كيفية تعيين الرسائل إلى Notify

حقل MIME أو SMTP	حقل Notify
RCPT TO	target.users.list — يقوم Pushwoosh بحل هذه العناوين إلى مشتركين
AUTH username	application
ترويسة Subject:	email_payload.subject["default"] (مفكوك ترميز RFC 2047)
ترويسة From:	email_payload.from — name و email
جزء HTML	email_payload.body (يفضل عند وجود كلا الجزأين)
جزء النص العادي	email_payload.body (يستخدم عند غياب HTML)
MAIL FROM	يتم تجاهله — يستبدل Pushwoosh هوية الإرسال الخاصة به ويتعامل مع الارتدادات بنفسه

يتم إرسال كل رسالة مع schedule.send_date: now.

الحدود

الحد	القيمة
الحد الأقصى لحجم الرسالة	25 ميبيبايت
الحد الأقصى للمستلمين لكل مغلف (RCPT TO)	50

تعيين الأخطاء

تتم ترجمة رموز حالة gRPC التي يعيدها Messaging API إلى رموز رد SMTP القياسية بحيث يظهر أي عميل SMTP خطأ ذا معنى.

حالة gRPC المصدر	رد SMTP	المعنى
Unauthenticated	535 5.7.8	رمز تطبيق أو رمز API غير صالح.
PermissionDenied	550 5.7.1	الرمز لا يملك صلاحيات لهذا التطبيق.
InvalidArgument / FailedPrecondition / OutOfRange	550 5.6.0	محتوى MIME غير صالح (على سبيل المثال، الموضوع أو النص مفقود).
NotFound	550 5.1.1	لم يتم العثور على التطبيق أو المستلم.
ResourceExhausted	452 4.5.3	تم الوصول إلى حد المعدل — حاول مرة أخرى لاحقًا.
DeadlineExceeded / Unavailable	451 4.4.1	خطأ عابر في المصدر — حاول مرة أخرى لاحقًا.
أي فشل آخر	451 4.5.0	خطأ داخلي عابر — حاول مرة أخرى لاحقًا.

الرموز في نطاق 4xx مؤقتة ويجب على العميل إعادة المحاولة؛ الرموز في نطاق 5xx دائمة وتتطلب إصلاحًا من جانب العميل.

مثال: الإرسال باستخدام swaks

swaks --server smtp.pushwoosh.com:587 \
      --auth-user "XXXXX-XXXXX" \
      --auth-password "YOUR_API_TOKEN" \
      --tls \
      --from from@example.com \
      --to user@example.com \
      --header "Subject: Hello from SMTP gateway" \
      --body "Plain-text body"

ترويسة From: في نص MIME هي التي تصل إلى Pushwoosh — يتم تجاهل مغلف --from (MAIL FROM).

ملاحظات

• البوابة عديمة الحالة ولا تخزن الرسائل. بمجرد إعادة توجيهها، يصبح التسليم مسؤولية Messaging API.
• تتم معالجة الارتدادات والشكاوى وروابط إلغاء الاشتراك بواسطة Pushwoosh، تمامًا مثل أي بريد إلكتروني آخر للمعاملات.
• لإرسال الحملات (الشرائح، الجدولة، A/B)، استخدم Notify مباشرة — بوابة SMTP مخصصة للإرسال فقط.

انظر أيضًا

نظرة عامة على Messaging API v2

Notify

مرجع حمولة البريد الإلكتروني

التسويق مقابل المعاملات