Synchronous Send v2.0

The Send v2 endpoint allows you to send emails both synchronously and asynchronously, and also allows you to schedule emails to be sent in the future. We currently support Gmail and Graph, with full IMAP support coming soon.

Synchronous Send

Synchronous Send allows you to send email immediately. Synchronous Send sends a message using the provider and instantly provides either a success or failure response. There's no data stored in the Nylas database with this type of send request.

Sending an Email

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

An example request is shown below:

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": "[email protected]"
  }],
  "to": [{
    "name": "Jake",
    "email": "[email protected]"
  }],
  "cc": [{
    "name": "Jason",
    "email": "[email protected]"
  }],
  "bcc": [{
    "name": "J. Jonah Jameson",
    "email": "[email protected]"
  }]
}'

Synchronous sending may fail for a number of reasons such as:

Unsupported attachment data.
Invalid credentials.
Rate-limiting.

If your message wasn't sent, you'll 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 wasn't 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 the Nylas system and our team has been alerted. Try sending the message again later.

Creating a Grant with Microsoft Graph

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

curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:NYLAS_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
}'

The next step is to request the specific set of scopes as you onboard customer accounts:

curl --location --request POST 'https://beta.us.nylas.com/connect/auth' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:NYLAS_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 v2, you need to use the Nylas Files endpoint. Below 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"'

The response will look like this:

[
    {
        "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, make a Send v2 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"]
}'

You can also embed attachments such as images into the HTML of your emails. To do this, inject the id of the attachment directly into the HTML. An example is shown below:

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

Keep in mind that you'll still need to provide the file ID in the array.

Link Tracking

You can also add a tracking object in the JSON body of your request:

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

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

Bounce Detection

Every email sent with Send v2 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.