Skip to content
User guides Support Request demo Sign in
Pushwoosh.com

Email API

createEmailMessage

Section titled “createEmailMessage”

Creates an email message.

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

Request parameters

Section titled “Request parameters”
NameType
RequiredDescription
authstringYesAPI access token from Pushwoosh Control Panel.
applicationstringYesPushwoosh application code
notificationsarrayYesJSON array containing email message details. See the Notifications Parameters table below.

Notifications parameters

Section titled “Notifications parameters”
NameType
RequiredDescription
send_datestringYesDefines when to send the email. Format: YYYY-MM-DD HH:mm or "now".
presetstringYesEmail preset code. Copy from the URL bar of the Email Content Editor in the Pushwoosh Control Panel.
subjectstring or objectNoSubject line of the email. The email will always be in the language of the content. If subject does not contain a matching language for content, the subject will be empty.
contentstring or objectNoThe email body content. Can be a string for plain HTML content or an object for localized versions.
attachmentsarrayNoThe email attachments. Only two attachments are available. Each attachment must not exceed 1MB (base64 encoded).
campaignstringNoCampaign code to associate the email with a specific campaign.
ignore_user_timezonebooleanNoIf true, sends the email immediately, ignoring user timezones.
timezonestringNoSends the email according to the user’s timezone. Example: "America/New_York".
filterstringNoSends the email to users matching a specific filter condition.
devicesarrayNoList of email addresses (max 1000) to send targeted emails. If used, the message is sent only to these addresses. Ignored if the Application Group is used.
use_auto_registrationbooleanNoIf true, automatically registers emails from the devices parameter.
usersarrayNoIf set, the email message will only be delivered to the specified user IDs (registered via /registerEmail call). Not more than 1000 user IDs in an array. If the “devices” parameter is specified,the “users” parameter will be ignored.
dynamic_content_placeholdersobjectNoPlaceholders for dynamic content instead of device tag values.
conditionsarrayNoSegmentation conditions using tags. Example: [["Country", "EQ", "BR"]].
fromobjectNoSpecify a custom sender name and email, overriding the default in application properties.
reply-toobjectNoSpecify a custom reply-to email, overriding the default in application properties.
transactionIdstringNoUnique message identifier to prevent re-sending in case of network problems. Stored on the side of Pushwoosh for 5 minutes.
capping_daysintegerNoThe number of days (max 30) to apply frequency capping per device. Note: Ensure Global frequency capping is configured in the Control Panel.
capping_countintegerNoThe 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_excludebooleanNoIf set to true, this email will not be counted towards the capping for future emails.
capping_avoidbooleanNoIf set to true, capping will not be applied to this specific email.

Request example

Section titled “Request example”
{
  "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"
      }],
      "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"
      },
      "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.
    }]
  }
}

Response examples

Section titled “Response examples”
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Tag conditions

Section titled “Tag conditions”

Each tag condition is an array like [tagName, operator, operand] where

  • tagName: name of a tag
  • operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
  • operand: string | integer | array | date

Operand description

Section titled “Operand description”
  • EQ: tag value is equal to operand;
  • IN: tag value intersects with operand (operand must always be an array);
  • NOTEQ: tag value is not equal to an operand;
  • NOTIN: tag value does not intersect with operand (operand must always be an array);
  • GTE: tag value is greater than or equal to operand;
  • LTE: tag value is less than or equal to operand;
  • BETWEEN: tag value is greater than or equal to min operand value but less than or equal to max operand value (operand must always be an array).

String tags

Section titled “String tags”

Valid operators: EQ, IN, NOTEQ, NOTIN
Valid operands:

  • EQ, NOTEQ: operand must be a string;
  • IN, NOTIN: operand must be an array of strings like ["value 1", "value 2", "value N"];

Integer tags

Section titled “Integer tags”

Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Valid operands:

  • EQ, NOTEQ, GTE, LTE: operand must be an integer;
  • IN, NOTIN: operand must be an array of integers like [value 1, value 2, value N];
  • BETWEEN: operand must be an array of integers like [min_value, max_value].

Date tags

Section titled “Date tags”

Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Valid operands:

  • "YYYY-MM-DD 00:00" (string)
  • unix timestamp 1234567890 (integer)
  • "N days ago" (string) for operators EQ, BETWEEN, GTE, LTE

Boolean tags

Section titled “Boolean tags”

Valid operators: EQ
Valid operands: 0, 1, true, false

List tags

Section titled “List tags”

Valid operators: IN
Valid operands: operand must be an array of strings like ["value 1", "value 2", "value N"].

registerEmail

Section titled “registerEmail”

Registers email address for the app.

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “Request body”
NameTypeDescription
application*stringPushwoosh application code
email*stringEmail address.
languagestringLanguage locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard.
userIdstringUser ID to associate with the email address.
tz_offsetintegerTimezone offset in seconds.
tagsobjectTag values to assign to the device registered.
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
Example
{
  "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

Section titled “deleteEmail”

Removes email address from your user base.

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “Request body”
NameTypeDescription
applicationstringPushwoosh application code
emailstringEmail address used in /registerEmail request.
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
Example
{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

setEmailTags

Section titled “setEmailTags”

Sets tag values for the email address.

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “Request body”
NameTypeDescription
applicationstringPushwoosh application code
emailstringEmail address.
tagsobjectJSON object of tags to set, send ‘null’ to remove the value.
userIdstringUser ID associated with the email address.
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}
Example
{
  "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

Section titled “registerEmailUser”

Associates an external User ID with a specified email address.

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

Can be used in /createEmailMessage API call (the ‘users’ parameter).

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “Request body”
NameTypeDescription
application*stringPushwoosh application code
email*stringEmail address.
userId*stringUser ID to associate with the email address.
tz_offsetintegerTimezone offset in seconds.
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
Example
{
  "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.
  }
}