--- title: "Create a Draft" method: POST path: "/v3/grants/{grant_id}/drafts" tags: ["Drafts"] --- # Create a Draft `POST /v3/grants/{grant_id}/drafts` Creates a draft. If you provide `tracking_options.domain_name`, Nylas validates the custom hostname and stores its canonical value with the draft's link click and message open tracking settings. If you omit the field, Nylas uses its regional tracking hostname when it creates tracking URLs. ## Request body - object — A draft of a message. You can edit a draft until you send it as a message. - `bcc` MessageParticipant[] — The name/email address pairs of the recipients to be BCC'd. - `name` string - `email` string, email, required - `body` string — The body of the draft, in HTML format. - `cc` MessageParticipant[] — The name/email address pairs of the recipients to be CC'd. - `name` string - `email` string, email, required - `tracking_options` object - `opens` boolean - `thread_replies` boolean - `links` boolean - `label` string - `domain_name` string — The custom hostname to use for link click and message open tracking. The hostname must be registered to the authenticated organization in the [Nylas Dashboard](https://dashboard-v3.nylas.com/organization/domains?tab=hosted-auth) and have an active certificate. Custom tracking hostnames are available on select plans. Contact your Nylas account representative or the [Nylas Sales team](https://www.nylas.com/contact-sales/) to enable this feature for your organization. Nylas trims surrounding whitespace, removes one trailing dot, and converts ASCII letters to lowercase before looking up the hostname. Provide an ASCII fully qualified hostname without a URL scheme, path, port, or wildcard. You must enable `links`, `opens`, or both when you provide this field. A custom tracking hostname does not support `thread_replies` by itself. If you omit this field, Nylas uses its regional tracking hostname. Invalid, inactive, blocked, deleted, and unowned hostnames return the same generic `400` response. If Nylas cannot complete the explicit ownership and certificate lookup, it returns a `5xx` response without falling back to a Nylas hostname. - `attachments` object[] — An array of file attachments to include in the draft. You can use either the `application/json` or `multipart/form-data` schema, depending on the size of the attachment. The `application/json` schema is limited to 3MB, including the message body. The `content` must be Base64-encoded. The `multipart/form-data` schema is limited by the provider to 25MB. See the [Attachments references](/docs/reference/api/attachments/) for more information. - `filename` string - `content` string — Must be Base64-encoded if using the `application/json` schema. Use binary format if using `multipart/form-data`. - `content_type` string — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name. - `content_id` string — (Inline attachments only) The alphanumeric `cid` from the `` tag in the email's HTML. For example, you might see something like `` in the message body. - `content_disposition` string — (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name. - `from` MessageParticipant[] — An array that contains a single name and email address pair that Nylas sets as the `from` header. By default, Nylas uses the email address associated with the `grant_id`. Nylas supports multiple `from` addresses for email aliases only. - `name` string - `email` string, email, required - `is_plaintext` boolean — 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. - `reply_to` MessageParticipant[] — An array of name/email address pairs that should receive replies to the message. This is used to set an alternative `Reply-To` header in the sent message. Not all providers support setting this in a draft. - `name` string - `email` string, email, required - `reply_to_message_id` string — The unique identifier of the message to which you want to draft a reply. - `starred` boolean — If `true`, the draft is starred. - `subject` string — The subject line of the draft. - `to` MessageParticipant[] — The name/email address pairs of the recipients. - `name` string - `email` string, email, required - `custom_headers` object[] — An array of custom headers to add to the message. - `name` string - `value` string - `metadata` Metadata — The metadata associated with the object. For more information, see [Metadata](/docs/reference/api/#metadata). - `template` object — The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields. - `id` string — The template ID. - `strict` boolean — When `true`, Nylas returns an error if the template contains variables that aren't defined in the `variables` object. - `variables` object — A set of key/value pairs representing variables to substitute for values in the template. - `signature_id` string — The ID of a [signature](/docs/v3/email/signatures/) to append to the draft body. Nylas inserts the signature after a line break at the end of the body. Only one signature can be used per draft. ## Response `200` Draft - object - `request_id` string — The request ID. - `data` object — A draft of a message. You can edit a draft until you send it as a message. - `bcc` MessageParticipant[] — The name/email address pairs of the recipients to be BCC'd. - `name` string - `email` string, email, required - `body` string — The body of the draft as either plain-text or HTML content. If the draft has both plain-text and HTML, Nylas returns the HTML version. - `cc` MessageParticipant[] — The name/email address pairs of the recipients to be CC'd. - `name` string - `email` string, email, required - `attachments` Attachment[] — An array of Attachment objects. For Google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included. - `id` string, required — The ID of the attachment. - `content_type` string — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name. The value of this field is exactly the same as the email attachment's `Content-Type` header. The provider might set additional parameters, such as `name` and `charset`. Nylas returns an empty `content_type` field if an attachment file name contains non-ASCII characters (for example, accented characters like `ü`). This is because Google can't detect its content type. - `filename` string — The file name of the attachment. - `grant_id` string — The ID of grant for the connected user. - `content_id` string — (Inline attachments only) The alphanumeric `cid` from the `` tag in the message's HTML. For example, you might see something like `` in the message body. Sometimes, the `content_id` value is contained in angle brackets (for example, ``). - `content_disposition` string — (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name (for example, `inline; filename="some-image.jpeg"`). - `is_inline` boolean — If `true`, indicates that the attachment is an inline file. - `size` integer — The size of the attachment, in bytes. - `folders` string[] — A list of folder IDs. For Microsoft, only a single folder is supported. For Google, multiple folders may exist. - `from` MessageParticipantResponse[] — An array containing a single name/email address pair, to set as the `From` header. - `name` string - `email` string, email - `grant_id` string — The ID of grant for the connected user. - `id` string — A globally unique object identifier for Microsoft accounts. An email address for Google accounts. - `metadata` Metadata — The metadata associated with the object. For more information, see [Metadata](/docs/reference/api/#metadata). - `object` string — The object type of the response. In this case, `draft`. - `reply_to` MessageParticipant[] — An array of name/email address pairs that should receive replies to the message. - `name` string - `email` string, email, required - `snippet` string — A short snippet of the message body (the first 100 characters, with any HTML tags removed). This is useful for displaying a preview of a draft message. - `starred` boolean — When `true`, shows that the Draft has been starred by the user. For EWS, this is only supported for Microsoft Exchange 2010 or later. - `subject` string — The subject line of the draft. - `thread_id` string — A reference to the parent Thread object. If this is a new draft, the thread is empty. - `to` MessageParticipant[] — The name/email address pairs of the recipients. - `name` string - `email` string, email, required ## Other responses - `400` — Bad Request - `401` — Unauthorized - `429` — Rate Limit - `504` — Provider Failure --- [API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)