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.