Only show these results:
Public Beta

Outbox Endpoint Guide

The Outbox endpoint lets you send and schedule messages. Outbox also integrates with the Job Status endpoint to get updates on the message statuses. This guide covers Outbox examples for requests and responses.

Sending Messages

The Outbox endpoint supports sending messages at the time of request as well as at a specific time. View the Send section for immediate messages and the Schedule section to set up a time. Both methods use the endpoint and request body below.

Endpoint URL: https://api.nylas.com/outbox

Send Immediately

This method sends a message as soon as the request to the endpoint is complete.

POST Outbox Request

The code below is cURL request example.

curl --location --request POST 'https://api.nylas.com/outbox' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '
{
"to": [
{
"email": "email@nylas.com",
"name": "Sample"
},
{
"email": "email@gmail.com",
"name": "Example"
}
],
"from": [{
"email": "sample@outlook.com",
"name": "Sample Account"
}],
"subject": "Outbox Endpoint",
"body": "Content for body of message.",
"reply_to": [{
"email": "sample@outlook.com",
"name": "Sample Account"
}]
}'

POST Outbox Response

Successful responses show a status of 202 Accepted. The response contains the "original_data" field to show the current content of the Outbox message.

{
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"status": "pending",
"original_data": {
"from": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"subject": "POST Request Outbox",
"to": [
{
"name": "Sample",
"email": "email@nylas.com"
}
],
"cc": [
{
"name": "Example",
"email": "example@gmail.com"
}
],
"bcc": [
{
"name": "Administrator",
"email": "admin@yahoo.com"
}
],
"reply_to": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"body": "Content for body of message.",
"send_at": 0,
"retry_limit_datetime": 0,
}
}

Schedule Time

This method sends a message to the endpoint at the configured time. Scheduled Outbox messages use the send_at object field highlighted in the code sample below. View the Request Body Objects section below for more about specific Outbox objects.

POST Outbox Scheduled Request

The code below is an example of the cURL request for the endpoint.

curl --location --request POST 'https://api.nylas.com/outbox' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '
{
"to": [
{
"email": "email@nylas.com",
"name": "Sample"
},
{
"email": "email@gmail.com",
"name": "Example."
}
],
"from": [{
"email": "sample@outlook.com",
"name": "Sample Account"
}],
"subject": "Outbox Endpoint",
"body": "Content for body of message.",
"reply_to": [{
"email": "sample@outlook.com",
"name": "Sample Account"
}],
"send_at": 1634922000,
"retry_limit_datetime": 1634933400
}'

POST Outbox Scheduled Response

The response contains the "original_data" field to show the current content of the Outbox message.

{
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"status": "pending",
"original_data": {
"from": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"subject": "POST Request Outbox",
"to": [
{
"name": "Sample",
"email": "email@nylas.com"
}
],
"cc": [
{
"name": "Example",
"email": "example@gmail.com"
}
],
"bcc": [
{
"name": "Administrator",
"email": "admin@yahoo.com"
}
],
"reply_to": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"body": "POST Outbox test.",
"send_at": 1635267900,
"retry_limit_datetime": 1635440700,
}
}

Outbox Configuration

The sections below cover options unique to Outbox requests and responses.

Job Status ID

The responses for Outbox API requests contain a job_status_id value. The job status shows changes synced back to the provider and has Outbox specific properties. Use the job_status_id value for the API requests below.

  • GET - Retrieve the status of Outbox messages.
  • PUT - Update Outbox messages.
  • DELETE - Delete Outbox messages.
{
...
"job_status_id": "6qwo2w0nreusrgb3syel9vjmk",
...
}

Request Body Objects

While Outbox is similar to the Send endpoint, it has additional request body objects below. These values add functionality to Outbox messages.

Name Type Description
"send_at" integer Unix timestamp to send a message.
"retry_limit_datetime" integer Optional, Unix timestamp to stop retry attempts for a message. Defaults to 24 hours after send_at value. The maximum value is 7 days from the scheduled time.

Service Integration

As an additional option for sending Outbox messages, you can include a third party mailing service, such as SendGrid, in your Outbox workflow. Nylas confirms the grant when connecting to the service.

Outbox Retry Logic

If an Outbox message fails, Nylas retries with different workflow strategies. We can also integrate SendGrid as a third party service to send Outbox messages. Without a fallback option, Nylas uses Outbox parameters as a guideline.

Daily Limit Errors

These errors happen when experiencing a provider restriction for sending Outbox messages. Outbox messages use the solutions below for this situation.

  • With Service - Nylas routes the Outbox message to the service when experiencing a daily limit error event.
  • Without - Nylas only uses the Outbox parameters. After the parameters have finished, Nylas doesn’t attempt to resend.

Retry Attempt Errors

These errors happen when Nylas encounters an issue while sending Outbox messages. In this situation, a daily limit error isn’t applicable to Nylas or the provider. After each message retry attempt, the time frame between each attempt increases. Outbox messages follow the strategies below.

  • With Service - Nylas attempts to send the Outbox message five times with increasing time frames. After five attempts, Nylas routes the Outbox message to the service.
  • Without - Nylas only uses the Outbox parameters. Once the time frame is greater than one hour between each attempt, the attempts become hourly. After the parameters have finished, Nylas doesn’t attempt to resend.

Nylas Dashboard Logs

With the Nylas Dashboard, view your application and account information in the Logs section. Logs contain records and status updates for your API requests.

Webhooks

Subscribing to the job status webhook gives you alerts for Outbox jobs. Get notifications for when a job is successful or has failed.

Successful emails from Outbox return a job.successful webhook. The provider syncs the information when sending an email successfully.

For failed emails from Outbox, Nylas returns the job.failed webhook notification. The provider hasn’t synced the changes and the message didn’t send.

Retrieving Outbox Messages

To view an Outbox message’s latest status update, make a GET request to the Job Status ID endpoint. Use the Outbox message’s job_status_id as the query string parameter.

Endpoint URL: https://api.nylas.com/job-statuses/<JOB_STATUS_ID>

Status Values

Outbox messages have the status values in the list below.

  • "pending" - The message is scheduled.
  • "successful" - The message was sent.
  • "failed" - The message is not able to be sent.
  • "delayed" - The message could not be sent at the scheduled time.
  • "cancelled" - The user has deleted the message.

For failed, delayed, or cancelled statuses, the responses also include a reason field. The text value provides a description of the issue. See the example below for the response.

{
...
"reason": "error executing child workflow",
...
}

GET Outbox Message Request

The code below is an example cURL request.

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

Get Outbox Message Response

The response contains the "original_data" field to show the current content of the Outbox message.

{
"account_id": "5i29uj73a2hqkomxpsnv89sff",
"action": "new_outbox",
"created_at": 1635267717,
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"object": "message",
"original_data": {
"bcc": [
{
"name": "Administrator",
"email": "admin@yahoo.com"
}
],
"body": "POST Outbox test.",
"cc": [
{
"name": "Example",
"email": "example@gmail.com"
}
],
"ext_message_id": "",
"ext_provider_id": 0,
"ext_provider_name": "",
"from": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"message_id_header": "",
"reply_to": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"retry_limit_datetime": 0,
"send_at": 1635268500,
"subject": "Outbox POST request",
"to": [
{
"name": "Sample",
"email": "email@nylas.com"
}
],
},
"send_at": 1635268500,
"status": "pending"
}

Updating Outbox Messages

Using the Outbox message’s job_status_id, you can update the message to change any information. Modifications to Outbox messages can happen up to 5 minutes before scheduled. Any changes within five minutes of the scheduled time may not update. Use the endpoint URL below for PATCH and DELETE API requests.

Endpoint URL: https://api.nylas.com/outbox/<JOB_STATUS_ID>

PATCH Update Outbox Message Request

The code below is a cURL request example.

curl --location --request PATCH 'https://api.nylas.com/outbox/<JOB_STATUS_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '
{
"send_at": 1635268500,
"subject": "Outbox POST request",
"body": "PATCH request update."
}'

PATCH Update Outbox Message Response

The response contains the "original_data" field to show the current content of the Outbox message.

{
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"status": "pending",
"original_data": {
"from": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"subject": "Outbox POST request",
"to": [
{
"name": "Sample",
"email": "email@nylas.com"
}
],
"cc": [
{
"name": "Example",
"email": "example@gmail.com"
}
],
"bcc": [
{
"name": "Administrator",
"email": "admin@yahoo.com"
}
],
"reply_to": [
{
"name": "Sample Account",
"email": "sample@outlook.com"
}
],
"body": "PUT request update.",
"send_at": 1635268500,
"retry_limit_datetime": 0,
}
}

Cancelling Outbox Messages

Using the Outbox message’s job_status_id, you can delete and cancel the message. Use the same endpoint URL for PUT and DELETE API requests.

Endpoint URL: https://api.nylas.com/outbox/<JOB_STATUS_ID>

DELETE Cancel Outbox Message Request

The code below is a cURL example.

curl --location --request DELETE 'https://api.nylas.com/outbox/<JOB_STATUS_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>

DELETE Cancel Outbox Message Response

A successful job shows a 200 status.

What's Next?