Skip to content
Pushwoosh Logo Developer Documentation

Email API

createEmailMessage

Creates an email message.

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

Request parameters

NameType
RequiredDescription
authstringYesAPI access token from Pushwoosh Control Panel.
applicationstringYesPushwoosh application code.
applications_groupstringNoCan be used instead of application to send to a group of applications.
notificationsarrayYesJSON array containing email message details. See the Notifications Parameters table below.

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.

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

Response examples

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

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

registerEmail

Registers email address for the app.

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

Request headers

NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

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

Removes email address from your user base.

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

Request headers

NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

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

Sets tag values for the email address.

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

Request headers

NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

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

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

NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

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