Using templates and workflows in Nylas

The Nylas Templates and Workflows endpoints work together to enable custom message flows triggered by specific events.

How templates and workflows work

You can create templates and workflows associated with either a Nylas application or a specific grant. For the purposes of this documentation, we reference the application-level Templates and Workflows endpoints.

You can use the Templates endpoints to create and manage reusable email templates with custom variables. When you create a template, you specify its content and the templating engine to use when rendering it.

curl --request POST \
  --url "https://api.us.nylas.com/v3/templates" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "body": "<p>Hello, {{user.name}}. I'm testing templates from Nylas.</p>",
    "name": "Testing template",
    "subject": "Testing Nylas templates",
    "engine": "mustache"
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "app_id": "6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb",
    "body": "<p>Hello, {{user.name}}. I'm testing templates from Nylas.</p>",
    "created_at": 1640995200,
    "engine": "mustache",
    "id": "b79c82b2-a51b-4c54-8469-28006a43551a",
    "name": "Testing template",
    "object": "template",
    "subject": "Testing Nylas templates",
    "updated_at": 1640995200
  }
}

Nylas supports the following templating engines:

After you create a template, you can pass its ID in a Create Workflow request to define the message the workflow sends.

curl --request POST \
  --url "https://api.us.nylas.com/v3/workflows" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "delay": 5,
    "is_enabled": true,
    "name": "Test workflow",
    "template_id": "b79c82b2-a51b-4c54-8469-28006a43551a",
    "trigger_event": "message.created"
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "app_id": "6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb",
    "date_created": 1756477389,
    "delay": 5,
    "id": "b79c82b2-a51b-4c54-8469-28006a43551a",
    "is_enabled": true,
    "name": "Test workflow",
    "template_id": "b79c82b2-a51b-4c54-8469-28006a43551a",
    "trigger_event": "message.created"
  }
}

Format dates and times in templates

When you create a template, you might want to show a date or time in it given a Unix timestamp. Nylas supports formatDate, a helper function for Handlebars, Nunjucks, and Twig that renders dates and times from a Unix timestamp.

mustache }} doesn’t support helper functions. If you choose to use it to render your templates, it won’t format Unix timestamps as a date or time.

formatDate accepts the following parameters:

Parameter	Description	Default
`timestamp` *	The time to render, in seconds using the Unix timestamp format.	—
`timezone`	The IANA-formatted time zone used to calculate the output.	`"UTC"`
`format`	The output format. Supports the options described in the Luxon library.	`"fff"`
`locale`	The output language. Supports the language codes defined in ISO 639.	`"en"`

When you use formatDate, the ordering of its parameters matters. If you want to use only one optional parameter, you need to pass null for the other options. When a parameter is null, Nylas uses its default value.

Format dates and times in Handlebars templates

formatDate follows the {{ formatDate timestamp timezone format locale }} format in Handlebars templates.

curl --location 'https://api.us.nylas.com/v3/templates/render' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "body": "The event is on {{ formatDate event.ts event.tz null \"en\" }}.",
    "engine": "handlebars",
    "variables": {
      "event": {
        "ts": 1758978000,
        "tz": "America/Toronto"
      }
    }
  }'

Format dates and times in Nunjucks and Twig templates

formatDate follows the {{ timestamp|formatDate(timezone, format, locale) }} format in Nunjucks and Twig templates.

curl --location 'https://api.us.nylas.com/v3/templates/render' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "body": "The event is on {{ event.ts|formatDate(event.tz, null, \"en\") }}.",
    "engine": "nunjucks",
    "variables": {
      "event": {
        "ts": 1758978000,
        "tz": "America/Toronto"
      }
    }
  }'

Use notification data in template variables

Workflows support all notifications that Nylas sends. When an event triggers a workflow, Nylas automatically includes the information from its data object as a set of template variables. For example, if your project receives a booking.created notification, you can access its information in your template.

{
  "specversion": "1.0",
  "type": "booking.created",
  "source": "/nylas/passthru",
  "id": "<WEBHOOK_ID>",
  "time": 1725895310,
  "webhook_delivery_attempt": 1,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "grant_id": "<NYLAS_GRANT_ID>",
    "object": {
      "booking_id": "<BOOKING_ID>",
      "booking_ref": "<BOOKING_REFERENCE>",
      "configuration_id": "<CONFIGURATION_ID>",
      "object": "booking",
      "booking_info": {
        "event_id": "<EVENT_ID>",
        "start_time": 1719842400,
        "end_time": 1719846000,
        "participants": [
          {
            "email": "[email protected]",
            "name": "Leyah Miller"
          },
          {
            "email": "[email protected]",
            "name": "Nyla"
          }
        ],
        "additional_fields": {
          "phone": "+1-415-555-0137",
          "company": "Nylas Inc."
        },
        "hide_cancellation_options": false,
        "hide_rescheduling_options": false,
        "participant_rescheduling_url": "https://example.com/reschedule/<BOOKING_REFERENCE>",
        "participant_cancellation_url": "https://example.com/cancel/<BOOKING_REFERENCE>",
        "host_language": "en",
        "guest_language": "en",
        "title": "Project sync with Leyah",
        "duration": 60,
        "location": "https://meet.google.com/abc-defg-hij",
        "organizer_timezone": "America/Toronto",
        "guest_timezone": "America/Toronto",
        "is_group_event": false,
        "organizer_calendar_id": "primary",
        "event_description": "Discuss Q3 roadmap and next steps",
        "event_html_link": "https://calendar.google.com/calendar/event?eid=abc123",
        "ical_uid": "040000008200E00074C5B7101A82E0080000000000000000000000000000000000",
        "host_confirmation_url": "https://example.com/confirm/<BOOKING_REFERENCE>"
      }
    }
  }
}

Your meeting for <b>{{ booking_info.title }}</b> is scheduled on {{ booking_info.start_time|formatDate(booking_info.guest_timezone) }}.

If you need to reschedule, <a href="{{ booking_info.participant_rescheduling_url }}">click here</a>.

Personalize notifications

If you’re sending notifications to a single recipient, Nylas automatically passes their email address, first name, and last name to the template as a set of variables: recipient.email, recipient.first_name, and recipient.last_name respectively. You can reference these variables in your template to personalize the notification.

Notify individual participants

For trigger events that include a participants object (for example, booking.created notifications), you can set up your workflow to send a message to all participants at once, or each participant individually.

By default, Nylas sends messages to all participants at once. If you want to notify individual participants for bookings notifications, add "notify_individually": "true" to the additional_fields object.

curl --request POST \
  --url "https://api.us.nylas.com/v3/scheduling/bookings?configuration_id=<SCHEDULER_CONFIG_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Content-Type: application/json' \
  --data '{
    "additional_fields": {
      "notify_individually": "true"
    },
    "end_time": 1709645400,
    "guest": {
      "name": "Nyla",
      "email": "[email protected]"
    },
    "participants": [],
    "start_time": 1709643600
  }'

To notify individual participants for events notifications, add "notify_individually": "true" to the metadata object.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "busy": true,
    "description": "Come ready to talk philosophy!",
    "location": "New York Public Library, Cave room",
    "metadata": {
      "notify_individually": "true"
    },
    "participants": [
      {
        "name": "Leyah Miller",
        "email": "[email protected]"
      },
      {
        "name": "Nyla",
        "email": "[email protected]"
      }
    ],
    "title": "Annual Philosophy Club Meeting",
    "when": {
      "start_time": 1674604800,
      "end_time": 1722382420,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
    }
  }'