deprecated

Asynchronous Send endpoint guide

This feature is deprecated and is no longer supported.

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

Sending Messages

The Asynchronous Send 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/send?sendnow=false or https://api.nylas.com/v2/outbox (deprecated)

Send Immediately

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

POST Asynchronous Send Request

The code below is a cURL request example:

curl --location --request POST 'https://api.nylas.com/v2/send?sendnow=false' \
--header 'Accept: application/json, application/gzip' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '{
   "to": [
       {
           "email": "nahida@example.com",
           "name": "Nahida"
       },
       {
           "email": "dain@example.com",
           "name": "Dain"
       }
   ],
   "from": [{
       "email": "leah@example.com",
       "name": "Leah"
   }],
   "subject": "Asynchronous Send Endpoint",
   "body": "Content for body of message.",
   "reply_to": [{
       "email": "leah@example.com",
       "name": "Leah"
   }]
}'

POST Asynchronous Send Response

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

{
   "job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
   "status": "pending",
   "original_data": {
       "from": [{
            "name": "Leah",
            "email": "leah@example.com"
        }],
       "subject": "POST Request Asynchronous Send",
       "to": [{
            "name": "Nahida",
            "email": "nahida@example.com"
        }],
       "cc": [{
            "name": "Dain",
            "email": "dain@example.com"
        }],
       "bcc": [{
            "name": "Administrator",
            "email": "admin@example.com"
        }],
       "reply_to": [{
            "name": "Leah",
            "email": "leah@example.com"
        }],
       "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 a set time. Scheduled Asynchronous Send messages use the send_at object field highlighted in the code sample below. View the Request body objects section below for more about specific Asynchronous Send objects.

POST Asynchronous Send 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, application/gzip' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '{
   "to": [
       {
           "email": "nahida@example.com",
           "name": "Nahida"
       },
       {
           "email": "dain@example.com",
           "name": "Dain"
       }
   ],
   "from": [{
       "email": "leah@example.com",
       "name": "Leah"
   }],
   "subject": "Asynchronous Send Endpoint",
   "body": "Content for body of message.",
   "reply_to": [{
       "email": "leah@example.com",
       "name": "Leah"
   }],
   "send_at": 1634922000,
   "retry_limit_datetime": 1634933400
}'

POST Asynchronous Send Scheduled Response

The response contains the "original_data" field to show the current content of the Asynchronous Send message. The send_at field displays the time the message will be sent.

{
   "job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
   "status": "pending",
   "original_data": {
       "from": [{
            "name": "Leah",
            "email": "leah@example.com"
        }],
       "subject": "POST Request Asynchronous Send",
       "to": [{
            "name": "Nahida",
            "email": "nahida@example.com"
        }],
       "cc": [{
            "name": "Dain",
            "email": "dain@example.com"
        }],
       "bcc": [{
            "name": "Administrator",
            "email": "admin@example.com"
        }],
       "reply_to": [{
            "name": "Leah",
            "email": "leah@example.com"
        }],
       "body": "POST Asynchronous Send test.",
       "send_at": 1635267900,
       "original_send_at": 1635267900,
       "retry_limit_datetime": 1635440700,
   }
}

Asynchronous Send Configuration

The sections below cover options that are unique to Asynchronous Send requests and responses.

Job Status ID

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

GET - Retrieve the status of Asynchronous Send messages.
PUT - Update Asynchronous Send messages.
DELETE - Delete Asynchronous Send messages.

{
   ...
   "job_status_id": "6qwo2w0nreusrgb3syel9vjmk",
   ...
}

Message Tracking Support

Asynchronous Send also supports all Message tracking features from the Send endpoint.

Request Body Objects

While Asynchronous Send is similar to the Send endpoint, it has additional request body objects that are described below. These values add functionality to Asynchronous Send 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 seven days from the scheduled time.

Service Integration

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

Asynchronous Send Retry Logic

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

Daily Limit Errors

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

With Service - Nylas routes the Asynchronous Send message to the service when experiencing a daily limit error event.
Without - Nylas only uses the Asynchronous Send 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 Asynchronous Send 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. Asynchronous Send messages follow the strategies below:

With Service - Nylas attempts to send the Asynchronous Send message five times with increasing time frames. After five attempts, Nylas routes the Asynchronous Send message to the service.
Without - Nylas only uses the Asynchronous Send parameters. Once the time frame is greater than an hour between each attempt, the attempts become hourly. After the parameters have finished, Nylas no longer attempts 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

In 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 Asynchronous Send jobs. Get notifications for when a job is successful or has failed.

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

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

Retrieving Asynchronous Send Message Statuses

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

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

Status Values

Asynchronous Send messages have a status value from the list below:

pending - The message is scheduled.
successful - The message was sent.
failed - The message isn't able to be sent.
delayed - The message couldn't 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 Asynchronous Send 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 Asynchronous Send Message Status Response

The response contains the original_send_at and send_at fields to show the Asynchronous Send 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 Asynchronous Send Messages

Using the Asynchronous Send message’s job_status_id, you can update the message to change any information. Modifications to Asynchronous Send messages can happen up to five 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 Asynchronous Send 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, application/gzip' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--data-raw '{
   "send_at": 1635268500,
   "subject": "Asynchronous Send POST request",
   "body": "PATCH request update."
}'

PATCH Update Asynchronous Send Message Response

The response contains the original_data field to show the current content of the Asynchronous Send 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 the updated send_at value.

{
   "job_status_id": "5qlu0dvy5vq7p3z0281isc0nj",
   "status": "pending",
   "original_data": {
       "from": [{
            "name": "Leah",
            "email": "leah@example.com"
        }],
       "subject": "Asynchronous Send POST request",
       "to": [{
            "name": "Nahida",
            "email": "nahida@example.com"
        }],
       "cc": [{
            "name": "Dain",
            "email": "dain@example.com"
        }],
       "bcc": [{
            "name": "Administrator",
            "email": "admin@example.com"
        }],
       "reply_to": [{
            "name": "Leah",
            "email": "leah@example.com"
        }],
       "body": "PATCH request update.",
       "send_at": 1635268500,
       "original_send_at": 1635268500,
       "retry_limit_datetime": 1639611100,
   }
}

Cancelling Asynchronous Send Messages

Using the Asynchronous Send 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 Asynchronous Send 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, application/gzip' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>

DELETE Cancel Asynchronous Send Message Response

A successful job shows a 200 status.

What's Next?

[Asynchronous Send API Reference](/docs/api/v2/#tag--Asynchronous Send)
Job Status API Reference