Email API

API methods to manage emails

post
/createEmailMessage

https://cp.pushwoosh.com/json/1.3/createEmailMessage
Creates an email message.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
application
required
string
Pushwoosh application code.
notifications
required
array
JSON array of email message parameters. Look at the request example below for more info.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": null
}
403: Forbidden
{
"status_code": 403,
"status_message": "Token restrictions forbid this operation",
"response": null
}
Example
{
"request": {
"application": "APPLICATION_CODE",
"applications_group": "GROUP_CODE", // Can be used instead of "application".
"auth": "API_ACCESS_TOKEN",
"notifications": [{
"campaign": "CAMPAIGN_CODE", // To assign this email message to a particular campaign, add a campaign code here.
"transactionId": "6e22a9af-84e4-46e6-af16-e457a4a6e7e5", // Unique message identifier to prevent re-sending in case of network problems. Stored on the side of Pushwoosh for 1 day.
"send_date": "now", // YYYY-MM-DD HH:mm OR 'now'
"ignore_user_timezone": true, // or false
"email_template": "ERDWE-32GFR", // email template code. Copy the template code from the URL bar of the Email Templates editor page in Pushwoosh Control Panel.
"timezone": "America/New_York", // Specify to send the message according to timezone set on user's device.
"filter": "FILTER_NAME", // Send the email message to specific users meeting filter conditions.
"devices": ["email_address1", "email_address2", ..., "email_addressN"], // Specify email addresses to send targeted email messages. Not more than 1000 addresses in an array. 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": ["userId1", "userId2", ..., "userIdN"], // If set, the email message will only be delivered to the specified user IDs (registered via /registerUser call). Not more than 1000 user IDs in an array. If the "devices" parameter is specified, the "users" parameter will be ignored.
"subject": [
{"default": "Hello {firstname|CapitalizeFirst|user}."},
{"ru": "Привет, {firstname_ru|CapitalizeFirst|пользователь}."},
{"en": "Hello {firstname_en|CapitalizeFirst|user}."}
],
"dynamic_content_placeholders": {
"firstname": "John",
"firstname_ru": "Джон",
"firstname_en": "John"
}, // optional, placeholders for dynamic content instead of device tag values.
"conditions": [TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN], // See remark below.
"from": {"name": "alice", "email": "from-email@email.com"}, //Specify a sender name and sender email address to replace the default "From name" and "From email" set up in application properties. Please note that "from_email" value should be previously verified for your account.
"reply-to": "reply-to@email.com" // Specify an email address to replace the default "Reply to" set up in application properties. Please note that "reply-to" value should be previously verified for your account.
}]
}
}

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

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.

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

post
/registerEmail

https://cp.pushwoosh.com/json/1.3/registerEmail
Registers email address for the app.
Request
Response
Body Parameters
auth
required
string
API access token with "Email API" restriction.
application
required
string
Pushwoosh application code.
email
required
string
Email address.
language
optional
string
Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard.
userId
optional
string
User ID to associate with the email address.
tz_offset
optional
integer
Timezone offset in seconds.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": null
}
Example
{
"request" : {
"auth" : "API-Token", // API Token with "Email API" restriction
"application" : "APPLICATION_CODE",
"email" : "email@domain.com",
"language" : "ru", // language locale
"userId" : "userId", // user ID to associate with the email address
"tz_offset" : 3600 // timezone offset in seconds
}
}

post
/deleteEmail

https://cp.pushwoosh.com/json/1.3/deleteEmail
Removes email address from your account.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
email
required
string
Email address used in /registerEmail request.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request" : {
"auth" : "nnFuCDrKT8mVn.........PUnZoxA7XAqq1ZaCvTgNyd",
"email" : "email@domain.com"
}
}

post
/setEmailTags

https://cp.pushwoosh.com/json/1.3/setEmailTags
Sets tag values for the email address.
Request
Response
Body Parameters
auth
required
string
API access token with "Email API" restriction.
application
required
string
Pushwoosh application code.
email
required
string
Email address.
tags
required
object
JSON object of tags to set, send 'null' to remove the value.
userId
optional
string
User ID associated with the email address.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": {
"skipped": []
}
}
Example
{
"request" : {
"auth" : "nnFuCDrKT8mVnQPyYRCoXGMwFmXhMcxzjBYVGg7q70SmfQogLZd001llMqcp8PPUnZoxA7XAqq1ZaCvTgNyd",
"email" : "email@domain.com",
"application" : "APPLICATION_CODE",
"tags" : {
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1","string2"],
"DateTag": "2015-10-02 22:11", // time in UTC
"BooleanTag": true // valid values are: true, 1, false, 0, null
},
"userId" : "userId"
}
}

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

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

post
/registerEmailUser

https://cp.pushwoosh.com/json/1.3/registerEmailUser
Associates an external User ID with a specified email address. Can be used in /createEmailMessage API call (the 'users' parameter).
Request
Response
Body Parameters
auth
required
string
API access token with "Email API" restriction.
application
required
string
Pushwoosh application code.
email
required
string
Email address.
userId
required
string
User ID to associate with the email address.
tz_offset
optional
integer
Timezone offset in seconds.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": null
}
400: Bad Request
{
"status_code": 400,
"status_message": "Request format is not valid."
}
403: Forbidden
{
"status_code": 403,
"status_message": "Forbidden."
}
Example
{
"request" : {
"auth" : "API Token", // API Token with restriction "Email API"
"application" : "APPLICATION_CODE",
"email" : "email@domain.com",
"userId" : "userId",
"tz_offset" : 3600
}
}