# واجهة برمجة تطبيقات البريد الإلكتروني (Email API)

import { Badge } from '@astrojs/starlight/components';

<Aside type="caution" title="تم إيقاف /createEmailMessage">
يجب أن تستخدم عمليات التكامل الجديدة [Messaging API v2](/ar/developer/api-reference/messaging-api-v2/) — مرر `platforms: ["EMAIL"]` وكتلة [`email_payload`](/ar/developer/api-reference/messaging-api-v2/email-payload-reference/) إلى `Notify`. راجع [دليل الترحيل](/ar/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createemailmessage).
</Aside>

## createEmailMessage <Badge text="مهمل" variant="caution" size="small" />

تنشئ رسالة بريد إلكتروني.

`POST` `https://api.pushwoosh.com/json/1.3/createEmailMessage`

### معلمات جسم الطلب

| الاسم | النوع <div style="width:80px"></div> | مطلوب | الوصف |
|------|--------|:--------:|-------------|
| auth | `string` | نعم | [رمز الوصول إلى API](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| application | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| notifications | `array` | نعم | مصفوفة JSON تحتوي على تفاصيل رسالة البريد الإلكتروني. انظر جدول **معلمات الإشعارات** أدناه. |

#### معلمات الإشعارات

| الاسم  | النوع <div style="width:50px"></div> | مطلوب | الوصف |
|------|------|:--------:|-------------|
| send_date | `string` | نعم | يحدد متى يتم إرسال البريد الإلكتروني. التنسيق: `YYYY-MM-DD HH:mm` أو `"now"`. |
| preset | `string` | نعم | [رمز الإعداد المسبق للبريد الإلكتروني](/ar/developer/api-reference/api-identifiers/#email-content-code). انسخه من شريط عنوان URL في **محرر محتوى البريد الإلكتروني** في لوحة تحكم Pushwoosh. |
| subject | `string` or `object` | لا | سطر موضوع البريد الإلكتروني. سيكون البريد الإلكتروني دائمًا بلغة المحتوى. إذا لم يحتوي `subject` على لغة مطابقة لـ `content`، فسيكون الموضوع فارغًا. |
| content | `string` or `object` | لا | محتوى جسم البريد الإلكتروني. يمكن أن يكون سلسلة نصية لمحتوى HTML عادي أو كائنًا للإصدارات المترجمة. |
| attachments | `array` | لا | مرفقات البريد الإلكتروني. يتوفر مرفقان فقط. يجب ألا يتجاوز كل مرفق 1 ميجابايت (بترميز base64). |
| list_unsubscribe | `string` | لا | يسمح بتعيين عنوان URL مخصص لترويسة "Link-Unsubscribe". |
| campaign | `string` | لا | [رمز الحملة](/ar/developer/api-reference/api-identifiers/#campaign-code) لربط البريد الإلكتروني بحملة معينة. |
| ignore_user_timezone | `boolean` | لا | إذا كانت القيمة `true`، يتم إرسال البريد الإلكتروني فورًا، مع تجاهل المناطق الزمنية للمستخدم. |
| timezone | `string` | لا | يرسل البريد الإلكتروني وفقًا للمنطقة الزمنية للمستخدم. مثال: `"America/New_York"`. |
| filter | `string` | لا | يرسل البريد الإلكتروني إلى المستخدمين الذين يطابقون [شرط فلتر معين](/ar/developer/api-reference/api-identifiers/#segment--filter-name). |
| devices | `array` | لا | قائمة بعناوين البريد الإلكتروني (بحد أقصى 1000) لإرسال رسائل بريد إلكتروني مستهدفة. إذا تم استخدامها، يتم إرسال الرسالة فقط إلى هذه العناوين. يتم تجاهلها إذا تم استخدام مجموعة التطبيقات. |
| use_auto_registration | `boolean` | لا | إذا كانت القيمة `true`، يتم تسجيل رسائل البريد الإلكتروني من معلمة `devices` تلقائيًا. |
| users | `array` | لا | إذا تم تعيينها، سيتم تسليم رسالة البريد الإلكتروني فقط إلى [معرفات المستخدم](/ar/developer/api-reference/api-identifiers/#user-id) المحددة (المسجلة عبر استدعاء /registerEmail). لا يزيد عن 1000 معرف مستخدم في المصفوفة. إذا تم تحديد معلمة "devices"، فسيتم تجاهل معلمة "users". |
| dynamic_content_placeholders | `object` | لا | عناصر نائبة للمحتوى الديناميكي بدلاً من قيم علامات الجهاز. |
| conditions | `array` | لا | شروط التجزئة باستخدام العلامات. مثال: `[["Country", "EQ", "BR"]]`. |
| from | `object` | لا | حدد اسم مرسل وبريد إلكتروني مخصصين، متجاوزًا الإعداد الافتراضي في خصائص التطبيق. |
| reply-to | `object` | لا | حدد بريدًا إلكترونيًا مخصصًا للرد، متجاوزًا الإعداد الافتراضي في خصائص التطبيق.  |
| bcc | `array` | لا | BCC (نسخة كربونية عمياء): مصفوفة من عناوين البريد الإلكتروني التي تتلقى نسخة من البريد الإلكتروني دون أن يراها المستلمون الآخرون. |
| email_type | `string` | لا | حدد نوع البريد الإلكتروني: `"marketing"` أو `"transactional"`. إذا تم حذفه، فلن يتلقى المستخدمون الذين لديهم `PW_ControlGroup: true` الرسالة. |
| email_category | `string` | مطلوب عندما يكون `email_type` هو `"marketing"`. | حدد أحد أسماء الفئات التي تم تكوينها في [مركز تفضيلات الاشتراك](/ar/product/messaging-channels/emails/email-preferences/) (على سبيل المثال، النشرة الإخبارية، العروض الترويجية، تحديثات المنتج). |
| transactionId | `string` | لا | معرف رسالة فريد لمنع إعادة الإرسال في حالة وجود مشاكل في الشبكة. يتم تخزينه على جانب Pushwoosh لمدة 5 دقائق.|
| capping\_days              | `integer`            |    لا    | عدد الأيام (بحد أقصى 30) لتطبيق تحديد التكرار لكل جهاز.   **ملاحظة:** تأكد من تكوين [تحديد التكرار العالمي](/ar/product/messaging-channels/global-frequency-capping/) في لوحة التحكم.                                                                                                           |
| capping\_count             | `integer`            |    لا    | الحد الأقصى لعدد رسائل البريد الإلكتروني التي يمكن إرسالها من تطبيق معين إلى جهاز معين خلال فترة `capping_days`. في حالة تجاوز الرسالة التي تم إنشاؤها حد `capping_count` لجهاز ما، فلن يتم إرسالها إلى ذلك الجهاز.                                                                                            |
| capping\_exclude           | `boolean`            |    لا    | إذا تم تعيينها على `true`، فلن يتم احتساب هذا البريد الإلكتروني ضمن تحديد التكرار للرسائل المستقبلية.                                                                                                        |
| capping\_avoid             | `boolean`            |    لا    | إذا تم تعيينها على `true`، فلن يتم تطبيق تحديد التكرار على هذا البريد الإلكتروني المحدد.                                                                                     |
| send\_rate                 | `integer`            |    لا    | حدد عدد الرسائل التي يمكن إرسالها في الثانية عبر جميع المستخدمين. يساعد على منع الحمل الزائد على الواجهة الخلفية أثناء عمليات الإرسال كبيرة الحجم.
| send\_rate\_avoid          | `boolean`            |    لا    | إذا تم تعيينها على `true`، فلن يتم تطبيق حد التقييد على هذا البريد الإلكتروني المحدد.                                                                          |
### مثال على الطلب
```json 
{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device. 
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions. 
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter 
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      }, 
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ], 
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, users with PW_ControlGroup: true will not receive the message.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit. 
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}
```

### أمثلة على الاستجابة
<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>

<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}
```
</TabItem>
</Tabs>

### شروط العلامة

كل شرط علامة هو مصفوفة مثل `[tagName, operator, operand]` حيث

* tagName: اسم العلامة
* operator: "EQ" | "IN" | "NOTEQ" | "NOTIN" | "LTE" | "GTE" | "BETWEEN"
* operand: string | integer | array | date

#### وصف المعامل

* EQ: قيمة العلامة تساوي المعامل؛
* IN: قيمة العلامة تتقاطع مع المعامل (يجب أن يكون المعامل دائمًا مصفوفة)؛
* NOTEQ: قيمة العلامة لا تساوي المعامل؛
* NOTIN: قيمة العلامة لا تتقاطع مع المعامل (يجب أن يكون المعامل دائمًا مصفوفة)؛
* GTE: قيمة العلامة أكبر من أو تساوي المعامل؛
* LTE: قيمة العلامة أصغر من أو تساوي المعامل؛
* BETWEEN: قيمة العلامة أكبر من أو تساوي قيمة المعامل الدنيا ولكنها أصغر من أو تساوي قيمة المعامل القصوى (يجب أن يكون المعامل دائمًا مصفوفة).

#### علامات السلسلة النصية

المعاملات الصالحة: EQ, IN, NOTEQ, NOTIN\
المعاملات الصالحة:

* EQ, NOTEQ: يجب أن يكون المعامل سلسلة نصية؛
* IN, NOTIN: يجب أن يكون المعامل مصفوفة من السلاسل النصية مثل `["value 1", "value 2", "value N"]`؛

#### علامات الأعداد الصحيحة

المعاملات الصالحة: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE\
المعاملات الصالحة:

* EQ, NOTEQ, GTE, LTE: يجب أن يكون المعامل عددًا صحيحًا؛
* IN, NOTIN: يجب أن يكون المعامل مصفوفة من الأعداد الصحيحة مثل `[value 1, value 2, value N]`؛
* BETWEEN: يجب أن يكون المعامل مصفوفة من الأعداد الصحيحة مثل `[min_value, max_value]`.

#### علامات التاريخ

المعاملات الصالحة: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE\
المعاملات الصالحة:

* `"YYYY-MM-DD 00:00"` (سلسلة نصية)
* الطابع الزمني يونكس `1234567890` (عدد صحيح)
* `"N days ago"` (سلسلة نصية) للمعاملات EQ, BETWEEN, GTE, LTE

#### علامات منطقية

المعاملات الصالحة: EQ\
المعاملات الصالحة: `0, 1, true, false`

#### علامات القائمة

المعاملات الصالحة: IN\
المعاملات الصالحة: يجب أن يكون المعامل مصفوفة من السلاسل النصية مثل `["value 1", "value 2", "value N"]`.

<Aside type="danger">
تذكر أنه لا ينبغي استخدام معلمتي "filter" و "conditions" معًا.\
أيضًا، **سيتم تجاهلهما كليهما**، إذا تم استخدام معلمة "devices" في نفس الطلب.
</Aside>

<Aside type="note">
**علامات البلد واللغة**

قيمة علامة اللغة هي رمز من حرفين صغيرين وفقًا لـ [ISO-639-1](https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes)\
قيمة علامة البلد هي رمز من حرفين كبيرين وفقًا لـ [ISO\_3166-2](https://en.wikipedia.org/wiki/ISO\_3166-2)\
على سبيل المثال، لإرسال إشعار فوري للمشتركين الناطقين بالبرتغالية في البرازيل، ستحتاج إلى تحديد الشرط التالي: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]`
</Aside>

## registerEmail

يسجل عنوان البريد الإلكتروني للتطبيق.

`POST` `https://api.pushwoosh.com/json/1.3/registerEmail`

#### ترويسات الطلب

| الاسم          | مطلوب | القيمة         | الوصف                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | نعم      | Token `XXXX`  | [رمز جهاز API](/ar/developer/api-reference/api-access-token/#device-api-token) للوصول إلى Device API. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك. |


#### جسم الطلب

| الاسم                                          | النوع    | الوصف                                                                                         |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| application\* | string  | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code)                                                                        |
| email\*       | string  | عنوان البريد الإلكتروني.                                                                                      |
| language                                      | string  | اللغة المحلية للجهاز. يجب أن يكون رمزًا من حرفين صغيرين وفقًا لمعيار ISO-639-1. |
| userId                                        | string  | [معرف المستخدم](/ar/developer/api-reference/api-identifiers/#user-id) لربطه بعنوان البريد الإلكتروني.                                                        |
| tz\_offset                                    | integer | إزاحة المنطقة الزمنية بالثواني.                                                                         |
| tags                                          | object  | قيم العلامات لتعيينها للجهاز المسجل.                                                      |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
<TabItem label="210">
```json
{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}
```
</TabItem>
<TabItem label="400">
```json
{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}
```
</TabItem>
<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}
```
</TabItem>
<TabItem label="500">
```json
{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="مثال"
{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered. 
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered. 
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}
```

#### رموز الاستجابة

تعيد واجهة برمجة التطبيقات العامة النتيجة في `status_code`. استخدم الجدول أدناه لتحديد ما إذا كان يجب إعادة محاولة استدعاء فاشل.

| `status_code` | المعنى | إعادة المحاولة؟ |
| ------------- | ------- | ------ |
| `200` | نجاح — تم تسجيل عنوان البريد الإلكتروني. | لا — تم. |
| `210` | خطأ في الوسيطة/التحقق — تم فهم الطلب ولكن تم رفضه (عنوان في القائمة السوداء، بريد إلكتروني غير صالح أو مؤقت، منصة خاطئة لخطة الحساب). انظر [رسائل الخطأ 210](#210-error-messages) أدناه. | **لا** — نفس الطلب يعيد نفس `210`. سجل العنوان وتخطاه. |
| `400` | طلب غير صحيح — JSON غير صالح أو حقل مطلوب مفقود. | لا — أصلح الطلب، لا تكرره. |
| `403` | محظور — رمز جهاز API غير صالح أو مقيد. | لا — أصلح التفويض. |
| `500` | خطأ داخلي في الخادم — مشكلة مؤقتة في البنية التحتية أو مهلة. | **نعم**، مع التراجع الأسي — الحالة العابرة الوحيدة. |

<Aside type="tip">
أعد المحاولة فقط للاستجابات `500`، باستخدام التراجع الأسي — إنها الحالة العابرة الوحيدة. الاستجابة `210` أو `400` أو `403` نهائية: فهم الخادم طلبك ورفضه، لذا فإن تكراره دون تغيير يعيد نفس النتيجة. بدلاً من ذلك، سجل العنوان (لـ `210`) أو أصلح الطلب/الرمز (لـ `400`/`403`).
</Aside>

#### رسائل الخطأ 210

تحمل الاستجابة `210` السبب المحدد في `status_message`.

| `status_message` | المعنى |
| ---------------- | ------- |
| `this hwid (email) is blacklisted` | العنوان موجود في قائمة الحظر بعد ارتداد دائم (hard) ولن يتم إعادة تسجيله. |
| `hwid (email) is invalid` / `has invalid semantic` | فشل التحقق من صحة العنوان. |
| `hwid (email) is empty` | لم يتم تقديم أي عنوان. |
| `hwid (email) has invalid count of parts` | علامة `@` مفقودة أو زائدة. |
| `hwid (email) has invalid local part` | الجزء قبل `@` غير صالح. |
| `hwid (email) has invalid domain part` | جزء النطاق غير صالح. |
| `hwid (email) has disposable domain` | يستخدم العنوان نطاق بريد إلكتروني مؤقت (مثل 10minutemail). |
| `hwid is not valid` | `hwid` نفسه غير صحيح. |
| `only email platform allowed for Email Only subscription` | الحساب على خطة بريد إلكتروني فقط ولا يمكنه تسجيل أجهزة غير البريد الإلكتروني. |

<Aside type="note">
فقط **الارتدادات الدائمة (hard bounces)** تضيف عنوانًا إلى القائمة السوداء. الارتدادات الناعمة وشكاوى البريد العشوائي **لا** تمنع `registerEmail` — فقط `this hwid (email) is blacklisted` يعكس الحظر.
</Aside>

## deleteEmail

يزيل عنوان البريد الإلكتروني من قاعدة المستخدمين الخاصة بك.

`POST` `https://api.pushwoosh.com/json/1.3/deleteEmail`

#### ترويسات الطلب

| الاسم          | مطلوب | القيمة         | الوصف                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | نعم      | Token `XXXX`  | [رمز جهاز API](/ar/developer/api-reference/api-access-token/#device-api-token) للوصول إلى Device API. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك. |


#### جسم الطلب

| الاسم        | النوع   | الوصف                                   |
| ----------- | ------ | --------------------------------------------- |
| application | string | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code)                 |
| email       | string | عنوان البريد الإلكتروني المستخدم في طلب [`/registerEmail`](/ar/developer/api-reference/email-api/#registeremail). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="مثال"
{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}
```

## setEmailTags

يضبط قيم العلامات لعنوان البريد الإلكتروني.

`POST` `https://api.pushwoosh.com/json/1.3/setEmailTags`

#### ترويسات الطلب

| الاسم          | مطلوب | القيمة         | الوصف                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | نعم      | Token `XXXX`  | [رمز جهاز API](/ar/developer/api-reference/api-access-token/#device-api-token) للوصول إلى Device API. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك. |

#### جسم الطلب

| الاسم        | النوع   | الوصف                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| application | string | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code)                                   |
| email       | string | عنوان البريد الإلكتروني.                                                |
| tags        | object | كائن JSON للعلامات المراد تعيينها، أرسل 'null' لإزالة القيمة.  |
| userId      | string | [معرف المستخدم](/ar/developer/api-reference/api-identifiers/#user-id) المرتبط بعنوان البريد الإلكتروني.                    |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}
```
</TabItem>
</Tabs>

```json title="مثال"
{
  "request": {
    "email": "email@domain.com",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": { 
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}
```

<Aside type="note">
بالنسبة لأنواع الأجهزة الأخرى، سيتم إرجاع 200 OK، على الرغم من عدم حفظ العلامات.
</Aside>

<Aside type="caution">
يرجى تجنب تعيين أكثر من 50 قيمة علامة في طلب `/setEmailTags` واحد.
</Aside>

## registerEmailUser

يربط [معرف مستخدم](/ar/developer/api-reference/api-identifiers/#user-id) خارجيًا بعنوان بريد إلكتروني محدد.

`POST` `https://api.pushwoosh.com/json/1.3/registerEmailUser`



<Aside type="note">
يرجى ملاحظة أن هذه الطريقة **لا تسجل عنوان بريد إلكتروني** في قاعدة المستخدمين الخاصة بك؛ يجب استخدامها فقط لتعيين معرفات المستخدمين لعناوين البريد الإلكتروني التي تم تسجيلها بالفعل بواسطة طلب `/registerEmail`.
</Aside>

يمكن استخدامها في استدعاء واجهة برمجة التطبيقات `/createEmailMessage` (معلمة 'users').

#### ترويسات الطلب

| الاسم          | مطلوب | القيمة         | الوصف                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | نعم      | Token `XXXX`  | [رمز جهاز API](/ar/developer/api-reference/api-access-token/#device-api-token) للوصول إلى Device API. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك. |


#### جسم الطلب

| الاسم                                          | النوع    | الوصف                                    |
| --------------------------------------------- | ------- | ---------------------------------------------- |
| application\* | string  | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code)                   |
| email\*       | string  | عنوان البريد الإلكتروني.                                 |
| userId\*      | string  | [معرف المستخدم](/ar/developer/api-reference/api-identifiers/#user-id) لربطه بعنوان البريد الإلكتروني.   |
| tz\_offset                                    | integer | إزاحة المنطقة الزمنية بالثواني.                    |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>

<TabItem label="400">
```json
{
  "status_code": 400,
  "status_message": "Request format is not valid."
}
```
</TabItem>

<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Forbidden."
}
```
</TabItem>
</Tabs>

```json title="مثال"
{
  "request": {
    "application": "APPLICATION_CODE", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}
```

<Aside type="note">
 لاسترداد البيانات حول الارتدادات الناعمة والارتدادات الدائمة وشكاوى البريد الإلكتروني، بما في ذلك التاريخ وعنوان البريد الإلكتروني وسبب كل ارتداد، استخدم طريقة [BouncedEmails](/ar/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails).
</Aside>