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âName | Type | Required | Description |
---|---|---|---|
auth | string | Yes | API access token from Pushwoosh Control Panel. |
application | string | Yes | Pushwoosh application code. |
notifications | array | Yes | JSON array containing email message details. See the Notifications Parameters table below. |
Notifications parameters
Section titled âNotifications parametersâName | Type | Required | Description |
---|---|---|---|
send_date | string | Yes | Defines when to send the email. Format: YYYY-MM-DD HH:mm or "now" . |
preset | string | Yes | Email preset code. Copy from the URL bar of the Email Content Editor in the Pushwoosh Control Panel. |
subject | string or object | No | Subject 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. |
content | string or object | No | The email body content. Can be a string for plain HTML content or an object for localized versions. |
attachments | array | No | The email attachments. Only two attachments are available. Each attachment must not exceed 1MB (base64 encoded). |
campaign | string | No | Campaign code to associate the email with a specific campaign. |
ignore_user_timezone | boolean | No | If true , sends the email immediately, ignoring user timezones. |
timezone | string | No | Sends the email according to the userâs timezone. Example: "America/New_York" . |
filter | string | No | Sends the email to users matching a specific filter condition. |
devices | array | No | List 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_registration | boolean | No | If true , automatically registers emails from the devices parameter. |
users | array | No | 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. |
dynamic_content_placeholders | object | No | Placeholders for dynamic content instead of device tag values. |
conditions | array | No | Segmentation conditions using tags. Example: [["Country", "EQ", "BR"]] . |
from | object | No | Specify a custom sender name and email, overriding the default in application properties. |
reply-to | object | No | Specify a custom reply-to email, overriding the default in application properties. |
transactionId | string | No | Unique message identifier to prevent re-sending in case of network problems. Stored on the side of Pushwoosh for 5 minutes. |
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. }] }}
Response examples
Section titled âResponse examplesâ{ "status_code": 200, "status_message": "OK", "response": null}
{ "status_code": 403, "status_message": "Token restrictions forbid this operation", "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âName | Required | Value | Description |
---|---|---|---|
Authorization | Yes | Token XXXX | API Device Token to access Device API. Replace XXXX with your actual Device API token. |
Request body
Section titled â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. |
{ "status_code": 200, "status_message": "OK", "response": null}
{ "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âName | Required | Value | Description |
---|---|---|---|
Authorization | Yes | Token XXXX | API Device Token to access Device API. Replace XXXX with your actual Device API token. |
Request body
Section titled âRequest bodyâName | Type | Description |
---|---|---|
application | string | Pushwoosh application code. |
string | Email address used in /registerEmail request. |
{ "status_code": 200, "status_message": "OK", "response": null}
{ "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âName | Required | Value | Description |
---|---|---|---|
Authorization | Yes | Token XXXX | API Device Token to access Device API. Replace XXXX with your actual Device API token. |
Request body
Section titled âRequest bodyâName | Type | Description |
---|---|---|
application | string | Pushwoosh application code. |
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. |
{ "status_code": 200, "status_message": "OK", "response": { "skipped": [] }}
{ "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âName | Required | Value | Description |
---|---|---|---|
Authorization | Yes | Token XXXX | API Device Token to access Device API. Replace XXXX with your actual Device API token. |
Request body
Section titled âRequest bodyâName | Type | Description |
---|---|---|
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. |
{ "status_code": 200, "status_message": "OK", "response": null}
{ "status_code": 400, "status_message": "Request format is not valid."}
{ "status_code": 403, "status_message": "Forbidden."}
{ "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. }}