Send Emails with Nylas

Nylas offers several ways to send emails.

Create and send a draft.
Send an email directly.

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

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

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.

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 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 avoid 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
- 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?

Create a Draft - Create a new draft.
Send a Draft - Send created drafts.
Message Tracking - Receive notifications for certain message actions.