Skip to content
Skip to main content

Schedule an email to send later

Last updated:

You want an email to land at 9 a.m. in the recipient’s time zone, or to queue a batch of messages to go out later without keeping a job running. Rolling your own scheduler means a queue, a worker, and retry logic that has to stay up until every message sends.

The Nylas Email API schedules the send for you. You add one field to a normal send request, and the API holds the message and delivers it at the time you set, through the user’s own provider.

How do I schedule an email to send later?

Section titled “How do I schedule an email to send later?”

Add a send_at field to your POST /v3/grants/{grant_id}/messages/send request, set to the delivery time as a Unix timestamp in seconds. Omit send_at and the message sends immediately; include it and Nylas queues the message and sends it at that time. Everything else about the request is identical to a direct send, so the same recipients, body, and tracking apply.

When Nylas stores the message, the send_at value must be between 2 minutes and 30 days in the future; if you keep the message on the provider instead, you can schedule it any time ahead. Either way the response returns a schedule you can track.

How do I see my scheduled sends?

Section titled “How do I see my scheduled sends?”

List pending scheduled sends with a GET /v3/grants/{grant_id}/messages/schedules request. Nylas returns each schedule with its ID and status, so you can show users what’s queued or reconcile your own records. A schedule’s details are kept for 72 hours after the send time, then deleted from the cache.

The request below returns all scheduled sends for a grant.

How do I cancel a scheduled send?

Section titled “How do I cancel a scheduled send?”

Cancel a pending send with a DELETE /v3/grants/{grant_id}/messages/schedules/{scheduleId} request, using the schedule ID from the list call. You can cancel up until at least 10 seconds before the send_at time; within that final 10-second window, Nylas can’t guarantee the cancellation will succeed. Build your UI to stop offering cancellation before that cutoff.

Cancelling removes the schedule and the message never sends, which is the clean way to handle a user who changes their mind before delivery.

Things to know about scheduled send

Section titled “Things to know about scheduled send”

A few details shape how scheduling behaves. The use_draft option, available on 2 providers (Google and Microsoft Graph), sends the message from a draft so it appears in the Drafts folder until delivery. Scheduled sends run on Nylas infrastructure, so your app doesn’t need to stay online for the message to go out at the right time.

Scheduling is distinct from message.send_success and message.send_failed: subscribe to those 2 webhook triggers to confirm a scheduled message actually delivered. See Schedule messages to send for the full reference.

What’s next

Section titled “What’s next”