Sign in
Messages

Send a Message

Sends the specified message. If you want to send the message immediately, omit the send_at field from your request. If you want to schedule it to be sent later, set send_at to the time you want to send the message, in seconds using the Unix timestamp format.

For more information about scheduling messages, see Schedule messages to send in the future.

To use a custom hostname for link click or message open tracking, provide tracking_options.domain_name. Nylas validates that the authenticated organization owns an active certificate for the hostname. If you omit the field, Nylas uses its regional tracking hostname. Scheduled sends validate an explicit custom hostname when you create the schedule and revalidate it immediately before delivery. If the hostname is no longer eligible, the scheduled send fails without falling back to a Nylas hostname.

(Google and Microsoft Graph only) When scheduling a message, you can set use_draft to true to save the message in the user's Drafts folder until it's sent.

Nylas also supports sending raw MIME messages. For more information, see Send messages with MIME data.

Limitations

Microsoft Graph and iCloud don't support the List-Unsubscribe-Post or List-Unsubscribe headers.

post/v3/grants/{grant_id}/messages/send

Query parameters

fields'standard' | 'include_headers' | 'include_basic_headers'

Include message headers in the send response. Headers are returned in the same headers array format as Get Message responses.

  • standard: Returns the standard send response (no headers array).
  • include_headers: Returns the full set of headers on the response.
  • include_basic_headers: Returns only the three RFC threading headers (Message-ID, In-Reply-To, References). Use this option when you only need to track message identity and thread relationships — payload size is significantly smaller than include_headers.

Supported on synchronous send only. The parameter has no effect when you set the send_at field on the request (scheduled send is asynchronous and doesn't return headers).

For provider support details, see Using email headers and MIME data.

Request body

bodystring

The HTML body of the message.

is_plaintextboolean

When true, the message body is sent as plain text and the MIME data doesn't include the HTML version of the message. When false, the message body is sent as HTML.

metadataMetadata

The metadata associated with the object. For more information, see Metadata.

reply_to_message_idstring

The ID of the message you're replying to. For Gmail and Microsoft Graph, this is the message ID on the provider. For IMAP Send, this is the RFC822 Message-ID header of the message you're replying to.

send_atinteger

The time when Nylas should send the message, in seconds using the Unix timestamp format. This time must be at least one minute in the future from the time you make your request. You can schedule a message to be sent up to 30 days in the future. If the request includes tracking_options.domain_name, Nylas validates the hostname when it creates the schedule and revalidates it before delivery.

subjectstring

The subject of the message.

use_draftboolean

(Google and Microsoft only) When true, Nylas saves the message in the user's Drafts folder until its send_at time. This field can't be true if send_at is undefined.

signature_idstring

The ID of a signature to append to the message body. Nylas inserts the signature after a line break at the end of the body, including after any quoted text in replies and forwards. Only one signature can be used per message.

Example request

{
  "attachments": [
    {
      "content": "YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL=",
      "content_disposition": "attachment; filename=\"nylas_logo.png\"",
      "content_id": "ce9b9547-9eeb-43b2-ac4e-58768bdf04e4",
      "content_type": "image/png",
      "filename": "nylas_logo.png"
    }
  ],
  "bcc": [
    {
      "name": "Leyah Miller",
      "email": "leyah@example.com"
    }
  ],
  "body": "Looking forward to seeing you!",
  "cc": [
    {
      "name": "Kaveh",
      "email": "kaveh@example.com"
    }
  ],
  "custom_headers": [
    {
      "name": "Email-Campaign",
      "value": "meetings"
    }
  ],
  "from": [
    {
      "name": "Nyla",
      "email": "nyla@example.com"
    }
  ],
  "reply_to": [
    {
      "name": "Leyah Miller",
      "email": "leyah@example.com"
    }
  ],
  "subject": "Reminder: Annual Philosophy Club Meeting",
  "template": {
    "id": "b79c82b2-a51b-4c54-8469-28006a43551a",
    "strict": true,
    "variables": {
      "user": {
        "name": "Leyah",
        "surname": "Miller"
      }
    }
  },
  "to": [
    {
      "name": "Kim Townsend",
      "email": "kim@example.com"
    }
  ],
  "tracking_options": {
    "domain_name": "tracking.example.com"
  },
  "signature_id": "sig_abc123"
}

Response

200 OK

grant_idstring required
request_idstring required

Example response

{
  "data": {
    "attachments": [
      {
        "content_disposition": "attachment",
        "content_type": "text/calendar",
        "filename": null,
        "content_id": "4kj2jrcoj9ve5j9yxqz5cuv98",
        "size": 1708
      },
      {
        "content_disposition": "attachment",
        "content_type": "application/ics",
        "filename": "invite.ics",
        "content_id": "70jcsv367jaiavt4njeu4xswg",
        "size": 1708
      }
    ],
    "bcc": [
      {
        "name": "Jon Snow",
        "email": "jon.snow@example.com"
      }
    ],
    "body": "Hello, I just sent a message using Nylas!",
    "cc": [
      {
        "name": "Jon Snow",
        "email": "jon.snow@example.com"
      }
    ],
    "date": 1635355739,
    "folders": [
      "8l6c4d11y1p4dm4fxj52whyr9",
      "d9zkcr2tljpu3m4qpj7l2hbr0"
    ],
    "from": [
      {
        "name": "Jon Snow",
        "email": "jon.snow@example.com"
      }
    ],
    "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
    "headers": [
      {
        "name": "Date",
        "value": "Thu, 15 Aug 2024 00:59:58 +0000 (UTC)"
      }
    ],
    "id": "5d3qmne77v32r8l4phyuksl2x, nyla@example.com",
    "object": "message",
    "reply_to": [
      {
        "name": "Jon Snow",
        "email": "jon.snow@example.com"
      }
    ],
    "reply_to_message_id": "1t8tv3890q4vgmwq6pmdwm8qg",
    "schedule_id": "c712c7ec-0bbd-4038-a69a-d7c287b026f5",
    "snippet": "You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern\nTime - Toronto Joining info",
    "subject": "Nylas Send v3 Email",
    "thread_id": "1t8tv3890q4vgmwq6pmdwm8qgsaer",
    "tracking_options": {
      "opens": true,
      "thread_replies": true,
      "links": true,
      "label": "Tracking test"
    },
    "to": [
      {
        "name": "Jon Snow",
        "email": "jon.snow@example.com"
      }
    ],
    "unread": true
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.