Only show these results:

Send Emails with Nylas

Nylas offers several ways to send emails.

  • Create and send a draft.
  • Send an email directly.
  • Schedule an email to be sent later.

You'll learn how to make API requests for each method and go over the differences between each.

Send and Schedule Messages

Using the /outbox endpoint, you can schedule messages to be sent at a future date or send emails directly.

To schedule a message add send_at to schedule the message.

Schedule 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": "Dorothy@spacetech.com",
"name": "dorothy@spacetech.com"
}
],
"from": [
{
"email": "kat@spacetech.com",
"name": "Katherine"
}
],
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details."
}'

Deliverability for Outbox

Outbox has a much higher rate of deliverability than out /send endpoint because of async sending and error handling.

Outbox Async Sending

Outbox sends messages asynchronously. Unlike send, which forces your app to wait for a response and could cause delays to the end-user, Outbox returns a job status ID right away. You can use the job status ID to check if the message has been sent. And once sent, Outbo will send a job status webhook.

Outbox Error Handling

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 AM was returned as a 429, and daily limits were reached. Nylas will start Tuesday again at 00:00.

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

Learn More

The Outbox endpoint has many other useful features, review the Outbox Endpoint Guide.

Create and Send Drafts

Drafts are sent using the account's original SMTP/ActiveSync gateway.

You have to make 2 API calls, POST /drafts and POST /send, to create and send drafts.

When you create a draft with Nylas, the draft is synced with your provider. You can access the draft and make updates as long as the draft has not been deleted.

Create a Draft

To create a draft, send a POST to /drafts.

Create a Draft Request

All the fields for creating a message are optional. You can send an empty draft request, and a blank draft is created.

Let's review a few of the request params:

  • reply_to - Name and emails added here to set an alternative Reply-To header in the final sent message. Not all providers support setting this in a draft. Reply-To is where replies are sent instead of using from.
  • reply_to_message_id - If you are replying to a specific message, make sure to include the message ID. You can get the message ID from /messages.
  • file_ids - Files should be uploaded to the /files endpoint before being attached to messages.

Learn More

Review the /drafts endpoint for a full list of parameters and definitions.

curl --location --request POST 'https://api.nylas.com/drafts/' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"subject": "From Nylas",
"to": [
{
"email": "swag@nylas.com",
"name": "Nylas"
}
],
"from": [
{
"email": "you@example.com",
"name": "Your Name"
}
],
"reply_to": [
{
"name": "Nylas",
"email": "swag@nylas.com"
}
],
"reply_to_message_id": "1d00e908341a4a889ba4",
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"file_ids": [
"0a512d9b79584e989ca7"
]
}'

Send a Draft

After you create a draft, use the /send to send your email.

Send Drafts Request

To get the most recent version of a draft, you can request the /draft/{draft_id} or find it in a list of all /drafts.

The version must be the most recent version, or the request will fail.

Learn More

Review the Send Drafts endpoint.

curl -X POST 'https://api.nylas.com/send' \
-H 'Authorization: Bearer <access_token>' \
-d '{
"draft_id": "{draft_id}",
"version": 0
}'

Send an Email Directly

Send directly uses the account's original SMTP/ActiveSync gateway.

Sending an email directly will bypass creating a draft and send the email straight to the recipient. The email shows in the sent folder.

Send Directly Request

To send an email directly, make a POST request to /send.

curl --location --request POST 'https://api.nylas.com/send' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"subject": "From Nylas",
"to": [
{
"email": "swag@nylas.com",
"name": "Nylas"
}
],
"from": [
{
"email": "you@example.com",
"name": "Your Name"
}
],
"reply_to": [
{
"name": "Nylas",
"email": "swag@nylas.com"
}
],
"reply_to_message_id": "1d00e908341a4a889ba4",
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"file_ids": [
"0a512d9b79584e989ca7"
]
}'

Learn More

Review Send Directly for a list of params.

Deliverability for Drafts and Send Endpoint

Sending operations are synchronous, meaning the request will block until the submission has succeeded or failed. In the event of failure, the sending API will not automatically retry.

We recommend that you apply backoff when HTTP 503's are returned. Your app may need to wait 10-20 minutes, or SMTP servers may continue to refuse connections for a particular account. For some providers like Gmail, there are hard limits on the number of messages you can send per day.

If large-volume sending continues to fail for your application, we recommend switching to a transactional sending service like Mailgun, Sendgrid, Mandrill, or Amazon SES.

Sending Timeouts

A successful request to the send endpoint can sometimes take up to two minutes for self-hosted Exchange accounts, though the average send time is around 2 seconds. We recommend that you set a minimum timeout of 150 seconds, to ensure you receive a response from us.

Sending Errors

Sometimes message delivery can fail if the user’s email gateway rejects the message. This could happen for a number of reasons, including illegal attachment data, bad credentials, or rate-limiting. If your message is submitted successfully, the server will respond with a HTTP response code of 200 OK. If your message could not be submitted, the server will respond with an appropriate error code.

Status Code Description Reason
200 OK Your message was submitted successfully for sending.
400 Bad Request Your request was malformed or contained an invalid parameter. The most common issue is invalid JSON.
402 Message Rejected The mail provider rejected your message because of its content or recipients. If the message includes "Sending to at least one recipient failed", it means that your message may have been delivered to only a subset of participants.
403 Unauthorized The server was unable to authenticate with the user's mail provider. Re-authenticate the user and try again.
422 Mail provider error An error occurred while the mail provider was sending the message. See the server_error value in the response body JSON for more information.
429 Quota Exceeded The user has exceeded their mail provider's sending quota. Unfortunately, there is no reliable way to determine these limits. Wait and try again later.
429 Account Throttled The account is in a throttled state and the mail server has asked us to temporarily stop making requests. Wait and try again later.
429 Nylas API Rate Limit You've made too many requests to the Nylas API too quickly. Wait and try again later. See Rate limiting.
503 Service Unavailable There was an error connecting to the user's mail provider. Wait and try again.

In addition, the response body contains a JSON object with information about the specific error, including the following attributes:

Status Code Type Reason
type string Error type
message string A brief human-readable description of the error.
server_error string (optional) The original error returned by the user's mail server.

402 errors with "Sending to at least one recipient failed"

If any of the recipient addresses contain non-ASCII characters (such as characters with accents or other diacritics), these recipients will be among those to whom delivery failed. Nylas is not currently able to send messages to such email addresses.

Deciding Which API to Use

  • Outbox
    • When you need to send a large number of emails and need a high rate of deliverability.
    • Message failures are retried.
    • Need to schedule messages to send at a later date.
    • Messages are synced to the provider's sent folder if possible.
  • Create and Send Drafts
    • When you want to create emails that don't need to be sent right away. Messages are synced to the provider's draft folder if possible.
    • Sending is synchronous, meaning the request will block until the submission has succeeded or failed. In the event of failure, the sending API will not automatically retry.
  • Send Directly
    • Good for sending a small number of emails without saving them to drafts first. Messages are synced to the provider's sent folder if possible.
    • Sending is synchronous, meaning the request will block until the submission has succeeded or failed. In the event of failure, the sending API will not automatically retry.

What's Next?