Menu

Mattering Automations Nylas integration

Connect Nylas to Mattering Automations: messages, threads, drafts, folders, attachments, calendars, events with RSVP, availability and free/busy lookups, contacts, and webhooks as workflow steps, authenticated with one API key and its region.

The Mattering Automations Nylas integration adds the Nylas v3 email, calendar, and contacts API to your automation canvas: list and read messages and threads with provider-native search, run the full draft lifecycle from compose to send, manage folders and labels, fetch attachment metadata and download files, manage calendars and events with RSVP, find open slots with availability and free/busy lookups, read and write contacts, and register webhooks for real-time notifications.

The credential is an API key created per application in the Nylas Dashboard, stored in Mattering together with the application's region, because Nylas v3 runs isolated US and EU regions and a key only works against the host its application lives in. Data access is per grant: a grant is one connected end-user account (Google, Microsoft, IMAP, or a virtual calendar) authorized through Nylas hosted authentication, and 37 of the 45 nodes take a grant ID naming whose mailbox, calendar, or address book the call touches. Setup takes a few minutes once the key exists, and this guide walks through each step and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 45 nodes, 20 read and 25 act, and 11 carry a destructive flag: Nylas: Delete Calendar, Nylas: Delete Contact, Nylas: Delete Draft, Nylas: Delete Event, Nylas: Delete Folder, Nylas: Delete Grant, Nylas: Delete Message, Nylas: Delete Webhook, and three that delete nothing at all: Nylas: Send Message, Nylas: Send Draft, and Nylas: Send Event RSVP are destructive-classed because they deliver real email that cannot be recalled. Some surfaces are deliberately absent: the separate Nylas Scheduler product, account connection flows, scheduled-send management, Smart Compose, and whole-thread delete stay off the canvas.

Before you start

  • A Nylas account with a v3 application in the Nylas Dashboard. Note the application's region (US or EU): the credential needs it, and a key checked against the wrong region fails authentication. A Sandbox application works for building and testing before a paid plan; production usage is priced per connected account.
  • At least one connected account (a grant) on the application, authorized through Nylas hosted authentication. Nylas: Get Application and Nylas: List Grants work before any account is connected, but every mailbox, calendar, and contact node needs a grant ID.
  • A Mattering workspace with access to the Automations app.
  • For the webhook nodes, a publicly reachable destination URL such as a Mattering inbound webhook trigger. Nylas verifies new webhook destinations with a challenge request the endpoint must answer within 10 seconds.
  • A testing caution rather than a prerequisite: sends from a connected account deliver real email, so point test sends only at addresses you own, and leave notify_participants false on event nodes during test runs.

Create a Nylas API key

Mattering authenticates to Nylas with an API key sent as a Bearer header on every request. Keys are minted per application in the Nylas Dashboard, they are displayed once at creation, and each carries an expiration you choose. The key authenticates the request; which mailbox or calendar a call touches is named separately by the grant ID, so one credential serves every account connected to the application.

Sign in to the Nylas Dashboard and open the application you want Mattering to use. Note its region (US or EU); you will need it when you create the credential.
Click API Keys in the left navigation, then click Generate new key.
Enter a name for the key, select an Expiration time, and click Generate key.
Copy the key now. The Dashboard displays an API key secret once, on this screen only; if you lose it, the key cannot be viewed again and you must generate a new one.
Nylas API keys expire on the date you chose at creation. Note it somewhere your team will see: when the key expires, every node starts failing authentication at once, and the fix is generating a new key and updating the Mattering credential.

Connect Nylas to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Nylas from the list.
Click Create new credential, paste the API key, and set the region to match your application: us or eu. Save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls the Nylas applications endpoint, which works before any account is connected: a success reports your application ID and region, and a 401 means the key is wrong, expired, or checked against the wrong region's host.
Click Connect. All 45 Nylas nodes appear in your canvas palette.

How webhook triggers deliver

Nylas pushes events to Mattering the moment they happen; no polling, no schedules.

Event happens

An event you subscribe to in Nylas

Delivery to your webhook URL

Mattering reads the event type and matches it to your trigger nodes

Your workflows run

Every active automation containing the trigger node fires

Verify it works

After connecting, open any automation canvas and check the palette: a Nylas section should list the query and action nodes. Drop Nylas: Get Application onto the canvas and run a test step. It is the integration's universal probe: it is grant-independent, so it proves the key and region before any account is connected, and a successful response returns the application ID, region, and environment without echoing the secret. If this node succeeds, the credential is healthy; anything failing after it is a grant, permissions, or parameters question, not an authentication one.

Next, run Nylas: List Grants and copy a grant ID, because 37 of the 45 nodes need one, and check each grant's status while you are there: a grant can go invalid when the end user's provider consent lapses, and every node using it fails until the account reauthorizes. Then run Nylas: List Calendars with that grant ID and copy a calendar ID, which every event node requires. Everything in this verify path is read-only: it cannot reach the 11 destructive nodes or send a single email, so it is safe to re-run whenever you rotate the key.

Node reference

45 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 20

Nylas: Download Attachment

nylas_download_attachment

Download an attachment's file content, returned base64-encoded at data.file_base64 with its content type and size. Files over the 5 MB (base64) cap fail with a clear error - check size first with Nylas: Get Attachment Metadata.

Nylas: Get Application

nylas_get_application

Fetch the Nylas application the API key belongs to: application ID, region, environment, and branding. Grant-independent, so it works before any account is connected - the credential health check to run first in any Nylas automation.

Nylas: Get Attachment Metadata

nylas_get_attachment

Fetch an attachment's metadata - filename, content type, and size - without downloading the bytes. Check the size here before Nylas: Download Attachment (5 MB node cap).

Nylas: Get Availability

nylas_get_availability

Find open meeting slots across one or more connected accounts: returns time_slots where every listed participant is free for the requested duration. GRANT-INDEPENDENT path - participants are named by email in the body (each must belong to a grant on this application). A read: it books nothing; feed a chosen slot into Nylas: Create Event.

Nylas: Get Event

nylas_get_event

Fetch one event: time, participants and their RSVP statuses, conferencing details, and recurrence. The participant check to run before Nylas: Send RSVP.

Nylas: Get Free/Busy

nylas_get_free_busy

Fetch busy time blocks for up to 50 email addresses (Google; 20 on Microsoft) as seen from the connected account's provider - colleagues on the same domain included, no extra grants needed. Returns per-email time_slots with status busy; gaps are free.

Nylas: Get Grant

nylas_get_grant

Fetch one grant: the connected account's email, provider, scopes, and valid/invalid status. The status check to run before a long email or calendar automation.

Nylas: Get Message

nylas_get_message

Fetch one message with its full body, participants, folders, and attachment metadata (attachment IDs feed the attachment nodes).

Nylas: Get Thread

nylas_get_thread

Fetch one thread: participants, message IDs (feed Nylas: Get Message for bodies), folders, and state.

Nylas: List Calendars

nylas_list_calendars

List the account's calendars with IDs, names, timezones, and read-only/primary flags. The calendar ID from here is required by every event node.

Nylas: List Connectors

nylas_list_connectors

List the auth connectors (providers) configured on the application - google, microsoft, imap, virtual_calendar - with their scopes. Tells an automation which account types this application can connect.

Nylas: List Contact Groups

nylas_list_contact_groups

List the account's contact groups (Google labels, Microsoft folders) with IDs and names - the values the contact group filter and the groups field take.

Nylas: List Contacts

nylas_list_contacts

List the account's contacts with names, emails, phone numbers, and groups. Filter by email, phone, source (address_book, inbox, domain), or contact group.

Nylas: List Drafts

nylas_list_drafts

List the account's email drafts with their draft IDs, which the update, send, and delete nodes need. Documented filters (subject, any_email, thread_id, unread, starred, has_attachment) are reachable via Extra query parameters.

Nylas: List Events

nylas_list_events

List events on a calendar, filtered by time range, title, attendee, or busy state. start/end are range FILTERS on the entity listing (Unix seconds), not a reporting window. calendar_id is required by the API.

Nylas: List Folders

nylas_list_folders

List the mailbox's folders (Gmail labels, Microsoft/IMAP folders) with IDs, names, and unread/total counts. Folder IDs feed the message/thread folder filters and moves.

Nylas: List Grants

nylas_list_grants

List the connected accounts (grants) on the application with their grant IDs, emails, providers, and valid/invalid status. Nearly every other Nylas node needs a grant ID from here. Paginates with limit/offset (not page_token).

Nylas: List Messages

nylas_list_messages

List messages in the connected mailbox, newest first, with filters on sender, recipient, folder, read/starred state, received-time range, and provider-native search. List responses carry a snippet; use Nylas: Get Message for the full body.

Nylas: List Threads

nylas_list_threads

List conversation threads with participants, snippet, message IDs, and unread/starred state - the one-row-per-conversation view of the mailbox.

Nylas: List Webhooks

nylas_list_webhooks

List the application's webhook destinations with their IDs, URLs, trigger types, and active/failing status.

Action nodes 25

Nylas: Create Calendar

nylas_create_calendar

Create a calendar on the connected account. Reversible with Nylas: Delete Calendar. Microsoft accepts only the name at creation; the other fields apply to Google and virtual calendars.

Nylas: Create Contact

nylas_create_contact

Create a contact in the connected account's address book. Reversible with Nylas: Delete Contact.

Nylas: Create Draft

nylas_create_draft

Create an email draft in the connected account. Nothing is sent - the draft sits in the mailbox for review until Nylas: Send Draft fires it or a human sends it from their mail client. Reversible with Nylas: Delete Draft. The draft-for-approval pattern is the safe way to automate outbound email.

Nylas: Create Event

nylas_create_event

Create a calendar event. Reversible with Nylas: Delete Event - BUT with notify_participants true the provider emails invitations to every participant, and those emails cannot be recalled; leave it false in test runs. The 'when' object sets the time in one of four documented shapes.

Nylas: Create Folder

nylas_create_folder

Create a folder (or Gmail label) in the mailbox. Reversible with Nylas: Delete Folder. Colors apply to Google only.

Nylas: Create Webhook

nylas_create_webhook

Create a webhook destination for real-time notifications (message.created, grant.expired, event.created, ...). Nylas immediately sends a challenge GET the endpoint must echo within 10 seconds, or creation fails. The response's webhook_secret is shown ONCE - store it to verify signatures. Reversible with Nylas: Delete Webhook.

Nylas: Delete Calendar

nylas_delete_calendar

DESTRUCTIVE: delete a calendar and EVERY event on it, permanently. Primary calendars cannot be deleted. Export or read the events first if there is any doubt.

Nylas: Delete Contact

nylas_delete_contact

DESTRUCTIVE: delete a contact from the account's address book. Its details are gone unless read beforehand.

Nylas: Delete Draft

nylas_delete_draft

DESTRUCTIVE: delete a draft. Its composed content is gone unless read beforehand (Nylas: List Drafts). Nothing is sent or recalled by this.

Nylas: Delete Event

nylas_delete_event

DESTRUCTIVE: delete an event from the calendar. Its details are gone unless read beforehand, and with notify_participants true the provider emails cancellations to participants.

Nylas: Delete Folder

nylas_delete_folder

DESTRUCTIVE: delete a folder. Provider behavior varies: Gmail removes the label from its messages (messages survive), while folder-based providers can delete or orphan the contents. Check the folder's total_count first.

Nylas: Delete Grant

nylas_delete_grant

DESTRUCTIVE: revoke a grant, disconnecting the account from Nylas. Every node using this grant ID starts failing immediately, and reconnecting requires the end user to authenticate again. The mailbox itself is untouched.

Nylas: Delete Message

nylas_delete_message

DESTRUCTIVE: delete a message from the mailbox. Provider behavior varies (some trash, some remove permanently) - prefer Nylas: Update Message with a Trash folder move when recoverability matters.

Nylas: Delete Webhook

nylas_delete_webhook

DESTRUCTIVE: delete a webhook destination. Notifications to it stop immediately, and its signing secret cannot be recovered.

Nylas: Send Draft

nylas_send_draft

DESTRUCTIVE: send an existing draft to its recipients. A SENT EMAIL CANNOT BE RECALLED, so this node must never run in a blind test matrix - read the draft's recipients and body upstream first. (POST to the draft's own path sends it; there is no /send suffix in Nylas v3.)

Nylas: Send Event RSVP

nylas_send_rsvp

DESTRUCTIVE: RSVP to an event as the connected account - yes, no, or maybe. This SENDS A REAL REPLY EMAIL to the event's organizer, which cannot be recalled, so it must never run in a blind test matrix. The status itself can be changed by RSVPing again.

Nylas: Send Message

nylas_send_message

DESTRUCTIVE: send an email from the connected account, immediately or scheduled via send_at. A SENT EMAIL CANNOT BE RECALLED, so this node must never run in a blind test matrix - verify recipients upstream. Fill reply_to_message_id to reply on an existing thread with correct headers. Sending is synchronous and can take up to ~2 minutes on slow providers.

Nylas: Update Calendar

nylas_update_calendar

Update a calendar's name, description, timezone, or color. Only the fields you fill are sent. Microsoft allows updating only the name.

Nylas: Update Contact

nylas_update_contact

Update a contact. Only the fields you fill are sent, but note array fields (emails, phone_numbers) REPLACE the stored array wholesale - read the contact first and send the full merged list.

Nylas: Update Draft

nylas_update_draft

Update an existing draft's content or recipients. Only the fields you fill are sent; nothing is delivered until the draft is sent.

Nylas: Update Event

nylas_update_event

Update an event's time, title, participants, or details. Only the fields you fill are sent. With notify_participants true the provider emails updates to participants (unrecallable); leave it false in test runs.

Nylas: Update Folder

nylas_update_folder

Rename a folder, re-parent it, or (Google) change its label colors. Messages inside are untouched.

Nylas: Update Message

nylas_update_message

Update a message's flags: mark read/unread, star/unstar, or move it between folders. Only the fields you fill are sent, and every change is reversible by writing the previous value back.

Nylas: Update Thread

nylas_update_thread

Update a whole thread's flags in one call: mark every message read/unread, star/unstar, or refile the thread. Reversible by writing the previous value back.

Nylas: Update Webhook

nylas_update_webhook

Update a webhook destination's URL, triggers, or alert emails. Changing the URL re-runs the challenge check.

Using the integration

On the automation canvas

Nylas nodes chain with every other node: a webhook for arriving mail can open a task in Mattering Productivity with the message body attached, a scheduled sweep can mirror Nylas: List Contacts into a Mattering database, and Nylas: Get Availability can feed a booking straight into Nylas: Create Event. The grant ID from Nylas: List Grants is the value almost every downstream node asks for, and the pickers across the connector are populated from the listers, so a grant chosen once flows through message, calendar, and contact fields without hand-copying IDs.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. An agent can search a mailbox with Nylas: List Messages, read a conversation with Nylas: Get Thread and Nylas: Get Message, check RSVP status with Nylas: Get Event, and compose a reply with Nylas: Create Draft. The read nodes are the safest surface to hand an agent; keep the 11 destructive nodes, the three send nodes above all, behind conditions or approval steps.

The draft-for-approval email pattern

Composing and sending are separate nodes on purpose. Nylas: Create Draft writes the message into the connected mailbox and sends nothing, so a workflow can compose a reply, open an approval task carrying the recipients and body, and hold until a person signs off, at which point Nylas: Send Draft delivers it. Nylas: Send Message skips the gate for sends the workflow fully controls, immediately or scheduled with send_at, which Nylas accepts from 1 minute to 30 days out. Sending is synchronous, and Nylas documents that slow providers can take up to about two minutes, so the send nodes run with extended timeouts rather than failing early.

Scheduling lookups that book nothing

Nylas: Get Availability takes participants by email, each connected as a grant on the application, and returns the slots where all of them are free for the requested duration; it is a read, and the workflow decides which slot becomes an event. Nylas: Get Free/Busy asks the connected account's provider for busy blocks, up to 50 email addresses on Google and 20 on Microsoft per request, and it can see colleagues on the same domain who never connected a grant. On the write side, Nylas: Create Event and Nylas: Update Event carry the notify_participants flag: true makes the provider email invitations or updates that cannot be recalled, so leave it false until the workflow is trusted.

Real-time triggers with webhooks

Nylas: Create Webhook registers a destination for notification types like message.created, event.created, and grant.expired, and pointing it at a Mattering inbound webhook trigger turns provider activity into workflow starts. Nylas verifies the destination immediately with a challenge request it must answer within 10 seconds, and the creation response includes a signing secret, shown once, for verifying delivery signatures. Nylas: List Webhooks reports each destination's active or failing status, worth a place in a scheduled health sweep, and Nylas: Update Webhook re-runs the challenge when the URL changes.

The 11 destructive nodes, gated

The three send nodes are the ones to respect most: Nylas: Send Message, Nylas: Send Draft, and Nylas: Send Event RSVP deliver real email that cannot be recalled, so keep them behind approval steps and never in a blind test run. Among the deletes, Nylas: Delete Calendar removes every event on the calendar permanently, Nylas: Delete Grant revokes the account connection and every node using that grant starts failing until the user reauthorizes, and Nylas: Delete Message varies by provider, some trash and some remove permanently, so prefer Nylas: Update Message with a move to the Trash folder when recoverability matters. The pattern for all 11 is the same: read the thing first, and put the node behind a condition, an approval task, or a manual run rather than a bare trigger.

Troubleshooting

Test Connection fails with a 401 error
Three causes cover nearly every case. First, the region: Nylas v3 runs isolated US and EU hosts, a key only works against the region its application lives in, and a US key checked against the EU host returns a 401 that looks exactly like a bad key. Open the application in the Nylas Dashboard, confirm its region, and make the credential's region match. Second, the key itself: check for whitespace from the copy and confirm the key was not revoked. Third, expiration: Nylas API keys carry an expiration chosen at creation, and an expired key fails authentication exactly like a wrong one. Generate a new key and update the credential.
Test Connection passes but mailbox and calendar nodes fail
The connection test calls the applications endpoint, which is grant-independent, so it proves the key without proving any account is connected. Run Nylas: List Grants: if it returns an empty list, no account has been connected to the application yet, and every grant-scoped node has nothing to act on until one is authorized through Nylas hosted authentication. If grants exist, check the status of the one your workflow uses: an invalid grant means the provider consent lapsed, and every call against it fails until the end user reauthorizes. Nylas can announce this in advance if you register a webhook for grant.expired.
Nylas: Create Webhook fails immediately
Nylas verifies a new destination before creating it: it sends a challenge request to the URL, and the endpoint must answer within 10 seconds or creation fails. A URL that is not publicly reachable, answers slowly, or does not echo the challenge fails every time. Point the webhook at an endpoint that implements the challenge response, such as a Mattering inbound webhook trigger, and note two things about the successful response: the signing secret it contains is shown once, so store it if you plan to verify delivery signatures, and changing the URL later with Nylas: Update Webhook re-runs the same challenge check.
Nylas: Download Attachment fails on a large file
The node returns file content base64-encoded and is capped at 5 MB; larger files fail with a clear error rather than truncating, which is deliberate, because a silently clipped attachment is worse than a loud failure. Run Nylas: Get Attachment Metadata first: it returns the filename, content type, and size without downloading anything, so the workflow can branch before committing to a download. Both attachment nodes also require the message ID alongside the attachment ID, because Nylas scopes attachment IDs to their message; the attachment IDs themselves ride on the message object returned by Nylas: Get Message.
Nylas: List Events returns an error before returning any events
The Nylas events endpoint requires a calendar ID on every listing call; there is no all-calendars listing. Run Nylas: List Calendars for the grant first and pass one of its IDs, and note the primary flag on the results, since the primary calendar is usually the one a workflow means. The start and end fields are range filters on the listing, expressed as Unix timestamps in seconds, not a reporting window, so an empty result with a valid calendar ID usually means the filter window does not overlap any events.
Nylas: Send Message runs far longer than other nodes
That is Nylas behaving as documented rather than a stuck workflow: sending in v3 is synchronous, the request blocks until the provider accepts or rejects the message, and Nylas advises a client timeout of at least 150 seconds because self-hosted Exchange accounts can take up to two minutes to complete a send. The send nodes run with extended timeouts to match, so let them finish. If a workflow needs to continue quickly, schedule the delivery instead with send_at, which Nylas accepts from 1 minute to 30 days in the future; the node then returns without waiting for delivery time.
Nylas: Update Contact wiped out emails or phone numbers
Array fields on contacts replace the stored array wholesale: sending an emails list with one entry leaves the contact with exactly that one email, whatever was stored before. This is how the Nylas API applies contact updates, and the node passes it through rather than guessing at a merge. The safe pattern is read-merge-write: fetch the contact through Nylas: List Contacts, merge your change into the full array, and send the complete list back. Scalar fields behave the way you expect, with only the fields you fill being sent.
Event participants received emails during a test run
The event nodes carry a notify_participants flag, and when it is true the provider, not Nylas, emails invitations on create, updates on change, and cancellations on delete, none of which can be recalled. Leave it false in every test run and in any workflow still being debugged; the event is still created or updated on the calendar either way, just silently. The same discipline applies to Nylas: Send Event RSVP, which sends a real reply email to the event's organizer, which is why it is flagged destructive even though the RSVP status itself can be changed by responding again.

Nylas is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products