Email Templates Tutorial

Email Templates let you send email notifications personalized with values that are specific to each user, e.g., first name, flight number, order status. If you've ever used a mail merge feature to create holiday card labels, you are already familiar with this concept.

First you create the template. Any user can view saved templates and edit the content. After setting up the basic descriptive information for your template, you will define the merge fields, into which the user-specific data will be populated when sending your message. This page takes you through the required steps to create the template.

Your final step will be to either reference the template in your Push API call or select it from the dashboard workflow.

Thanks for reading, {{name}}; we're very excited to have {{your_company}} as a customer!


Contact Urban Airship Support or your Account Manager to provision your project for Email Templates. See: Email Notifications: Configuration and Requirements.


Templates can only be created by a Team member with the Owner, Administrator, or Full Access role. Templates should be created via the dashboard only, not the API. Push messages referencing a template are not editable in the dashboard.

What You'll Do

In this tutorial, you will:

  1. Define the template name and merge fields.
  2. Enter the message content.
  3. Add your company logo image and specify the message's text colors.
  4. Configure a button, if included in your chosen message layout.
  5. Enter message settings, including From name and address, and Subject line.
  6. Send a test message to yourself.

Features and options are explained along the way.


As you create a new template, these page elements are available to guide and assist.

Progress Header

Your steps are tracked in the progress header. Click the left and right arrows to move ahead or to go back and edit.


As you build your template, the preview on the left side of the screen updates with your changes. Links included in the template are functional in the preview.

Select a view from the dropdown menu: Mobile, Plain Text, Browser, or HTML.

The HTML view is not editable but you may copy the HTML to your clipboard by clicking Copy HTML.


Open your project from the dashboard, then click Messages and select Templates.

Then select Email Templates from the left side menu, and click New Email Template.

Template Info


After saving the merge fields created during this step, no fields may be added, removed, or changed. However, you may duplicate and modify any saved template. See Saved Templates.


Of the merge fields created in this step, either all or zero must be used in the template.

In other words, if you create four merge fields, the template Content must include all four merge fields or none of them, otherwise the message will not send.

  1. Enter a Name and a brief Description defining its purpose. The name should be specific enough to help you identify the template in your list of all saved templates.
  2. Click Add a Merge Field. These fields determine the available options when composing your message text.

    Fill out the required fields, then click Addto add the new merge field to the template, or cancel to discard.

    • Key may contain only alphanumeric characters and internal single underscores, and must be at least two characters in length. Required field.
    • Friendly Name is required.
    • Description is optional.


      Key = gate, Friendly Name = Gate Location
      Key = flight, Friendly Name = Flight Number
      Key = air_code, Friendly Name = Airport Code

  3. Click Save once you are satisfied with your merge fields, then Confirm.


  1. Click to select the message Layout.
  2. Click Build in the header to move on, then configure each tab.

Build: Content

  1. Configure the message's Content. Available message elements depend on the selected Layout.

    In the Body and Footer fields, type {{ to enable the merge field selector, allowing you to see what fields are available, then click your choice. You may use merge fields in the Title field, but you must enter them manually rather thanusing the merge field selector. When the merge fields are added to the message, they are listed at the bottom of the screen below the last Content field.

    Example message body for a notification about airline flight information: “Heads up! Your flight {{ flight }} has had a gate change. Your new gate is {{ gate }} at {{ air_code }}.“

    • Title: Enter a headline for the message. The title is bolded and a larger size by default to stand out from the message body. Note: This appears above the message body, it is not the email Subject line. See: Email Notifications: Example.

    • Body: Enter the main text of the message.

    • Media: Enter the URL for the image to be displayed in the message and an Alt Text description. Alt text provides alternative information about an image case it cannot be rendered or if the user uses a screen reader. Ensure the URL will be accessible by your audience.

      Message size may not exceed 250k, so be mindful of using large images. We highly recommend keeping your emails under 100k.

    • Footer: Enter text relevant to the message, e.g., Terms & Conditions.
  2. Optionally set a Default value for each field. Check the box for Allow Empty if you want the field to appear even if it has no value. This pane will appear at the bottom of the page after entering a text body that contains merge fields. These settings are used when a value is not sent through your integration. Take care to craft your message so that your default values will make sense in the case they are needed.Continuing the example in Template Info, these would be appropriate default values:

    • Flight Number: Check the box for Allow Empty so that no value will be displayed if the flight number is not sent.

    • Airport Code: "your airport"

Build: Design

  1. Configure the look of the message by adding your logo and specifying colors. For layout reference, see: Email Notifications: Example.
    • Logo: Enter a URL for the logo image and an Alt Text description. The logo appears in the header above the message body. Alt text provides alternative information about an image case it cannot be rendered or if the user uses a screen reader. Ensure the URL will be accessible by your audience.

    • Header Background, Body Background, and Body Font colors: The header is located above the message body. Make sure that the colors for the message body's background and font colors have enough contrast to be easily readable. Select colors for each. See Color Selection below.

Build: Action

  1. Configure the message's button label, URL, and colors. The Action tab is blank if you did not choose the Action layout.
    • Text: Enter the text that will appear as the button label.

    • URL: Enter the URL that will open when the button is clicked.

    • Background and Font Colors: Select colors for the button's background and text. See Color Selection below.

Build: Settings

  1. Configure the message's Settings.
    • From: Enter the sender name and email address.

    • Subject: Enter the message's subject line and preview text. Preview text is a snippet of the email body that is displayed below the sender name and subject line in a user's inbox. Note: Not all email clients support preview text.

    • Reply To: Specify the email address that will populate the To field if the message is replied to. Leave blank if replies should go to the address already entered in the From email address field.

    • Text-Only Version: A text-only version of the message for email clients that support plain text messages only. Toggle to enable, then enter your text.

    • Transactional: If the message is triggered by a user's action such as a password reset request, opt-in, shopping receipt, etc., flag it as Transactional, and optionally include an Unsubscribe link. Toggle to enable/disable.
  2. Click Test in the header to move on.


Confirm the message design before sending to your users.

  1. Enter key values, then select a radio button for either Email Address or Test Group.
    • Email Address: Enter a valid email address.

      Email addresses entered here are registered with Urban Airship. While registration is generally immediate, processing may cause a minor delay. You may need to send the test message to the address again.

    • Test Group: Select from the dropdown menu.

      In order to send to a test group, you must first create a group of test users. See Audience: Test Groups.

  2. Click Send Test and review the message.

  3. Click Finish in the progress header if the template is ready for use. If you would like to make changes, click the left arrow, complete your edits, and send another test message.

After clicking Finish, you will return to the list of email templates, where your new template will be listed. You'll use that ID when sending your message.

Color Selection

Click the dropdown arrow in the color field to display the color options. You may click to select a color, or enter hexadecimal or RGB color values.

Next Steps

Send an Email Notification

Saved Templates

The list of saved templates has columns for Name, Template ID, Layout, and Creation Date.

The default view of your email templates is sorted by creation date, newest templates first. Click the Creation Date column header to toggle ascending/descending order.

Click an action icon at the end of a template row.

X = Delete template
Deletes the template.
Pencil = Edit template
Opens the template for editing.
Plus sign = Duplicate
Creates a copy of the template and opens it for editing. You must complete the setup steps in order to save the new template. Be sure to give it a name differentiating it from the template you duplicated