Email Templates

This guide refers to developing Email Templates with HTML

Create a template

Template syntax

Email template is a .zip archive containing index.html in its root. Most email clients don't support JavaScript and CSS as email assets. Please consider inlining CSS and avoid scripts.

Please make sure that your index.html is UTF-8 encoded.

Message size

Actual message size after base64 encoding is limited to 10 MB per message, which means 6 MB limitation of raw message size. The larger your email message is, the slower it’s delivered and downloaded on the user’s device. Large messages produce more system load and can trigger spam filtering. Moreover, some email clients clip large messages, and the recipient needs to click on “View entire message” to see the email message in full. Please take into account that emails you send should be as light as possible.

CSS inlining

To ensure that various email clients render your email message properly, please consider inlining CSS. It provides more compatibility and guarantees correct performance of your email styles in email clients not supporting external and embedded styles. For example, embedded styles placed in the <head> of the HTML document are mostly stripped out by Gmail.

Embedding images

To embed images in your email template, use inline embedding (base64 images) or link out to images to load them from an external server.

Base64 images

Encode your image with a base64 tool and add a base64 encoded string to the HTML code as follows:

<img src=“data:image/png;base64, ,iVBORw0KGgoAAAANSUhEUgAAAH0AAACVCAIAAAD6... your image encoded to base64”/>

Linked images

Another option is to add a link to the external source as follows:

<img src="https://example.org/image.png">

SVG

Please note that most email clients don’t support SVG images.

Customize a template

Placeholders

To customize and localize the template content, use placeholders. A placeholder must follow the format below: {{ Placeholder name | Type | Default value }}

Where:

  • Placeholder name — is the name of the placeholder displayed in the Email Templates editor.

  • Type — is the type of the placeholder. The type can take any of the following values:

    • color — color input

    • text — text input

    • html — text area (multiline text)

  • Default value — default value that is used if no value is provided in the editor. If none is set then Placeholder name is used as a default value.

{{Header text|text|Tell Us What You Think}}

You can group placeholders so they would be linked together in the Email Templates editor. To achieve that, add a pushwoosh.json file to the archive with your email template next to the index.html file.

The structure of the file is very simple and should be self-explanatory:

{
"input_groups": [
["Logo image URL", "Logo background color"],
["Topic text", "Topic text color", "Topic background color", "Sub-topic text"],
["Main text", "Text background color"],
["Button text", "Button URL", "Button text color", "Button background color"]
]
}

Using Unsubscribe link in emails is obligatory by legislation.

To give recipients a way to unsubscribe from your emails, add the Unsubscribe link to your template as follows:

<a href=“%%PW_EMAIL_UNSUBSCRIBE%%“> Unsubscribe </a>

The attribute value %%PW_EMAIL_UNSUBSCRIBE%% will be replaced with the Pushwoosh Unsubscribe link at the moment you send the email message. When recipients follow the link, they opt out from your emails and are accounted in unsubscribe rate for that particular email message in Message History.

To let you deliver important emails to your customers, we don't delete the unsubscribed users from your user base. For users who followed the Unsubscribed link from your emails, the Unsubscribed Emails default tag is set with the 'true' value.

Please consider creating a Filter for users who did not unsubscribe (the ones with the 'false' value of the Unsubscribed Emails tag) to continue messaging them. To avoid complaints, do not email users who unsubscribed from your messages.

If you use your own Unsubscribe link instead of the Pushwoosh link, you will need to call the /emailUnsubscribe API method to let us know about unsubscribed users. However, when you use your own Unsubscribe link and unregister users via the API, opted out users won’t be accounted in unsubscribe rate presented in Message History. Therefore, to get the correct message statistics, please use the Pushwoosh Unsubscribe link.

Editing email templates

Go to the Email Templates tab in the Pushwoosh Control Panel and click Add Email Template.

Upload a .zip archive containing your email template.

Customize the template in accordance with your goals. Here, you can preview how your Email Template looks on desktop or mobile phone screen.

Dynamic content

Use Dynamic Content placeholders to add a personal touch to your emails. When editing, select a tag and its value modifier, enter a default tag value that would be used in case there is no tag value on user's device, and click Insert. The {TAG_NAME|MODIFIER|DEFAULT_VALUE} placeholder will be substituted by respective tag values in the email for each recipient.

For API triggered emails, the same placeholders can be modified with the data you submit from your backend in the "dynamic_content_placeholders" field of the /createEmailMessage call:

"dynamic_content_placeholders" :{
"upsell_item_name":"PushOn T-Shirt",
"upsell_item_price":"25"
},

Multi-language

To send multi-language emails, choose a language from the drop-down and modify template's content correspondingly. The email message will be delivered to a recipient according to their device locale settings. In case there are no locale settings on user’s device, the default language is English.

To customize and localize the template content, use placeholders.

To add a multi-language subject line to your email, insert subjects localized for different languages to your pushwoosh.json.

{
"subjects": {
"default": "Default Email Subject",
"en": "Email Subject",
"de": "E-Mail Betreff"
},
"default_language": "en",
"localization": {
"en": {
"URL": "https:\/\/example.com\/en\/{SenderID|lowercase|}",
"Button": "English Text"
},
"de": {
"URL": "https:\/\/example.com\/de\/{SenderID|lowercase|}",
"Button": "Der Deutsche Text"
}
}
}

Save changes and go to the Send Email tab.