Only show these results:
Private Beta

Send v2 Endpoint

The Send v2 endpoint allows you to send emails both synchronously and asynchronously, and allows you to schedule future email sends. Currently we support Gmail and Graph, with full IMAP support coming soon.

Synchronous Send

Synchronous send lets you send email immediately. Synchronous sends a message using the provider and provides a success or failure response instantly. There is no data stored in the Nylas database with this type of send request.

Sending an Email

Make a POST request to https://api.nylas.com/v2/send?sendnow=true or https://api.nylas.com/v2/send/. Passing the query parameter sendnow=true will send the email immediately.

Example:

curl --request POST \
--url https://api.nylas.com/v2/send/ \
--header 'Authorization: Bearer <AUTH TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"body": "This is a test",
"subject": "This is a subject",
"from": [{
"name": "John",
"email": "johndoe@gmail.com"
}],
"to": [{
"name": "Jake",
"email": "jakesmith@outlook.com"
}],
"cc": [{
"name": "Jason",
"email": "jasonpenderghast@yahoo.com"
}],
"bcc": [{
"name": "J. Jonah Jameson",
"email": "jjj@thedailybugle.com"
}]
}'

Synchronous sending may fail for a number of reasons, including:

  • Illegal attachment data
  • Bad credentials
  • Rate limiting

If your message was not successfully sent, you will receive one of the following error codes:

Status Code Description Reason
200 Success Your message was submitted successfully to your email provider for sending.
400 Bad Request Your request was malformed or contained an invalid parameter. The most common issue is invalid JSON.
401 Not Authenticated There was an issue with your access credentials.
404 Not Found The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again
422 Un-processable Entity We cannot process your request due to an error; for example, the provider may be unsupported for synchronous send
500 Internal Server Error An error has occurred within Nylas' system and our team has been alerted. You may wish to try again later.

Creating a Grant with Microsoft Graph

Microsoft Graph requires a special set of scopes to allow Send 2.0 to send email. First, you'll need create an integration:

curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Send v2 Test app",
"provider": "microsoft",
"settings": {
"client_id": "<AZURE_CLIENT_ID>",
"client_secret": "<AZURE_CLIENT_SECRET>",
"tenant": "<TENANT_ID>"
},
"redirect_uris": [
"https://myapp.com/callback-handler"

],
"expires_in": 1209600
}'

Then, as you onboard customer accounts, you'll want to request the specific set of scopes:

curl --location --request POST 'https://beta.us.nylas.com/connect/auth' \
--header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"provider": "microsoft",
"redirect_uri": "https://myapp.com/callback-handler",
"expires_in": 43200,
"account_id": "anz2nojgkfzfo4094wi291hzq",
"scope":[
"Mail.Send",
"offline_access",
"User.Read"
]
}'

Incorrect scopes may result in your account being unable to send email through Send v2.

Attachments

To send attachments with Send 2.0, you must use the existing Nylas Files endpoint. Here is an example call to the Files endpoint:

curl --location --request POST 'https://api.nylas.com/files/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer token' \
--form 'file=@"/Users/test-user/Downloads/1.html"'

This will give you a response that looks like:

[
{
"account_id": "account_id",
"content_type": "text/html",
"filename": "1.html",
"id": "q9h8ith5q3xhrpq0ye40ecux",
"object": "file",
"size": 2899057
}
]

To send an email with a file attachment, simply make a Send 2.0 API call with the attachment(s) in an array, under the file_ids key:

curl --location --request POST 'url' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"body": "This is a body ",
"subject": "This is a subject",
"to": [ {
"name": "<name>",
"email": "<email address>"
}
],
"file_ids":["bvo4bnkb4hvp8dco4ymo94ryr"]
}'

If you wish, you may also embed attachments (such as images) into the HTML of your emails. You may do so by injecting the ID of the attachment directly into the HTML, like so:

curl --location --request POST 'url' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{

"body": "<div><p>Before image</p><img src='\''cid:dm9uws5q0cx9v1ns2yjz17pdh'\''><p>After image</p></div>",
"subject": "Inline image",
"to": [{
"name": "<name>",
"email": "<email address>"
}],
"file_ids": ["dm9uws5q0cx9v1ns2yjz17pdh"]
}'

Note that you must still provide the file ID in the array, as you normally would.

You may wish to add, in the JSON body of your request, a tracking object:

"tracking": {
"link": true,
"opens": true
}

The link key controls whether all links in the email are tracked, and the opens key tracks when an email is opened.

Bounce Detection

Every email sent with Send 2.0 supports Nylas' bounce detection features. You can read more about this (and how to subscribe to bounce detection webhooks) in the Bounce Detection section of our documentation.