Only show these results:
Private 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/v2/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/v2/outbox' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '
{
"to": [
{
"email": "[email protected]",
"name": "Sample"
},
{
"email": "[email protected]",
"name": "Example"
}
],
"from": [{
"email": "[email protected]",
"name": "Sample Account"
}],
"subject": "Outbox Endpoint",
"body": "Content for body of message.",
"reply_to": [{
"email": "[email protected]",
"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": "[email protected]"
}
],
"subject": "POST Request Outbox",
"to": [
{
"name": "Sample",
"email": "[email protected]"
}
],
"cc": [
{
"name": "Example",
"email": "[email protected]"
}
],
"bcc": [
{
"name": "Administrator",
"email": "[email protected]"
}
],
"reply_to": [
{
"name": "Sample Account",
"email": "[email protected]"
}
],
"body": "Content for body of message.",
"send_at": 1639431155,
"original_send_at": 1639431155,
"retry_limit_datetime": 1640035955,
}
}

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/v2/outbox' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '
{
"to": [
{
"email": "[email protected]",
"name": "Sample"
},
{
"email": "[email protected]",
"name": "Example."
}
],
"from": [{
"email": "[email protected]",
"name": "Sample Account"
}],
"subject": "Outbox Endpoint",
"body": "Content for body of message.",
"reply_to": [{
"email": "[email protected]",
"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. The "send_at" field displays the time the message will be sent.

{
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"status": "pending",
"original_data": {
"from": [
{
"name": "Sample Account",
"email": "[email protected]"
}
],
"subject": "POST Request Outbox",
"to": [
{
"name": "Sample",
"email": "[email protected]"
}
],
"cc": [
{
"name": "Example",
"email": "[email protected]"
}
],
"bcc": [
{
"name": "Administrator",
"email": "[email protected]"
}
],
"reply_to": [
{
"name": "Sample Account",
"email": "[email protected]"
}
],
"body": "POST Outbox test.",
"send_at": 1635267900,
"original_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",
...
}

Message Tracking Support

Outbox supports all Message Tracking features from the Send endpoint as well.

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_a" 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.

Invalid Authentication

Requests from invalid authentications are rejected without retry attempts. Accounts experiencing invalid authentication during scheduling or retry attempts result in permanent failure. Re-authenticate the account information to create new requests.

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 Message Statuses

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": "Reached retry limit datetime",
...
}

Get Outbox Message Status 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 Status Response

The response contains the original_send_at and send_at fields to show the Outbox message's current scheduled delivery.

{
"account_id": "5i29uj73a2hqkomxpsnv89sff",
"action": "new_outbox",
"created_at": 1635267717,
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"object": "message",
"original_send_at": 1635268500,
"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/v2/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/v2/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. Both the send_at and original_send_at values update to the PATCH request value. Without an assigned value, the retry_limit_datetime object defaults to 24 hours after updated send_at value.

{
"job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
"status": "pending",
"original_data": {
"from": [
{
"name": "Sample Account",
"email": "[email protected]"
}
],
"subject": "Outbox POST request",
"to": [
{
"name": "Sample",
"email": "[email protected]"
}
],
"cc": [
{
"name": "Example",
"email": "[email protected]"
}
],
"bcc": [
{
"name": "Administrator",
"email": "[email protected]"
}
],
"reply_to": [
{
"name": "Sample Account",
"email": "[email protected]"
}
],
"body": "PATCH request update.",
"send_at": 1635268500,
"original_send_at": 1635268500,
"retry_limit_datetime": 1639611100,
}
}

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/v2/outbox/<JOB_STATUS_ID>

DELETE Cancel Outbox Message Request

The code below is a cURL example.

curl --location --request DELETE 'https://api.nylas.com/v2/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?