Email API
API methods to manage emails
Creates an email message.
post
https://cp.pushwoosh.com/json/1.3
/createEmailMessage
Example
{
"request": {
"application": "APPLICATION_CODE", // required, Pushwoosh application code
"applications_group": "GROUP_CODE", // optional, can be used instead of "application".
"auth": "API_ACCESS_TOKEN", // required, API access token from Pushwoosh Control Panel with "Email API" restriction enabled
"notifications": [{
"campaign": "CAMPAIGN_CODE", // optional. To assign this email message to a particular campaign, add a campaign code here.
"transactionId": "6e22a9af-84e4-46e6-af16-e457a4a6e7e5", // optional. Unique message identifier to prevent re-sending in case of network problems. Stored on the side of Pushwoosh for 1 day.
"send_date": "now", // required, YYYY-MM-DD HH:mm OR 'now'
"ignore_user_timezone": true, // or false, optional
"email_template": "ERDWE-32GFR", // required, 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", // optional. Specify to send the message according to timezone set on user's device.
"filter": "FILTER_NAME", // optional. Send the email message to specific users meeting filter conditions.
"devices": ["email_address1", "email_address2", ..., "email_addressN"], // optional. 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"], // optional. If 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.
"subject": [ // required, email message subject line.
{"default": "Hello {firstname|CapitalizeFirst|user}."},
{"en": "Hello {firstname_en|CapitalizeFirst|user}."}
],
"dynamic_content_placeholders": { // optional, placeholders for dynamic content instead of device tag values.
"firstname": "John",
"firstname_en": "John"
},
"conditions": [TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN], // optional, segmentation conditions, see remark below.
"from": {"name": "alias from", "email": "[email protected]"}, //optional. 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": {"name": "alias reply to ", "email": "[email protected]"} // optional. Specify an email address to replace the default "Reply to" set up in application properties. Please note that "reply-to.email" value should be previously verified for your account.
}]
}
}
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
- 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).
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"];
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].
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
Valid operators: EQ
Valid operands:
0, 1, true, falseValid 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"]]Registers email address for the app.
post
https://cp.pushwoosh.com/json/1.3
/registerEmail
Example
{
"request" : {
"application" : "APPLICATION_CODE", // required, Pushwoosh application code
"email" : "[email protected]", // 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": "2015-10-02 22:11", // note the time should be in UTC
"BooleanTag": true // valid values are: true, 1, false, 0, null
}
}
}
Removes email address from your user base.
post
https://cp.pushwoosh.com/json/1.3
/deleteEmail
/deleteEmail
Example
{
"request" : {
"application" : "APPLICATION_CODE", // required, Pushwoosh application code
"email" : "[email protected]" // required, email to delete from app subscribers
}
}
Sets tag values for the email address.
post
https://cp.pushwoosh.com/json/1.3
/setEmailTags
Example
{
"request" : {
"auth" : "eXKjNPrq..............R0FSsLIXuZF", // required, API Token with "Email API" restriction enabled
"email" : "[email protected]", // required, email address to set tags for
"application" : "APPLICATION_CODE", // required, Pushwoosh 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" // optional, User ID associated with the email address
}
}
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.Associates an external User ID with a specified email address.
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).post
https://cp.pushwoosh.com/json/1.3
/registerEmailUser
Example
{
"request" : {
"auth" : "API Token", // required, API Token with "Email API" restriction enabled
"application" : "APPLICATION_CODE", // required, Pushwoosh application code
"email" : "[email protected]", // required, user email address
"userId" : "userId", // required, user ID to associate with the email address
"tz_offset" : 3600 // optional, timezone offset in seconds
}
}
Retrieves the list of email addresses that bounced your email messages.
post
https://cp.pushwoosh.com/json/1.3
/getBouncedEmails
Example
{
"request": {
"auth": "eXKjNPrq..............5sHvPR0FSsLIXuZF", // required, API access code with "Email API" restriction enabled
"application": "XXXXX-XXXXX", // required, Pushwoosh app code
"message": "XXXXXXXXXXXX", // required, message code or message ID to get the bounced emails list for.
"date_from": "2019-09-01", // optional, start of the reporting period
"date_to": "2019-09-30" // optional, end of the reporting period
}
}
Field | Type | Description |
request_id | string |
The method will respond with a downloadable .csv file containing bounced email addresses, date and time of the bounce occurred, and the bounce reason.
CSV example with possible bounce reasons
Last modified 20d ago