Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Outbox Endpoint Guide

Send and schedule emails using the Nylas Outbox endpoint.

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 /outbox.

curl --location --request POST 'https://api.nylas.com/outbox' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subject": "Welcome to Nylas!,
    "to": [
        {
            "email": "[email protected]",
            "name": "Dorothy"
        }
    ],
    "from": [
        {
            "name": "[email protected]",
            "email": "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": [
        {
            "email": "Leonardo Work",
            "name": "[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/outbox' \
--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": [
        {
            "name": "[email protected]",
            "email": "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": [
        {
            "email": "Leonardo Work",
            "name": "[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/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"
}

Get All Outbox Messages

To see all messages scheduled make a GET request to /outbox.

Get All Outbox Message Request

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

Get All Outbox Message Response


[
    {
        "account_id": "5tgncdmczat02216u7d6uypyi",
        "action": "outbox",
        "bcc": [],
        "body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "cc": [],
        "created_at": 1608064069,
        "date": 1608064068,
        "events": [],
        "files": [],
        "from": [
            {
                "email": "Leonardo Work",
                "name": "[email protected]"
            }
        ],
        "id": "afc7gknkgig2dfeu0d7w2llly",
        "job_status_id": "endc1r0qttsrq2et5jkp5unut",
        "labels": [],
        "object": "draft",
        "reply_to": [],
        "reply_to_message_id": null,
        "send_at": 1608062400,
        "snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "starred": false,
        "status": "pending",
        "subject": "From Nylas",
        "thread_id": "clmeoxat1457kfau28ifp5n8b",
        "to": [
            {
                "email": "[email protected]",
                "name": "Leonardo"
            }
        ],
        "unread": false,
        "version": 0
    },
    {
        "account_id": "5tgncdmczat02216u7d6uypyi",
        "action": "outbox",
        "bcc": [],
        "body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "cc": [],
        "created_at": 1608064663,
        "date": 1608064663,
        "events": [],
        "files": [],
        "from": [
            {
                "email": "Leonardo Work",
                "name": "[email protected]"
            }
        ],
        "id": "2r1s54gyqodvkkdzhfv43b22",
        "job_status_id": "1aoyusvupm738p7wpp7g5b3cv",
        "labels": [],
        "object": "draft",
        "reply_to": [],
        "reply_to_message_id": null,
        "send_at": 1608151200,
        "snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "starred": false,
        "status": "pending",
        "subject": "Sent at 2:40",
        "thread_id": "6fbyd50xl91lgbqpdtleff0ts",
        "to": [
            {
                "email": "[email protected]",
                "name": "Leonardo"
            }
        ],
        "unread": false,
        "version": 0
    },
    {
        "account_id": "5tgncdmczat02216u7d6uypyi",
        "action": "outbox",
        "bcc": [],
        "body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "cc": [],
        "created_at": 1608064900,
        "date": 1608064899,
        "events": [],
        "files": [],
        "from": [
            {
                "email": "Leonardo Work",
                "name": "[email protected]"
            }
        ],
        "id": "f3sp74ocr764ksevpa9wkgl2j",
        "job_status_id": "5oqakcos3qqhp0sti1pasfsvd",
        "labels": [],
        "object": "draft",
        "reply_to": [],
        "reply_to_message_id": null,
        "send_at": 1608064899,
        "snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "starred": false,
        "status": "pending",
        "subject": "Sent at 2:40",
        "thread_id": "c0udqhht0v9hev9ayigu9bcv0",
        "to": [
            {
                "email": "[email protected]",
                "name": "Leonardo"
            }
        ],
        "unread": false,
        "version": 0
    },
    {
        "account_id": "5tgncdmczat02216u7d6uypyi",
        "action": "outbox",
        "bcc": [],
        "body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "cc": [],
        "created_at": 1608065002,
        "date": 1608065001,
        "events": [],
        "files": [],
        "from": [
            {
                "email": "leonardo Work",
                "name": "[email protected]"
            }
        ],
        "id": "4ob23iv76gj8dv85pnivh6kra",
        "job_status_id": "2dqclipba6flkvo6y0a42tgjh",
        "labels": [],
        "object": "draft",
        "reply_to": [],
        "reply_to_message_id": null,
        "send_at": 1608151500,
        "snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "starred": false,
        "status": "pending",
        "subject": "Sent at 2:45",
        "thread_id": "5fail6l2b474jdx72qczolj16",
        "to": [
            {
                "email": "[email protected]",
                "name": "Leonardo"
            }
        ],
        "unread": false,
        "version": 0
    },
    {
        "account_id": "5tgncdmczat02216u7d6uypyi",
        "action": "outbox",
        "bcc": [],
        "body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "cc": [],
        "created_at": 1608065541,
        "date": 1608065541,
        "events": [],
        "files": [],
        "from": [
            {
                "email": "Leonardo Work",
                "name": "[email protected]"
            }
        ],
        "id": "8bup1y1szsybrj91e86l9l07o",
        "job_status_id": "996mfx5bg5yzay4bpedug7of2",
        "labels": [],
        "object": "draft",
        "reply_to": [],
        "reply_to_message_id": null,
        "send_at": 1608155100,
        "snippet": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
        "starred": false,
        "status": "pending",
        "subject": "Sent at 4:00",
        "thread_id": "abnnykhlipvgknbvubgfrqknx",
        "to": [
            {
                "email": "[email protected]",
                "name": "Leonardo"
            }
        ],
        "unread": false,
        "version": 0
    }
]

Delete Scheduled Message

To delete a scheduled message send a DELETE request to /outbox with the job_status_id from the scheduled message response.

Delete Schedule Message Request


curl --location --request DELETE 'https://api.nylas.com/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 A.M. was returned as a 429, and daily limits were reached. Nylas will start Tuesday again at 00:00.

If there are several 429s 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

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 /outbox without adding send_at. Messages are sent immediately.
  • Messages that have been sent, can not be edited.

Feature Support

ScopesProvider AvailabilitySDK Support
email.sendGoogle
Microsoft
IMAP
None

What's Next?

Updated about a month ago

Outbox Endpoint Guide


Send and schedule emails using the Nylas Outbox endpoint.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.