More topics

Designing your emails

Last updated on November 24, 2024

You can set up multiple emails notifications for your form, and even control which emails go out and when.

On this page:

Overview

By default, Orbeon will send out at least one email with each form submission. You can customize and manage these emails using templates in the Email Settings.

To access the email templates:

  1. Click Advanced on the Toolbar
  2. Click Email Settings

The Email Settings window will be displayed.

For additional information, see:

Outlook considerations

Some program areas have an autoresponse set up on their email inbox. If they do, an adjustment may be needed to avoid redundant or confusing communications.

Consider options such as:

  • Discontinuing the use of the autoresponse
  • Creating a rule that does not respond to the Form Handler Application email address
  • Creating a rule that discards autoresponses mailed to the program area
  • Establishing separate email address for form submissions and general inquiries

Separate email addresses might be the best option:

  • Submissions don't get responded to regardless of the originator
  • Reply to addresses could be directed to the general email and be responded to

Design considerations

Before creating your templates, there are a few things to consider for your email design. These can be considered for a particular form, or be included in ministry practices, guidelines and even form templates.

Template names

Template names are primarily used for your convenience to help you distinguish one template from another. To assist you and any team members, you can establish a naming pattern for templates similar to how you might for control names.

Consider using a pattern like:

  • Identifying the recipient such as:
    • "PROG" for program emails
    • "CITZ" for citizen emails
  • Identifying a key characteristics such as:
    • "with PDF" to indicate the form is included
    • "no PDF" to indicate the form is not included

You can prename email templates and include them as part of a form template.

For additional information, see:

Template parameters

If you want to personalize email subjects or body content, you'll need to set up template parameters.

On the design side of things, you'll want to:

  • Identify what data you'll want to include
  • What you want to call these data elements
  • Which control they'll connect to or other setting they'll employ

Parameters you establish can be used across all the email templates in all their languages (if applicable).

  • You can also set up common parameters as part of a form template

For additional information, see:

How many templates to create

In general, you'll want at least 2 templates:

  • One for the program area with most or all attachments
  • One for the citizen with fewer or no attachments

You'll need to add one or more if you are using conditions as well. For example, if you want to give the citizen the choice of receiving a PDF copy of the form by email, you'll need one for each condition.

  • A citizen email with no attachments
  • A citizen email with just the form PDF attached

You can create as many templates as needed based on things like:

  • Intended recipient
  • Conditions applied
  • How your API is set up

For additional information, see:

How APIs can affect design choices

Email template names are primarily for your and your team's convenience. But not all forms will send data to program areas by email.

If you are having data sent to an API instead, you'll need to:

  • Consider how notifications will be applied for the form
  • Create a "recovery email" in case something happens with the API send
  • Advise GDX if you are changing the name of the email template

The backgroud server-side process that sends data to your API will send specific emails using their template name. If you add a template or change a name, the process will need to be updated accordingly.

For additional information, see:

Settings guidance

There are many options for how you set up an individual template, and you'll want to ensure information security and privacy for citizens. Errors made in setting up a template may lead to an information incident. While some setting choices may seem obvious, some are not. This section provides guidance on the available options with focus on information security and privacy.

For additional information, see:

Email template name

You can give your template any name that is useful to you or your team. Consider a designed pattern for ease and consistency.

Enable this template...

You can specify when this template is used by Orbeon using a boolean ('true'/'false) formula.

To use a condition:

  1. Select the checkbox to the left of "Enable this template only..."
  2. Enter a boolean ('true'/'false') expression for Orbeon to evaluate

Keep in mind that:

  • If there is no condition set, Orbeon will send the email
  • If you want Orbeon to only send one of 2 or more templates, each template will need a different condition applied

Addressing emails correctly

Email addressing is a common source of information incidents.

  • Emails go to a non-existent or incorrect address
  • Citizens reply to emails that go to a non-existent or incorrect address

Following the recommendations in this section will help prevent these issues.

To address an email:

  1. Click the plus icon to the right of the addressing line (under the conditional field)
  2. Select the addressee type, such as Sender or Recipient
  3. Select the Control Value that holds the email address to use
  4. Repeat steps 1-3 for additional addressees

Every email needs to be addressed to a Recipient. If you forget and Orbeon attempts to use the template, the citizen will get a process error.

For additional information, see:

Addressing program emails

For emails to the program area:

  • The Sender MAY be absent to use the default Form Handler Application email address
    • This can make submissions easier to identify and filter using rules in Outlook
    • The GDX team would get notifications if there is something wrong with the program's mailbox
  • The Recipient MUST be a group mailbox controlled by the program area
    • Do not use email addresses for individuals as they may be unavailable
  • The Reply to MAY use the citizen's email address
    • This makes it easier to reply to the citizen, if part of your process

Addressing citizen emails

For emails to the citizen:

  • The Sender MUST be the program area's group mailbox
    • DO NOT use a "do not reply" or the default Form Handler Application email address
    • The program area needs to receive notifications of issues with citizen emails
    • The program area needs to receive any replies or follow-ups from the ctizen
  • The Reply to SHOULD be absent
    • This is only used to direct notifications and replies to an address different than the Sender

Email subject

You have 3 choices when it comes to the email subject line:

  • The default subject of "Here is your confirmation:"
  • A static typed subject
  • A dynamic subject that uses templated information

To override the default subject:

  1. Deselect the checkbox to the left of "Email Subject"
  2. Enter a subject in the space provided

For additional information, see:

Program email subject suggestions

Consider including some or all of the following in your email subject:

  • Form title, number, or submission type
  • The name of the submitting individual or organization

If you have a piece of unique and stable information provided in the email subject, you can apply filtering and rules in Outlook.

Citizen email subject suggestions

Consider providing citizens with a subject line that's more specific, such as:

  • "Thank you for your feedback on your {service name} experience"
  • "Your {program name} grant application has been received"
  • "{Organization name} funding request"

If the individual prepares a number of forms, being more specific can help them locate the desired response in their mailbox.

Email body

You have 3 choices when it comes to the email body:

  • The default body of "Please find attached a form submitted by a user."
  • A static typed body
  • A dynamic body that uses templated information

To override the default body:

  1. Deselect the checkbox to the left of "Email Body"
  2. (Optional) Select the "Use HTML" option to use rich text formatting
  3. Enter body text in the space provided

For additional information, see:

Program email body suggestions

Consider including the following in the body of program emails:

  • Contact name for the program
  • The full name of the submitter
  • Their email address
  • Their phone number

In the event that the program's email address is incorrect or something else is wrong, this content will be included in system messages that may be received by GDX. If you or we discover the issue, we can at least let you know who was affected and you can contact the individual directly to resolve.

Citizen email body suggestions

Consider including the following in the body of citizen emails:

  • A greeting using their name
  • The name and purpose of the form they submitted
  • When they can expect a response, and how
  • What to do if they do not get a response in the expected time frame
  • Links to program information
  • Links to other services they might be interested in

In summary, this content describes:

  • What has happened
  • What is expected to happen next
  • What they could do in the meantime
  • What to do if something doesn't happen

Attach form as

This section allows you to control whether or not a PDF or XML copy of the form is attached to the email.

PDF forms are:

  • Autogenerated based on the forms design or uploaded PDF template
  • Generally useful to both program areas and citizens
  • Included by default

XML forms are:

  • Useful for importing into spreadsheets or databases
  • Generally only useful to program areas
  • Included by default

To change the default setting for either:

  1. Deselect the Use default option
  2. Select "Yes" or "No"

Default settings are on the server side and not visible to you, therefore you can specify either "Yes" or "No" to override whatever the default setting is.

It's a good practice to specify "Yes" or "No" to:

  • Make it clear what the intent or choice is
  • Avoid having to change this if the default setting is changed

For additional information, see:

Attach files users uploaded to the form

The quantity and size of attachments is another potential cause of information incidents. Most email providers limit the total size of incoming emails, and some of these limits are quite low. If the message is too large, the notification will be rejected and the citizen will not receive their notification. In some cases, this causes citizens to repeatedly submit their form.

For additional information, see:

Attached files for programs

Program areas will need a copy of all attachments uploaded by the citizen.

  • Use the default setting, or
  • Specify "All"

Attached files for citizens

It's receommended that you DO NOT include any attachments uploaded by the citizen to their email.

  • It increases the total size of the email, potentially causing the email to be rejected by their email provider
  • They already have copies of the information attached
  • Some information may be included or embedded within the form itself, adding to the overall size

Selected attachments

You can specify that only certain uploaded attachments are included using the "Selected attachments" option.

  • Click the plus icon to the right add an attachment line
  • This works just like template and addressing options
  • Add the attachment(s) you want

You may want to consider this for some attachments that are temporary in nature, such as a provided screenshot, receipt from another system, or similar; but also keep in mind that message size will increase.

Exclude from All Control Values

In the Template parameters tab there is an added option to the dropdown list: All Control Values.

  • You can set up a single name such as all-data
  • You can use that name to display all the data from the form in an email

This section allows you to specify which fields you DO NOT want to include with all the values. You may want to trim out things like:

  • A field that is redundant, such as an orginal and it's tranformed version
  • Extra fields added to the form for layout purposes (if they are appearing in All Control Values)
  • Any switch- or path-like controls that only support the experience and don't include useful data

This function is similar the default functioning of older form platforms, though with greater control, and can still be useful in some scenarios.