Creating an Email Notification

This guide shows how to create an email notification that sends a welcome email to a newly signed-up user.

Prerequisites

To follow the steps in this tutorial, you must understand notifications. You use the sign-up form you created in a previous tutorial.

• Form Configuration Options
• Notifications
• Creating a Sign-Up Form

Steps

Creating an email notification has three steps:

• Step 1: Create an email notification
• Step 2: Send the notification with the GraphQL email_send mutation
• Step 3: Connect the notification to the sign-up form

Step 1: Create an Email Notification

app/emails/welcome_user.liquid

---
to: '{{ form.email }}'
from: 'My Site <no-reply@insites.site>'
reply_to: hello@example.com
subject: 'Welcome to our platform, {{ form.first_name }}!'
layout: mailer
---
<h2>Hi {{ form.first_name }}!</h2>

<p>Welcome to our platform!</p>

Set reply_to to a mailbox that someone reads, because no-reply@insites.site has no inbox.

Choosing the From Address

The From address must be one your instance can send from:

• no-reply@insites.site, which every production instance can use, or
• an address at a domain connected to the instance whose email notifications are live, such as hello@acme.com.

An email from any other address is refused and does not arrive. The name before the address, such as My Site, is what the recipient sees. To send from your own domain, see Sending Email from Your Own Domain.

Step 2: Send the Notification with GraphQL

Save this mutation as app/graphql/notify.graphql:

mutation notify($tpl: String!, $data: HashObject) {
  email_send(template: { name: $tpl }, data: $data) {
    is_scheduled_to_send
  }
}

Every value you pass as the data argument can be read in the email notification as data, or as form to match a form. Prepare the data object and run the mutation:

{%- liquid
  assign data = {}
  assign data.email = 'michael@email.com'
  assign data.first_name = 'Michael'
-%}
{%- graphql notify = 'notify', tpl: 'welcome_user', data: data -%}

is_scheduled_to_send: true means the email was queued. It does not prove the email arrived.

Step 3: Connect the Notification to the Sign-Up Form

Edit the forms/developer/sign_up.liquid file to connect the email to it. The email notification name is the file path relative to the emails directory, without the extension.

For app/emails/welcome_user.liquid, the part in bold is the name.

resource: User
email_notifications:
  - welcome_user

Newly registered users receive the email when they submit the form.

Note: On a staging instance, emails do not go to the real recipients. They go only to the test email recipients you set, so you must configure your test emails first. A staging instance sends from no-reply@staging.insites.site.

Next Steps

You have created an email notification. Now you can learn about using email layouts: Using Email Layouts