Email API

createEmailMessage

Creates an email message.

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

Request Body

Name	Type	Description
auth*	string	API access token from Pushwoosh Control Panel.
application*	string	Pushwoosh application code.
notifications*	array	JSON array of email message parameters. Look at the request example below for more info.

200

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

403

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

Example

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "applications_group": "GROUP_CODE", // optional. Can be used instead of "application".
    "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.
        "default": "Hello, User."
      }, {
        "en": "Hello, User."
      }],
      "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.
    }]
  }
}

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

• 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

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

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

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

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

List tags

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

Danger

Remember that “filter” and “conditions” parameters should not be used together.
Also, both of them will be ignored, if the “devices” parameter is used in the same request.

Note

Country and Language tags

Language tag value is a lowercase two-letter code according to ISO-639-1
Country tag value is an UPPERCASE two-letter code according to ISO_3166-2
For example, to send push a notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

registerEmail

Registers email address for the app.

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

Request Body

Name	Type	Description
application*	string	Pushwoosh application code.
email*	string	Email address.
language	string	Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard.
userId	string	User ID to associate with the email address.
tz_offset	integer	Timezone offset in seconds.
tags	object	Tag values to assign to the device registered.

200

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

Removes email address from your user base.

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

Request Body

Name	Type	Description
application	string	Pushwoosh application code.
email	string	Email address used in /registerEmail request.

200

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

Sets tag values for the email address.

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

Request Body

Name	Type	Description
auth	string	API access token.
application	string	Pushwoosh application code.
email	string	Email address.
tags	object	JSON object of tags to set, send ‘null’ to remove the value.
userId	string	User ID associated with the email address.

200

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

Example

{
  "request": {
    "auth": "eXKjNPrq..............R0FSsLIXuZF",  // required. API Access Token.
    "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.
  }
}

Note

For other device types will be returned 200 OK, though tags won’t be saved.

Caution

Please avoid setting more than 50 tag values in a single /setEmailTags request.

registerEmailUser

Associates an external User ID with a specified email address.

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

Note

Please note that this method does not register an email address in your user base; it should be used only for assigning user IDs to email addresses that have been registered already by /registerEmail request.

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

Request Body

Name	Type	Description
auth*	string	API access token.
application*	string	Pushwoosh application code.
email*	string	Email address.
userId*	string	User ID to associate with the email address.
tz_offset	integer	Timezone offset in seconds.

200

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

400

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

403

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

Example

{
  "request": {
    "auth": "API Token",               // required. API Access Token.
    "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.
  }
}

Note

To retrieve data on soft bounces, hard bounces, and email complaints, including the date, email address, and reason for each bounce, use the BouncedEmails method.