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.