Send Email With Nylas

Learn how to send emails with Nylas.

What you'll learn

In this guide, you'll learn how to do the following:

Choose how to send emails.
Create and send a draft.
Send an email directly without creating a draft.

Step 1: Choose how to send emails

Decide which sending method is best for your application.

Create and send drafts - Ideal for preparing emails that don't need to be sent right away. Messages are synced to the provider's draft folder if possible.
Send emails directly without creating drafts - 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.

In both cases, sending operation is synchronous, and the request blocks until the submission succeeds or fails. In the event of failure, the sending API won't automatically retry. For more information, refer to Deliverability for drafts and send endpoint.

Step 2: Send emails with Nylas

You can either create and send a draft, or send an email directly without creating a draft.

Option 1: Create and send drafts

To create and send drafts, you need to make the following API requests:

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 isn't deleted.

Create a draft

Make a POST /drafts request.

The following are some of the request parameters that can be useful:

All request parameters are optional. If you send a request without any request parameters, Nylas creates a draft with no content.

reply_to - Add name and emails to set a Reply-to address in the Reply-to header. A Reply-to address is where reply messages are sent to and can be different from the From: address. Not all providers support setting a Reply-to address in drafts.
reply_to_message_id - If you're replying to a specific message, include the message ID. You can retrieve the message ID by making a GET /messages request.
file_ids - Upload files before you attach them to messages. You can retrieve file IDs by make a GET /files request.

For more information on available parameters, refer to POST /drafts.

Example: Create a draft

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

After you create a draft, make a POST /send request to send your email. Make sure that you specify the draft_id and version in the request.

If there is a newer draft version than the one you're trying to send, the request fails. To get the latest draft version, make a GET /draft/{draft_id} request.

Example: Send a draft

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

Option 2: Send emails without creating drafts

To send an email directly without creating a draft, make a POST /send request.

Example: Send an email without creating a draft

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"
    ]
}'

Deliverability for drafts and send endpoint

Sending operations are synchronous, and the request blocks until the submission succeeds or fails. In the event of failure, the sending API won't automatically retry.

Consider applying 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 information on the number of messages you can send per day, refer to Provider rate limits. If large-volume sending continues to fail for your application, switch 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 two seconds. To make sure that you receive a response from Nylas, set the minimum timeout to 150 seconds.

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 fails. 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. Avoid using this message_id_header with the @mailer.nylas.com domain for email configurations.

Video walkthrough

Prefer video? You can watch our LiveStream Coding with Nylas.

More resources

Learn about Message Tracking - Receive notifications for certain message actions.
Read the blog post Send and Read Emails Using Node-Red and the Nylas APIs.
Read the blog post How to Send an Email in Any Language Using the Nylas APIs.