How to customize the Scheduler booking confirmation email

Overview

Nylas Scheduler sends a default confirmation email after each booking, which includes the following sentence:

"You're booked! You're meeting on [date]."

 

This article explains why this wording is used and how to replace the default emails with your own content and design using email templates and workflows.
 

This approach works whether you use the Scheduler API or the Scheduler and Scheduler Editor components. If you use the components, see section 4 for how to turn off the default emails without API calls for each configuration.

1. About the default wording

The default confirmation email includes the sentence:

"You're booked! You're meeting on [date]."

This is correct English. "You're" is the contraction of "you are", so the sentence reads "You are meeting on [date]". It is the intended wording, not a misspelling of "your".

The default email can be adjusted in two limited ways:

• Change the email title.
• Add an extra paragraph.

You can configure these using scheduler.email_template.booking_confirmed on the configuration or the Communications tab in the Scheduler Editor.

These options do not replace the main sentence or the rest of the email body.

If you need different wording, your own branding, or a completely different layout, you can replace the default emails with your own templates.

2. How it works

Booking emails are not sent by the Scheduler or Scheduler Editor components. They are sent by Nylas after a booking is created, rescheduled, or cancelled.

This means you can replace them without changing your components.

1. A guest books a meeting through your Scheduler page or component.
2. Nylas creates the booking and triggers a booking.created event.
3. A workflow listening for booking.created sends your custom email template.
4. The default Nylas email is disabled on the configuration, so guests only receive your custom email.

You need three things:

• An email template (created once per application).
• A workflow that sends the template (created once per application).
• Default emails turned off on each Scheduler configuration.

3. Step-by-step setup

Note: The examples below use the US region. Replace api.us.nylas.com with api.eu.nylas.com if your application is in the EU region.

Step 1. Create your email template

Set the template engine to handlebars so you can use helpers such as formatDate.

curl --request POST 'https://api.us.nylas.com/v3/templates' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Booking confirmation",
    "engine": "handlebars",
    "subject": "{{#if booking_info.title}}Booking confirmed: {{booking_info.title}}{{else}}Booking confirmed{{/if}}",
    "body": "<p>{{#if recipient}}{{#if recipient.first_name}}Hi {{recipient.first_name}},{{else}}Hi,{{/if}}{{else}}Hi,{{/if}}</p><p>Your meeting is confirmed.</p>"
  }'

Save the id returned in the response. You will need it when creating the workflow.

Step 2. Test the template

Render the template with sample data before using it. A missing or misspelled variable returns an error during rendering, allowing you to catch problems before activating the workflow.

curl --request POST 'https://api.us.nylas.com/v3/templates/render' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "engine": "handlebars",
    "subject": "Booking confirmed: {{booking_info.title}}",
    "body": "<p>Hi {{recipient.first_name}},</p><p>Your meeting is confirmed.</p>",
    "variables": {
      "booking_info": {
        "title": "Test meeting"
      },
      "recipient": {
        "first_name": "Sam"
      }
    }
  }'

Step 3. Create the workflow

Create a workflow that sends your template whenever a booking is created.

curl --request POST 'https://api.us.nylas.com/v3/workflows' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Booking confirmation",
    "trigger_event": "booking.created",
    "template_id": "<TEMPLATE_ID>",
    "delay": 0,
    "is_enabled": true
  }'

Templates and workflows are created at the application level, so one workflow covers every Scheduler configuration in your application.

Steps 1 to 3 are a one-time setup, even if you use the components.

Step 4. Turn off the default Nylas emails

Turn off the default emails on each Scheduler configuration that should use your custom template.

If you use the Scheduler Editor component, you can do this from the Editor instead. See section 4.

curl --request PUT 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_booking": {
      "disable_emails": true,
      "notify_participants": true
    }
  }'

Important:

• Set disable_emails inside event_booking (or group_booking for group configurations). A disable_emails field placed anywhere else, such as under scheduler, is ignored without an error, and the default emails keep sending.
• Keep notify_participants set to true so guests still receive the calendar invitation. disable_emails only controls the Nylas emails. notify_participants controls the calendar invitation sent by the organizer's calendar provider.

With notify_participants: false on a Google organizer, guests do not receive an invitation, and guests on other providers (for example, Outlook) do not get the event on their calendar.

Microsoft organizers always send the invitation, whatever this setting is.

Step 5. Test with a booking

Create a test booking using the updated configuration.

The guest should receive your custom email template and the calendar invitation, and should not receive the default "You're booked!" confirmation email.

4. Using the Scheduler and Scheduler Editor components

If your organizers create and edit their Scheduler configurations through the Scheduler Editor component, you do not need to call the API for each configuration.

Turn off the default emails for one configuration

In the Scheduler Editor:

1. Open the configuration.
2. Go to the Communications tab.
3. Turn off Enable email notifications.

When this is off, Nylas stops sending its default booking emails for that configuration.

The custom email title and additional info fields are also hidden because they only apply to the default email.

Turn off the default emails for every new configuration

Set event_booking.disable_emails in the Editor's defaultSchedulerConfigState.

New configurations created in the Editor then start with Enable email notifications turned off.

schedulerEditor.defaultSchedulerConfigState = {
  selectedConfiguration: {
    event_booking: {
      disable_emails: true,
      notify_participants: true
    },
    scheduler: {
      additional_fields: {
        notify_individually: {
          label: "Notify individually",
          type: "metadata",
          required: false,
          default: "true"
        }
      }
    }
  }
};

In React, pass the same object to the defaultSchedulerConfigState prop of NylasSchedulerEditor.

If you already set defaultSchedulerConfigState (for example, for rescheduling_url and cancellation_url), add event_booking and additional_fields to the same selectedConfiguration object.

The notify_individually field lets your template greet each recipient by name. See section 5.

Existing configurations

defaultSchedulerConfigState only applies to new configurations.

For configurations that already exist, either:

• Turn off Enable email notifications in the Editor for each one.
• Update them using the API request in Step 4.

Keep in mind

• Every time a configuration is saved in the Editor, the Editor sends the current value of Enable email notifications. If an organizer turns it back on, the default Nylas email is sent again together with your custom email.
• If you don't want organizers to change this setting, hide the Communications tab with the Editor's hideEditorTabs property, for example hideEditorTabs: ['communications']. The configuration keeps the value you set.

5. Greet each recipient by name

By default, a booking workflow sends one shared email to all participants (the guest and the organizer).

Because the email has more than one recipient, recipient is empty, and a greeting such as Hi {{recipient.first_name}}, falls back to "Hi,".

To send a separate email to each participant with their own name, enable notify_individually.

Step 1. Declare the field on the configuration

Passing it on a booking without declaring it first returns:

400 Additional field 'notify_individually' not found in configuration

curl --request PUT 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduler": {
      "additional_fields": {
        "notify_individually": {
          "label": "Notify individually",
          "type": "metadata",
          "required": false,
          "default": "true"
        }
      }
    }
  }'

Note: scheduler.additional_fields is replaced as a whole. If the configuration already has other additional fields, include them in the same request.

If you use the Scheduler Editor, you can add the field for every new configuration through defaultSchedulerConfigState. See section 4.

Step 2. Make sure bookings include it

Bookings made through the Scheduler component or a hosted scheduling page send the field's default value automatically, and the field is not shown to the guest.

Bookings created with POST /v3/scheduling/bookings do not, so add it to the request:

{
  "additional_fields": {
    "notify_individually": "true"
  }
}

Where the names come from

If the organizer's participant entry has no name, the organizer still receives their own email, but the greeting falls back to "Hi,".

The name on the connected account is not used.

6. Example template with custom wording and colors

The following example keeps a layout similar to the default confirmation email while allowing you to customize the wording and colors.

Every variable is wrapped in a conditional check to prevent missing fields from causing rendering errors.

<h1 style="font-weight:400; color:#d32f2f;">
  Booking Confirmed
</h1>

<p>
  {{#if recipient}}
    {{#if recipient.first_name}}
      Hi {{recipient.first_name}},
    {{else}}
      Hi,
    {{/if}}
  {{else}}
    Hi,
  {{/if}}
</p>

<p style="color:#d32f2f; font-weight:bold;">
  Your meeting is confirmed for
  {{#if booking_info.guest_timezone}}
    {{formatDate booking_info.start_time booking_info.guest_timezone "ccc, LLL d, yyyy t" "en"}}
  {{else}}
    {{#if booking_info.organizer_timezone}}
      {{formatDate booking_info.start_time booking_info.organizer_timezone "ccc, LLL d, yyyy t" "en"}}
    {{else}}
      {{formatDate booking_info.start_time "UTC" "ccc, LLL d, yyyy t" "en"}} UTC
    {{/if}}
  {{/if}}.
</p>

<table>
  {{#if booking_info.title}}
  <tr>
    <td style="color:#999;">What</td>
    <td>{{booking_info.title}}</td>
  </tr>
  {{/if}}

  {{#if booking_info.location}}
  <tr>
    <td style="color:#999;">Where</td>
    <td>{{booking_info.location}}</td>
  </tr>
  {{/if}}

  {{#if booking_info.duration}}
  <tr>
    <td style="color:#999;">Duration</td>
    <td>{{booking_info.duration}} minutes</td>
  </tr>
  {{/if}}

  {{#if booking_info.participants}}
  <tr>
    <td style="color:#999;">Who</td>
    <td>
      {{#each booking_info.participants}}
        {{#if name}}
          {{name}}
        {{else}}
          {{#if email}}{{email}}{{/if}}
        {{/if}}
        <br/>
      {{/each}}
    </td>
  </tr>
  {{/if}}
</table>

<p>
  {{#if booking_info.participant_cancellation_url}}
    <a href="{{booking_info.participant_cancellation_url}}">
      Cancel
    </a>
  {{/if}}

  {{#if booking_info.participant_rescheduling_url}}
    |
    <a href="{{booking_info.participant_rescheduling_url}}">
      Reschedule
    </a>
  {{/if}}
</p>

Send the HTML as the template body, encoded as a single JSON string.

You can change the sentence, colors, and layout to match your branding.

Available template variables

7. Replacing other booking emails

Turning off the default emails on a Scheduler configuration turns off all of them, including rescheduling, cancellation, and reminder emails.

To continue sending these notifications, create a separate template and workflow for each event type.

Additional event-specific variables

• booking_info.old_start_time: Previous meeting time, available for rescheduled bookings.
• booking_info.cancellation_reason: Cancellation reason, when provided.

The booking.reminder trigger only runs if the configuration has a webhook reminder configured, for example:

{
  "event_booking": {
    "reminders": [
      {
        "type": "webhook",
        "minutes_before_event": 30
      }
    ]
  }
}

Use a separate template for each trigger, since some fields are only available for certain events.

For example, booking.cancelled does not include booking_ref.

Example cancellation email

<p>
  {{#if recipient}}
    {{#if recipient.first_name}}
      Hi {{recipient.first_name}},
    {{else}}
      Hi,
    {{/if}}
  {{else}}
    Hi,
  {{/if}}
</p>

<p>
  Your meeting{{#if booking_info.title}}
  "{{booking_info.title}}"{{/if}}
  has been cancelled.
</p>

{{#if booking_info.cancellation_reason}}
<p>
  Reason: {{booking_info.cancellation_reason}}
</p>
{{/if}}

8. Things to keep in mind

Guard every variable

Templates are rendered in strict mode.

If a variable is missing from the booking data and is not wrapped in an {{#if}} check, the email is not sent, even though the booking itself succeeds.

Check each level separately, for example {{#if recipient}} and then {{#if recipient.first_name}}.

Timezones can be empty

booking_info.guest_timezone is not always populated.

Use booking_info.organizer_timezone as a fallback, followed by a fixed timezone such as UTC.

All participants receive the email

Booking workflows send emails to all participants, including the organizer.

By default, everyone receives one shared email and recipient is empty.

With notify_individually enabled, each participant receives their own copy and recipient is filled in for each one. See section 5.

Sender address

By default, the email is sent from the organizer's email account. This works for both Google and Microsoft organizers.

To send from your own address instead, add a from object containing the email address and name to the workflow.

The sender address must belong to a domain verified for transactional sending.

Calendar invitations

Calendar invitations are sent by the organizer's calendar provider, not by Nylas.

disable_emails does not affect them, but notify_participants does.

Keep notify_participants set to true. See Step 4.

Configuration-level and application-level settings

• disable_emails, notify_participants, and notify_individually are set individually on each Scheduler configuration, through the API or the Scheduler Editor.
• Templates and workflows apply at the application level.

9. Troubleshooting

If your custom email is not received, follow these steps.

1. Check workflow logs

In the Nylas Dashboard, navigate to Logs → System and filter by Source: Workflows.

Each skipped send includes a reason. Logs are retained for 14 days.

2. Check for template rendering errors

If the logs indicate a missing variable or rendering error:

• Add {{#if}} checks around the affected variable.
• Test the template using POST /v3/templates/render.
• Retry the booking.

3. Verify the workflow configuration

Confirm that is_enabled is set to true and that trigger_event matches the intended booking event.

4. Confirm the template engine

Verify that the template engine is set to handlebars.

The default engine, mustache, does not support helpers such as formatDate.

5. Check the organizer's grant

If the logs indicate that the grant is invalid or lacks the required email-sending scopes:

• Confirm the organizer's account is connected.
• Verify that the account has permission to send email.
• If the account is valid and the email is still skipped, contact Nylas Support with the workflow ID and booking ID.

6. Guests still receive the default "You're booked!" email

• Confirm the configuration returns "disable_emails": true inside event_booking using GET /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>.
• If it shows null or false, the setting was not saved, for example because it was sent under scheduler instead of event_booking.
• If you use the Scheduler Editor, check that Enable email notifications is off in the Communications tab. Saving a configuration in the Editor overwrites the value with whatever the switch shows.
• Confirm that you do not have more than one enabled workflow for the same trigger event.

7. Guests don't receive a calendar invitation

Confirm notify_participants is true inside event_booking on the configuration.

8. The greeting shows "Hi," without a name

If the email arrives but does not include the recipient's name:

• Confirm notify_individually is declared in scheduler.additional_fields on the configuration.
• For bookings created with POST /v3/scheduling/bookings, include "additional_fields": {"notify_individually": "true"} in the request.
• For the guest, confirm a name was entered when booking (guest.name).
• For the organizer, confirm name is set on the organizer's entry in the configuration's participants.

Related documentation

• Customize Scheduler email for your app
• Why isn't my workflow sending email?
• Templates and workflows
• Customize your Scheduler implementation

Updated October 19, 2026 17:47