Only show these results:
deprecated

Outbox Endpoint

This feature is deprecated and is no longer supported.

The Outbox endpoint is under revision and enhancement.

On December 13th, 2021, this documentation guide will be deprecated. View the upcoming Outbox Endpoint Guide with enhanced features and updates. The transition between Outbox versions requires no change to implementation setups.

The Outbox Endpoint lets you schedule messages. Outbox is also integrated with Job Status and Webhooks, so you always know the status of any messages sent.

You'll learn how to schedule a message, check on the status of scheduled messages, change the send time, and how it delivers emails.

Send a Message

To send a message, send a POST request to /v2/send?sendnow=false. You may aslo use our legacy endpoint, /v2/outbox

curl --location --request POST 'https://api.nylas.com/v2/send?sendnow=false' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"subject": "Welcome to Nylas!",
"to": [
{
"email": "[email protected]",
"name": "Dorothy"
}
],
"from": [
{
"email": "[email protected]",
"name": "Katherine"
}
],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details."
}'

Send a Message Response

{
"account_id": "5tgncdmczat02216u7d6uypyi",
"bcc": [],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"cc": [],
"date": "Tue, 15 Dec 2020 20:52:21 GMT",
"events": [],
"files": [],
"from": [
{
"name": "Leonardo Work",
"email": "[email protected]"
}
],
"id": "8bup1y1szsybrj91e86l9l07o",
"job_status_id": "996mfx5bg5yzay4bpedug7of2",
"labels": [],
"object": "draft",
"reply_to": [],
"reply_to_message_id": null,
"snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"starred": false,
"subject": "Sent at 4:00",
"thread_id": "abnnykhlipvgknbvubgfrqknx",
"to": [
{
"email": "[email protected]",
"name": "Leonardo"
}
],
"unread": false,
"version": 0
}

Schedule a Message

To schedule a message, add send_at to the message object. Send at is the time the message should be sent in Unix timestamp.

Schedule a Message Request

curl --location --request POST 'https://api.nylas.com/v2/send?sendnow=false' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"subject": "Welcome to Nylas!",
"send_at": 1608156000,
"to": [
{
"email": "[email protected]",
"name": "Dorothy"
}
],
"from": [
{
"email": "[email protected]",
"name": "Katherine"
}
],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details."
}'

Schedule a Message Response

The Outbox API returns a job_status_id and outbox_info object. Use these to manage your outbox. The job_status_id is used to update and delete scheduled messages.

{
"account_id": "5tgncdmczat02216u7d6uypyi",
"bcc": [],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"cc": [],
"date": "Tue, 15 Dec 2020 20:52:21 GMT",
"events": [],
"files": [],
"from": [
{
"name": "Leonardo Work",
"email": "[email protected]"
}
],
"id": "8bup1y1szsybrj91e86l9l07o",
"job_status_id": "996mfx5bg5yzay4bpedug7of2",
"labels": [],
"object": "draft",
"outbox_info": {
"id": "bzjc8nrklhpybk71sbt3o1lve",
"message_id": "8bup1y1szsybrj91e86l9l07o",
"send_at": "Wed, 16 Dec 2020 22:00:00 GMT",
"sent_at": null
},
"reply_to": [],
"reply_to_message_id": null,
"snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"starred": false,
"subject": "Sent at 4:00",
"thread_id": "abnnykhlipvgknbvubgfrqknx",
"to": [
{
"email": "[email protected]",
"name": "Leonardo"
}
],
"unread": false,
"version": 0
}

Update Send Time

To update the scheduled send time of a message, do a PUT request to the outbox using the job_status_id from the scheduled message response and update send_at.

Update Sent at Time Request

curl --location --request PUT 'https://api.nylas.com/v2/outbox/<job_status_id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"send_at": 1608155100
}'

Update Sent at Time Response

The response returns the job status object with the new send_at time.

{
"account_id": "5tgncdmczat02216u7d6uypyi",
"action": "outbox",
"created_at": 1608065541,
"id": "8bup1y1szsybrj91e86l9l07o",
"job_status_id": "996mfx5bg5yzay4bpedug7of2",
"object": "message",
"send_at": 1608155100,
"status": "pending"
}

Delete Scheduled Message

To delete a scheduled message send a DELETE request to /v2/send?sendow=false or /v2/outbox with the job_status_id from the scheduled message response.

Delete Schedule Message Request

curl --location --request DELETE 'https://api.nylas.com/v2/outbox/<job_status_id>' \
--header 'Authorization: Bearer <access_token>' \

Delete Schedule Message Response

The response will return a 200 OK along with the deleted job.

{
"account_id": "5tgncdmczat02216u7d6uypyi",
"action": "outbox",
"created_at": 1608151222,
"id": "2g8kjhqrxknksimqlg6iwckkg",
"job_status_id": "6gi9cvb6jjsyotaalawdzujau",
"object": "message",
"send_at": 1608156000,
"status": "pending"
}

Outbox Object

The outbox_info object contains information about the scheduled message.

  • message_id - ID of the message scheduled to be sent.
  • send_at - When the message is scheduled to be sent.
  • sent_at - Send at always returns null. The message has not been sent when the message is created.
...
"outbox_info": {
"id": "bzjc8nrklhpybk71sbt3o1lve",
"message_id": "8bup1y1szsybrj91e86l9l07o",
"send_at": "Wed, 16 Dec 2020 22:00:00 GMT",
"sent_at": null
},
...

Outbox File Attachments

You can attach files to outgoing messages. There are a few limitations to attachments:

  • Attachments are limited to 30 MB
  • Messages may expire if:
    • The message is scheduled more than 7 days out.
    • The message is scheduled for less than 7 days in the future, but the file was uploaded more than 7 days before the message send date.
    • The file was uploaded within 7 days of the send date, but the send date is more than 7 days after the file was uploaded because of deliverability issues.

Job Status

As part of the response, we return a job_status_id. Job status is used to determine if changes have synced back to the provider. Query the job status endpoint to determine if the message was sent successfully. You can also subscribe to webhooks to get notified of the job status.

...
"id": "8bup1y1szsybrj91e86l9l07o",
"job_status_id": "996mfx5bg5yzay4bpedug7of2",
"labels": [],
"object": "draft",
...

Outbox Job Status Request

curl --location --request GET 'https://api.nylas.com/job-statuses/<job_status_id>' \
--header 'Authorization: Bearer <access_token>' \

Outbox Job Status Response

  • send_at - When the message is scheduled to be sent.
  • status - Status of the message
    • pending - Message is schedule
    • success - Message was sent
    • failed - Message has failed to send.
{
"account_id": "5tgncdmczat02216u7d6uypyi",
"action": "outbox",
"created_at": 1608065002,
"id": "4ob23iv76gj8dv85pnivh6kra",
"job_status_id": "2dqclipba6flkvo6y0a42tgjh",
"object": "message",
"send_at": 1608151500,
"status": "pending"
}

Outbox Webhooks

Subscribe to the job status webhook to get alerts when a job is successful or has failed.

When an email is successful, Nylas will return a job.successful webhook. The email was sent successfully, and the information was synced back to the provider.

When an email has permanently failed, Nylas will return a job.failed webhook. The changes have not synced with the provider. You will need to send the message again.

Deliverability

What makes Outbox API different from our other methods of sending messages is how it handles mail failures. When Nylas receives a 429 error (Too Many Requests) from a provider, we will attempt to deliver the message again.

Once we hit the daily limits, we will start the next day again. For example, a message scheduled for Monday at 08:00 AM was returned as a 429, and daily limits were reached. Nylas will start Tuesday again at 00:00.

If there are several 429's and messages were not sent, Nylas attempts again using the First In First Out to determine the order the messages will be sent.

We will keep trying until we receive a 401, 403, or 404 from the email provider.

You may wish to add, in the JSON body of your request, a tracking object:

"tracking": {
"link": true,
"opens": true
}

The link key controls whether all links in the email are tracked, and the opens key tracks when an email is opened.

Bounce Detection

Every email sent with Asynchronous Send supports Nylas' bounce detection features. You can read more about this (and how to subscribe to bounce detection webhooks) in the Bounce Detection section of our documentation.

200 OK Response

A 200 response does not mean a message was delivered successfully. Review the job status to learn the status of the message.

Keep in Mind

  • Messages scheduled to be sent are only created on Nylas. After the message is sent and synced to the provider will it show in the folder or label for sent messages. It is not saved to provider drafts.
  • You can send a message using /v2/send?sendow=false or /v2/outbox without adding send_at. Messages are sent immediately.
  • Messages that have been sent, can not be edited.

Feature Support

Scopes Provider Availability SDK Support
email.send Google
Microsoft
IMAP
None

What's Next?