Skip to content
Skip to main content

Customize Scheduler email for your app

Last updated:

Scheduler sends booking confirmations for you, and you can’t change their wording or branding. An application-level workflow replaces them with your own HTML, using one template that applies to every user of your product.

This recipe covers the whole booking lifecycle: confirmation, reschedule, cancellation, pending approval, and reminder. If each of your customers needs their own branding, use Customize Scheduler email for each user instead.

A booking confirmation email with a dark green header showing the meeting title, the time in the recipient's timezone, and Reschedule and Cancel meeting buttons, followed by the duration, meeting link, and attendees

How do I replace the Scheduler confirmation email?

Section titled “How do I replace the Scheduler confirmation email?”

Create a template, point an application-level workflow at it, then turn off Nylas’s own email on the Scheduler configuration. The workflow fires for every grant in the application, so one template covers every user.

Start with the template. Set engine to handlebars explicitly, because the API default is mustache and mustache can’t call the formatDate helper you need for times.

curl -X POST 'https://api.us.nylas.com/v3/templates' \
  -H "Authorization: Bearer $NYLAS_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "Booking confirmed",
    "engine": "handlebars",
    "subject": "Confirmed: {{booking_info.title}}",
    "body": "<html>…</html>"
  }'

body is a JSON string, so every quote and line break in the HTML needs escaping. Rather than escaping by hand, let jq build the request from the template file:

jq -n --rawfile body booking-created.html \
  '{name: "Booking confirmed", engine: "handlebars",
    subject: "Confirmed: {{booking_info.title}}", body: $body}' \
| curl -X POST 'https://api.us.nylas.com/v3/templates' \
    -H "Authorization: Bearer $NYLAS_API_KEY" -H 'Content-Type: application/json' \
    -d @-

Then the workflow. delay is in minutes and 0 sends immediately.

The from address decides who the confirmation appears to come from. Omit it and the message sends through the host’s own grant, so the guest sees it arrive from the host’s real address, in the same thread as their other correspondence, with replies landing in the host’s inbox. That needs no domain setup, only mail send scopes on the grant. Set from and it sends through transactional send on a domain you registered, which gives every host the same branding. The Workflows overview compares both.

For booking confirmations the host’s own address is often the better choice, because a confirmation that looks personal gets replied to and a no-reply one doesn’t.

curl -X POST 'https://api.us.nylas.com/v3/workflows' \
  -H "Authorization: Bearer $NYLAS_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "Booking confirmed",
    "trigger_event": "booking.created",
    "template_id": "<TEMPLATE_ID>",
    "delay": 0,
    "is_enabled": true,
    "from": { "email": "[email protected]", "name": "Your Company" }
  }'

Drop the from line entirely to send from the host’s mailbox instead. Everything else stays the same.

Repeat for each of the 5 booking triggers with its own template. booking.rescheduled and booking.reminder drop 4 fields that booking.created carries, and booking.cancelled has no booking_ref, so one shared template throws on whichever trigger lacks a field it references.

How do I stop Nylas sending its own email?

Section titled “How do I stop Nylas sending its own email?”

Set disable_emails: true on the Scheduler configuration. Two fields control this independently, and your choice depends on whether guests also need the calendar provider’s invitation.

disable_emailsnotify_participantsMessages the guest receives
falsefalseNylas Scheduler email plus your workflow email
truefalseYour workflow email only
truetrueYour workflow email plus the Google or Microsoft calendar invitation

Choose notify_participants: true when guests need a calendar reply button and a .ics attachment, which an HTML email can’t provide. The provider sends that invitation from the organizer’s own address rather than from Nylas, so it won’t carry your branding. Microsoft grants ignore notify_participants and always notify, so the workflow-only setup isn’t achievable on Microsoft.

{
  "event_booking": {
    "title": "Meeting with ${invitee}",
    "booking_type": "booking",
    "disable_emails": true,
    "notify_participants": false,
    "reminders": [{ "type": "webhook", "minutes_before_event": 30 }]
  },
  "scheduler": {
    "additional_fields": {
      "notify_individually": {
        "label": "Notify individually",
        "type": "metadata",
        "required": false,
        "default": "true"
      }
    }
  }
}

reminders with type: "webhook" is what makes booking.reminder fire, and without it that trigger never runs. Use booking_type: "organizer-confirmation" for booking.pending, which also requires scheduler.organizer_confirmation_url or the request returns 400. PUT merges your body into the existing configuration, so settings you leave out are kept. The exception is scheduler.additional_fields, which is replaced as a whole: when you add a field, send every field the configuration already has alongside it, or the ones you omit are removed.

How do I address each guest by name?

Section titled “How do I address each guest by name?”

Set notify_individually on the booking. Nylas then sends one message per participant and populates recipient.email, recipient.first_name, and recipient.last_name for each. By default it sends a single message to all participants, leaving recipient undefined so any template referencing it fails to render.

The field has to be declared on the configuration first, as shown above. Passing it on the booking alone returns 400 Additional field 'notify_individually' not found in configuration.

Bookings made on a scheduling page pick up "true" automatically. The booking form doesn’t show a metadata field, but the page sends its default value with the booking when the guest submits. If your own code creates bookings with POST /v3/scheduling/bookings, include the value in the request, because the Bookings API doesn’t read default:

{
  "additional_fields": { "notify_individually": "true" },
  "start_time": 1790182800,
  "end_time": 1790184600,
  "participants": [],
  "guest": { "name": "John Smith", "email": "[email protected]" }
}

A booking with a guest named John Smith and an organizer named Nick then produces 2 messages from one template, reading Hi John, and Hi Nick,.

Do workflows work with Group Configurations?

Section titled “Do workflows work with Group Configurations?”

Yes. booking.created and booking.reminder both fire for group events, and the same templates render them. A Group Configuration keeps its email settings in group_booking instead of event_booking, so set disable_emails and the webhook reminder there:

{
  "group_booking": {
    "booking_type": "booking",
    "calendar_id": "primary",
    "disable_emails": true,
    "reminders": [{ "type": "webhook", "minutes_before_event": 30 }]
  }
}

PUT replaces group_booking as a whole, so send its existing booking_type and calendar_id with your changes. A request that sends event_booking to a Group Configuration returns 400 EventBooking is not supported for Group Events configuration.

Group events differ from other bookings in 3 ways:

  • No calendar invitation. A Group Configuration has no notify_participants, so the workflow email is the only message a guest receives.
  • No recipient. Group bookings don’t populate recipient, even when the booking sets notify_individually, so guests see the template’s fallback greeting.
  • One reminder per session. Scheduler creates the webhook reminder when the first guest books, so booking.reminder fires once per group event, with additional_fields set to null.

How does the template work?

Section titled “How does the template work?”

The template is ordinary HTML with {{variable}} placeholders filled from the event payload. The renderer runs in strict mode, so every value that can be missing is guarded, and every guard has a fallback. Five parts do the real work.

The greeting guards two levels. recipient is absent whenever notify_individually is off, and present but unnamed when a participant has no display name. The renderer throws on a missing parent, so a single guard isn’t enough.

{{#if recipient}}{{#if recipient.first_name}}Hi {{recipient.first_name}},{{else}}Hi,{{/if}}{{else}}Hi,{{/if}}

The time resolves per recipient. booking_info is identical in every copy of a message and only recipient changes between them, so one timezone expression would give every recipient the same zone. lookup works as a nested expression, which is enough to pick a zone per person. Each level has its own {{else}}, so the time still renders when recipient or additional_fields is missing.

{{#if recipient}}{{#if booking_info.additional_fields}}{{#if (lookup booking_info.additional_fields recipient.email)}}
  {{ formatDate booking_info.start_time (lookup booking_info.additional_fields recipient.email) "DDDD, t ZZZZ" booking_info.guest_language }}
{{else}}
  {{#if booking_info.guest_timezone}}{{ formatDate booking_info.start_time booking_info.guest_timezone "DDDD, t ZZZZ" booking_info.guest_language }}{{else}}{{ formatDate booking_info.start_time booking_info.organizer_timezone "DDDD, t ZZZZ" booking_info.guest_language }}{{/if}}
{{/if}}{{else}}
  {{#if booking_info.guest_timezone}}{{ formatDate booking_info.start_time booking_info.guest_timezone "DDDD, t ZZZZ" booking_info.guest_language }}{{else}}{{ formatDate booking_info.start_time booking_info.organizer_timezone "DDDD, t ZZZZ" booking_info.guest_language }}{{/if}}
{{/if}}{{else}}
  {{#if booking_info.guest_timezone}}{{ formatDate booking_info.start_time booking_info.guest_timezone "DDDD, t ZZZZ" booking_info.guest_language }}{{else}}{{ formatDate booking_info.start_time booking_info.organizer_timezone "DDDD, t ZZZZ" booking_info.guest_language }}{{/if}}
{{/if}}

The complete templates wrap this in {{#if booking_info.guest_language}} and repeat it with "en" as the locale in the {{else}}, because a missing locale also fails the render.

That resolves in 4 steps: the recipient’s own timezone, then guest_timezone, then organizer_timezone, then UTC. guest_timezone is only set when the guest supplies one and is an empty string otherwise, which formatDate would silently treat as UTC, so the {{#if}} skips it when empty. organizer_timezone carries the configuration’s event_booking.timezone, and if that’s empty too, formatDate uses UTC. A value that isn’t a valid IANA timezone fails the render, so check the per-recipient values before you send them.

Supply the per-recipient dictionary in the booking request. It’s different for every booking, so it can’t come from a configuration default. Email addresses are valid field keys.

"additional_fields": {
  "notify_individually": "true",
  "[email protected]": "America/Chicago",
  "[email protected]": "America/New_York"
}

One booking with a host in America/Chicago and a guest in America/New_York then produces 1:00 PM EDT for the guest and 12:00 PM CDT for the host, from the same template. Leave the guest out of the dictionary and they get organizer_timezone instead, because guest_timezone is empty on bookings made through the API.

Dates follow the guest’s language. formatDate takes a timestamp, an IANA timezone, a Luxon token string, and a locale, and all 4 accept variables. DDDD and t are Luxon’s localized date and time tokens, so passing booking_info.guest_language renders miércoles, 23 de septiembre de 2026, 19:00 CEST for es in Europe/Madrid and Mittwoch, 23. September 2026, 19:00 MESZ for de in Europe/Berlin, each with that language’s clock format. The template’s own copy is English. To translate it, branch on the language with eq:

{{#if (eq booking_info.guest_language "es")}}Reunión confirmada{{else if (eq booking_info.guest_language "fr")}}Rendez-vous confirmé{{else}}Your meeting is confirmed{{/if}}

Optional fields and actions are wrapped. location, duration, event_description, old_start_time, and cancellation_reason can each be missing or empty, so each detail row sits inside {{#if}} and disappears cleanly rather than failing the render or leaving a dangling label. The Reschedule and Cancel buttons check both the URL and the configuration’s hide_rescheduling_options and hide_cancellation_options, so a configuration that hides them doesn’t get them back in email. event_description is the calendar event description that Scheduler writes: the configuration’s description followed by its own meeting, reschedule, and cancel links, as HTML. The template renders it with triple braces, {{{booking_info.event_description}}}, because double braces would escape the HTML and show raw tags.

{{#unless booking_info.hide_cancellation_options}}{{#if booking_info.participant_cancellation_url}}
  <a href="{{booking_info.participant_cancellation_url}}">Cancel meeting</a>
{{/if}}{{/unless}}

Long values wrap. Titles, email addresses, and meeting links can be any length, so the headline and detail cells set word-break: break-word and the link sets break-all. A 300-character title or a 40-person attendee list wraps inside a 320px screen instead of forcing a horizontal scroll.

Section titled “How do I show each user’s logo?”

Store each user’s logo URL in a hidden metadata field on their Scheduler configuration, and read it in the template. When a booking has no logo, the template falls back to your own default. One application-level workflow still covers every user.

  1. Host the user’s logo anywhere public, such as your own storage or the user’s website.

  2. Add a logo_url field to the user’s configuration, with the URL in default:

    {
      "scheduler": {
        "additional_fields": {
          "notify_individually": {
            "label": "Notify individually",
            "type": "metadata",
            "required": false,
            "default": "true"
          },
          "logo_url": {
            "label": "Logo URL",
            "type": "metadata",
            "required": false,
            "default": "https://cdn.example.com/customers/acme/logo.png"
          }
        }
      }
    }

    scheduler.additional_fields is replaced as a whole on update, so include your existing fields, such as notify_individually.

  3. Use this block for the logo in each booking template. The complete templates below already include it:

    {{#if booking_info.additional_fields}}{{#if booking_info.additional_fields.logo_url}}
      <img src="{{booking_info.additional_fields.logo_url}}" alt="Company logo" style="max-width: 150px;" />
    {{else}}
      <img src="https://cdn.example.com/brand/default-logo.png" alt="Company logo" style="max-width: 150px;" />
    {{/if}}{{else}}
      <img src="https://cdn.example.com/brand/default-logo.png" alt="Company logo" style="max-width: 150px;" />
    {{/if}}

Bookings made on a scheduling page get the user’s logo automatically. If your own code creates bookings through the Bookings API, pass logo_url in the request’s additional_fields, or the email shows your default. Group-event reminders also show the default, because they carry no additional_fields.

Use metadata in workflow templates covers other values you can pass this way and which ones are safe to store.

The complete template

Section titled “The complete template”

This is the booking.created template from the screenshot above. The other 4 booking triggers follow the same structure with their own fields.

Render each one with POST /v3/templates/render before enabling its workflow. A missing variable returns 400 and sends nothing, with no error on the booking request, so Why isn’t my workflow sending email? is worth reading before you go live.

What’s next

Section titled “What’s next”