Only show these results:

Send Emails with Nylas

Nylas offers several ways to send emails. You can do the following:

  • Create and send a draft.
  • Send an email directly.

In this guide, we go over how to make API requests for each method and the differences between each method.

Create and Send Drafts

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

You have to make two API calls to create and send drafts:

  • POST /drafts
  • POST /send

When you create a draft with Nylas, the draft is synced with your email provider. You can access the draft and make updates as long as the draft hasn't 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 will be created.

A few of the request parameters are explained below:

  • reply_to - Add name and emails 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're 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.

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

An example script is shown below:

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": "[email protected]",
"name": "Nylas"
}
],
"from": [
{
"email": "[email protected]",
"name": "Your Name"
}
],
"reply_to": [
{
"name": "Nylas",
"email": "[email protected]"
}
],
"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

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

Send Drafts Request

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

If the version isn't the most recent, the request will fail.

For more information, review our documentation on the Send drafts endpoint.

An example script is shown below:

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

Send an Email Directly

Sending an email directly uses the account's original SMTP/ActiveSync gateway.

This method bypasses creating a draft and sends the email straight to the recipient. The email appears in the sent folder.

Request to Send Directly

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": "[email protected]",
"name": "Nylas"
}
],
"from": [
{
"email": "[email protected]",
"name": "Your Name"
}
],
"reply_to": [
{
"name": "Nylas",
"email": "[email protected]"
}
],
"reply_to_message_id": "1d00e908341a4a889ba4",
"body": "This email was sent using the Nylas email API. Visit https://nylas.com for details.",
"file_ids": [
"0a512d9b79584e989ca7"
]
}'

Review Send directly for a list of parameters.

Deliverability for Drafts and Send Endpoint

Sending operations are synchronous, which means the request will block until the submission has succeeded or failed. In the event of failure, the sending API won't automatically retry.

We recommend that you apply backoff when HTTP 503's are returned. Your application may need to wait anywhere from 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 such as 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 can happen for a number of reasons, including illegal attachment data, bad credentials, or rate-limiting. If your message is submitted successfully, the server responds with a HTTP response code of 200 OK. If your message wasn't submitted, the server responds with an appropriate error code.

Below is a table of error codes:

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 for more information.
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 recipient addresses contain non-ASCII characters, such as characters with accents or other diacritics, delivery will fail. Nylas is currently unable to send messages to email addresses that contain these characters.

Email Message ID Header Behavior

Sending an email using the Nylas API creates a unique message_id_header value in the sender's database. This value is required for the provider's SMTP server. The text shown below with @mailer.nylas.com is an example of the Nylas message_id_header value for internal use.

[email protected]   

This is part of the standard protocol when using Nylas as an email client. The header is only visible on the sender's database and isn't an email object to use or update.

The provider's SMTP server may modify this value during the sending process, so we don't recommend using this message_id_header with the @mailer.nylas.com domain for email configurations.

Deciding Which API to Use

  • 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
    • Ideal 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?