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

createEmailMessage

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

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

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

الاسم	النوع	مطلوب	الوصف
auth	`string`	نعم	رمز وصول API من لوحة تحكم Pushwoosh.
application	`string`	نعم	رمز تطبيق Pushwoosh
notifications	`array`	نعم	مصفوفة JSON تحتوي على تفاصيل رسالة البريد الإلكتروني. انظر جدول معلمات الإشعارات أدناه.

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

الاسم	النوع	مطلوب	الوصف
send_date	`string`	نعم	يحدد متى يتم إرسال البريد الإلكتروني. التنسيق: `YYYY-MM-DD HH:mm` أو `"now"`.
preset	`string`	نعم	رمز الإعداد المسبق للبريد الإلكتروني. انسخه من شريط 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`	لا	رمز الحملة لربط البريد الإلكتروني بحملة معينة.
ignore_user_timezone	`boolean`	لا	إذا كانت القيمة `true`، يتم إرسال البريد الإلكتروني فورًا، مع تجاهل المناطق الزمنية للمستخدم.
timezone	`string`	لا	يرسل البريد الإلكتروني وفقًا للمنطقة الزمنية للمستخدم. مثال: `"America/New_York"`.
filter	`string`	لا	يرسل البريد الإلكتروني للمستخدمين الذين يطابقون شرط فلتر معين.
devices	`array`	لا	قائمة بعناوين البريد الإلكتروني (بحد أقصى 1000) لإرسال رسائل بريد إلكتروني مستهدفة. إذا تم استخدامها، يتم إرسال الرسالة فقط إلى هذه العناوين. يتم تجاهلها إذا تم استخدام مجموعة التطبيقات.
use_auto_registration	`boolean`	لا	إذا كانت القيمة `true`، يتم تسجيل رسائل البريد الإلكتروني من معلمة `devices` تلقائيًا.
users	`array`	لا	إذا تم تعيينه، سيتم تسليم رسالة البريد الإلكتروني فقط إلى معرفات المستخدم المحددة (المسجلة عبر استدعاء /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"`.
email_category	`string`	مطلوب عندما يكون `email_type` هو `"marketing"`.	حدد أحد أسماء الفئات التي تم تكوينها في مركز تفضيلات الاشتراك (على سبيل المثال، Newsletter، Promotional، Product Updates).
transactionId	`string`	لا	معرف رسالة فريد لمنع إعادة الإرسال في حالة حدوث مشاكل في الشبكة. يتم تخزينه على جانب Pushwoosh لمدة 5 دقائق.
capping_days	`integer`	لا	عدد الأيام (بحد أقصى 30) لتطبيق تحديد التكرار لكل جهاز. ملاحظة: تأكد من تكوين تحديد التكرار العالمي في لوحة التحكم.
capping_count	`integer`	لا	الحد الأقصى لعدد رسائل البريد الإلكتروني التي يمكن إرسالها من تطبيق معين إلى جهاز معين خلال فترة `capping_days`. في حالة تجاوز الرسالة التي تم إنشاؤها حد `capping_count` لجهاز ما، فلن يتم إرسالها إلى ذلك الجهاز.
capping_exclude	`boolean`	لا	إذا تم تعيينه على `true`، فلن يتم احتساب هذا البريد الإلكتروني ضمن تحديد التكرار للرسائل المستقبلية.
capping_avoid	`boolean`	لا	إذا تم تعيينه على `true`، فلن يتم تطبيق تحديد التكرار على هذا البريد الإلكتروني المحدد.
send_rate	`integer`	لا	حدد عدد الرسائل التي يمكن إرسالها في الثانية عبر جميع المستخدمين. يساعد على منع الحمل الزائد على الواجهة الخلفية أثناء عمليات الإرسال كبيرة الحجم.
send_rate_avoid	`boolean`	لا	إذا تم تعيينه على `true`، فلن يتم تطبيق حد التقييد على هذا البريد الإلكتروني المحدد.

مثال على الطلب

{
  "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".
      "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.
      "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.
    }]
  }
}

أمثلة على الاستجابة

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

شروط العلامة

كل شرط علامة هو مصفوفة مثل [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"].

registerEmail

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

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

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

جسم الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
email*	string	عنوان البريد الإلكتروني.
language	string	لغة الجهاز المحلية. يجب أن يكون رمزًا من حرفين صغيرين وفقًا لمعيار ISO-639-1.
userId	string	معرف المستخدم لربطه بعنوان البريد الإلكتروني.
tz_offset	integer	إزاحة المنطقة الزمنية بالثواني.
tags	object	قيم العلامات لتعيينها للجهاز المسجل.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "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
    }
  }
}

deleteEmail

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

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

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

جسم الطلب

الاسم	النوع	الوصف
application	string	رمز تطبيق Pushwoosh
email	string	عنوان البريد الإلكتروني المستخدم في طلب `/registerEmail`.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "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 للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

جسم الطلب

الاسم	النوع	الوصف
application	string	رمز تطبيق Pushwoosh
email	string	عنوان البريد الإلكتروني.
tags	object	كائن JSON للعلامات المراد تعيينها، أرسل ‘null’ لإزالة القيمة.
userId	string	معرف المستخدم المرتبط بعنوان البريد الإلكتروني.

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

{
  "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.
  }
}

registerEmailUser

يربط معرف مستخدم خارجي بعنوان بريد إلكتروني محدد.

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

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

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

جسم الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
email*	string	عنوان البريد الإلكتروني.
userId*	string	معرف المستخدم لربطه بعنوان البريد الإلكتروني.
tz_offset	integer	إزاحة المنطقة الزمنية بالثواني.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

{
  "status_code": 403,
  "status_message": "Forbidden."
}

{
  "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.
  }
}