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.
Link Tracking
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 addingsend_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 |