Create a workflow - Application Level Workflows - API Reference

POST

https://api.us.nylas.com/v3/workflows

Creates an application-level workflow.

ℹ️ You must have an existing template to create a workflow.

NYLAS API KEY

Request body

Create workflow request

delayinteger

The number of minutes between a trigger_event being met and the workflow sending a message.

Default: 0

Example: 5

is_enabledboolean

When true, indicates that the workflow is enabled.

Default: true

Example: true

name*string

The name of the workflow.

Example: "New booking confirmation workflow"

template_id*string

The ID of the email template the workflow uses.

Example: "14c00cc8-648c-4381-ad10-52641d9bac8e"

trigger_event*string

The event which triggers the workflow.

grant.expired and grant.deleted require a from sender address, because the grant that triggered them can no longer send email. Every other trigger accepts a workflow without one.

Workflows have no condition or filter field, so an enabled workflow sends for every matching event in its scope. High-volume triggers such as message.created fire for every message in every mailbox the workflow covers.

booking.cancelledbooking.createdbooking.pendingbooking.reminderbooking.rescheduledcalendar.createdcalendar.deletedcalendar.updatedcontact.deletedcontact.updatedevent.createdevent.deletedevent.updatedfolder.createdfolder.deletedfolder.updatedgrant.createdgrant.deletedgrant.expiredgrant.imap_sync_completedgrant.updatedmessage.bounce_detectedmessage.createdmessage.link_clickedmessage.openedmessage.send_failedmessage.send_successmessage.updatednotetaker.creatednotetaker.deletednotetaker.medianotetaker.meeting_statenotetaker.updatedthread.replied

Example: "booking.created"

fromobjectnullable

Details of the sender if the workflow should use transactional send. If not provided, the sender will be the grant associated with the trigger event.

A workflow with from.email must use an application-level template. If template_id points to a grant-level template, the request returns 400 with the message a Workflow with a from email must use an application-level template.

Responses

request_id*string

The ID of the request.

data*object

A custom workflow that sends messages from a template when certain events are triggered.

app_idstringnullable

The ID of the Nylas application associated with the workflow. Returned only if the workflow is configured at the application level.

Example: "6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb"

date_created*integer

When the workflow was created, in seconds using the Unix timestamp format.

Example: 1756477389

delay*integer

The number of minutes between a trigger_event being met and the workflow sending a message.

Example: 5

grant_idstringnullable

The ID of the grant associated with the workflow. Returned only if the workflow is configured at the grant level.

Example: "6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb"

id*string

The ID of the workflow.

Example: "b79c82b2-a51b-4c54-8469-28006a43551a"

is_enabled*boolean

When true, indicates that the workflow is enabled.

Example: true

name*string

The name of the workflow.

Example: "New booking confirmation workflow"

template_id*string

The ID of the email template the workflow uses.

Example: "14c00cc8-648c-4381-ad10-52641d9bac8e"

trigger_event*string

The event which triggers the workflow.

grant.expired and grant.deleted require a from sender address, because the grant that triggered them can no longer send email. Every other trigger accepts a workflow without one.

Example: "booking.created"

fromobjectnullable

Details of the sender if the workflow uses transactional send.

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