# بوابة SMTP

تقبل بوابة SMTP إرسال البريد القياسي وتعيد توجيه كل رسالة إلى [`Notify` في Messaging API v2](/ar/developer/api-reference/messaging-api-v2/notify/) كبريد إلكتروني للمعاملات. استخدمها عندما يكون توصيل أداة بريد موجودة — مثل MTA أو mailer لإطار عمل أو SDK — أسهل من إرسال طلب JSON إلى API.

<Aside type="note">
البوابة مخصصة للمعاملات فقط. بالنسبة لشرائح الجمهور أو الجدولة أو حملات A/B، استدعِ [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/) مباشرة.
</Aside>

## كيف تعمل

```
   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.

## نقطة النهاية

| الإعداد <div style="width:140px"></div> | القيمة <div style="width:340px"></div> |
|---------|-------|
| المضيف    | `smtp.pushwoosh.com` |
| المنفذ    | `587` (إرسال SMTP) |
| TLS     | `STARTTLS` — إلزامي قبل `AUTH` |
| المصادقة    | `AUTH PLAIN` |

## المصادقة

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

| حقل AUTH <div style="width:120px"></div> | قيمة Pushwoosh |
|------------|-----------------|
| `username` | [رمز التطبيق](/ar/developer/api-reference/api-identifiers/#application-code)، على سبيل المثال `XXXXX-XXXXX` |
| `password` | [رمز API للخادم](/ar/developer/api-reference/api-access-token/#server-api-token) |

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

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

| حقل MIME أو SMTP <div style="width:200px"></div> | حقل 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`.

## الحدود

| الحد <div style="width:280px"></div> | القيمة |
|-------|-------|
| الحد الأقصى لحجم الرسالة       | 25 ميبيبايت |
| الحد الأقصى للمستلمين لكل مغلف (`RCPT TO`) | 50 |

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

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

| حالة gRPC المصدر <div style="width:280px"></div> | رد SMTP <div style="width:120px"></div> | المعنى |
|----------------------|------------|---------|
| `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

```bash
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`](/ar/developer/api-reference/messaging-api-v2/notify/) مباشرة — بوابة SMTP مخصصة للإرسال فقط.

## انظر أيضًا

<CardGrid>
  <LinkCard title="نظرة عامة على Messaging API v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="مرجع حمولة البريد الإلكتروني" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="التسويق مقابل المعاملات" href="/product/messaging-channels/marketing-vs-transactional/" />
</CardGrid>