Skip to content

Send messages with Nylas

Nylas offers multiple ways to send messages. This page describes how to choose the best method for your project, how to create and send a draft, and how to send a message without creating a draft.

Choose how to send messages

Nylas offers two different ways to send messages:

  • Create and send a draft: This method is ideal for preparing messages that you don’t need to send immediately. Nylas syncs drafts to the provider’s Draft folder, if possible.
  • Send message without creating draft: This method is ideal for sending a small number of messages without saving them as drafts first. Nylas syncs messages to the provider’s Sent folder, if possible.

In both cases, the sending operation is synchronous (meaning Nylas sends items one at a time) and the request blocks until the submission either succeeds or fails. If the submission fails, Nylas does not automatically try to send the message again. For more information, see Deliverability for drafts and Send endpoint.

When you make a Send Message request, Nylas connects to the provider to send the message as the user. Because of this, providers see the activity as the user sending a message, rather than an external platform making the request on the user’s behalf.

Messages sent through Nylas have very high deliverability, but might be subject to rate-limiting and abuse detection from the provider. See Improve email deliverability for more information and a list of best practices.

Create and send a draft

If you want to prepare a message that you don’t need to send immediately, you can create a draft and send it later. When you create a draft with Nylas, it’s synced with the provider. You can access it and make updates as long as it isn’t deleted.

To create a draft in Nylas v3, make a Create Draft request and include any relevant information, or use the Nylas SDKs. If you make the request with no parameters, Nylas creates a draft with no content.

When you’re ready, you can send the draft by making a Send Draft request or by using the SDKs.

Create and send a message

If you want to create and send a message immediately, make a Send Message request or use the Nylas SDKs.

Draft deliverability and the Send endpoint

Send operations are synchronous (meaning Nylas sends items one at a time), and the request blocks until the submission succeeds or fails. If the request fails, Nylas does not automatically try to send the message again.

Nylas recommends that you apply a backoff strategy when you receive 503 errors. Your application might need to wait between 10–20 minutes, or else SMTP servers might continue to refuse connections for the affected user.

For information on the number of messages you can send per day, see the Provider rate limits documentation. If large-volume sending continues to fail for your application, Nylas recommends you switch to a transactional sending service (for example, Mailgun, SendGrid, Mandrill, or Amazon SES).

Bounce detection

Nylas monitors for and notifies you when a user gets a message bounce notification. Bounce notifications are sent by a recipient’s provider when the message can’t be delivered, and usually include a detailed error message. When a user receives a notification that a message bounced, Nylas scans it and grabs the cause from the error message.

Messages can bounce for a variety of reasons, and can be considered either “soft” bounces (those with a temporary root cause, like the recipient’s inbox being full) or “hard” bounces (those with a permanent root cause, like the recipient’s email address no longer exists). Currently, Nylas supports hard bounces only, and publishes mailbox_unavailable and domain_not_found bounces. For more information about bounce detection, see the message.bounce_detected notification schema and Soft vs. Hard Bounce - what’s the difference? on the Nylas blog.

The message ID header

Sending a message using the Nylas Email API creates a unique message_id_header in the sender’s database, similar to the example below.

This value is required for the provider’s SMTP server, and is part of the standard protocol when using Nylas as an email client. The header is visible only on the sender’s database, and isn’t an object that you can use or update.

The provider’s SMTP server might change this value during the sending process. Nylas recommends you avoid using this message_id_header with the @mailer.nylas.com domain for email configuration.

Override sender display name

When you send messages using Nylas, you can set the sender’s display name by modifying the from.name parameter in your request.

curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"subject": "Reaching out with Nylas",
"to": [{
"name": "Leyah Miller",
"email": "[email protected]"
}],
"from": [{
"name": "Nyla",
"email": "[email protected]"
}]
}'

If you don’t include the from field when you send a message, Nylas uses the account’s default display name.

Limitations for sending messages

  • Microsoft Graph and iCloud don’t support the List-Unsubscribe-Post or List-Unsubscribe headers. Because of this, Nylas can’t support these headers for messages sent from Microsoft Graph and iCloud accounts.
  • Some providers change folders immediately after a message sends successfully (for example, moving the message from the Outbox folder to Sent). Because of this, you might receive multiple message.updated notifications for a single send request.
  • Nylas automatically de-duplicates some webhook notifications to avoid spam, so you might receive a message.updated notification instead of a message.created notification.