# Create a Draft

> **POST** `https://api.us.nylas.com/v3/grants/{grant_id}/drafts`

Source: https://developer.nylas.com/docs/reference/api/drafts/post-draft/

Creates a draft.

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. |

## Request body

Content-Type: application/json, multipart/form-data

- `bcc` (array) - The name/email address pairs of the recipients to be BCC'd.
  - `name` (string)
  - `email` (string) **(required)**
- `body` (string) - The body of the draft, in HTML format.
- `cc` (array) - The name/email address pairs of the recipients to be CC'd.
  - `name` (string)
  - `email` (string) **(required)**
- `tracking_options` (object)
  - `opens` (boolean)
  - `thread_replies` (boolean)
  - `links` (boolean)
  - `label` (string)
- `attachments` (array) - 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 `<img>` tag in the email's
HTML. For example, you might see something like
`<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` 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` (array) - 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) **(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` (array) - 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) **(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` (array) - The name/email address pairs of the recipients.
  - `name` (string)
  - `email` (string) **(required)**
- `custom_headers` (array) - An array of custom headers to add to the message.
  - `name` (string)
  - `value` (string)
- `metadata` (object) - 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.

## Responses

### 200 - Draft

- `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` (array) - The name/email address pairs of the recipients to be BCC'd.
    - `name` (string)
    - `email` (string) **(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` (array) - The name/email address pairs of the recipients to be CC'd.
    - `name` (string)
    - `email` (string) **(required)**
  - `attachments` (array) - 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 `<img>` tag in the message's HTML. For
example, you might see something like `<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in
the message body.

Sometimes, the `content_id` value is contained in angle brackets (for example,
`<ce9b9547-9eeb-43b2-ac4e-58768bdf04e4>`).
    - `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` (array) - A list of folder IDs. For Microsoft, only a single folder is supported. For Google, multiple folders may exist.
  - `from` (array) - An array containing a single name/email address pair, to set as the `From` header.
    - `name` (string)
    - `email` (string)
  - `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` (object) - 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` (array) - An array of name/email address pairs that should receive replies to the message.
    - `name` (string)
    - `email` (string) **(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` (array) - The name/email address pairs of the recipients.
    - `name` (string)
    - `email` (string) **(required)**

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 504 - Provider Failure

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "With Love, From Nylas",
    "to": [{
      "email": "leyah@example.com",
      "name": "Leyah Miller"
    }],
    "cc": [{
      "email": "nyla@example.com",
      "name": "Nyla"
    }],
    "bcc": [{
      "email": "nylas-devrel@example.com",
      "name": "Nylas DevRel"
    }],
    "reply_to": [{
      "email": "nylas@example.com",
      "name": "Nylas"
    }],
    "body": "This email was sent using the Nylas Email API. Visit https://nylas.com for details.",
    "tracking_options": {
      "opens": true,
      "links": true,
      "thread_replies": true,
      "label": "Just testing"
    }
  }'
```

### Node.js SDK

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";

const createDraft = async () => {
  try {
    const draft = {
      subject: "Your Subject Here",
      to: [{ name: "Recipient Name", email: "recipient@example.com" }],
      body: "Your email body here.",
    };

    const createdDraft = await nylas.drafts.create({
      identifier,
      requestBody: draft,
    });

    console.log("Draft created:", createdDraft);
  } catch (error) {
    console.error("Error creating draft:", error);
  }
};

createDraft();

```

### Python SDK

```python
from nylas import Client
from nylas import utils

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"

attachment = utils.file_utils.attach_file_request_builder("Nylas_Logo.png")

draft = nylas.drafts.create(
  grant_id,
  request_body={
    "to": [{ "name": "Name", "email": email }],
    "reply_to": [{ "name": "Name", "email": email }],
    "subject": "Your Subject Here",
    "body": "Your email body here.",
    "attachments": [attachment]
  }
)

print(draft)

```

### Ruby SDK

```ruby
require 'nylas'	

# Initialize Nylas client
nylas = Nylas::Client.new(
	api_key: "<NYLAS_API_KEY>"
)

file = Nylas::FileUtils.attach_file_request_builder("Nylas_Logo.png")

request_body = {
    subject: "From Nylas",
    body: 'This email was sent using the ' +
              'Nylas email API. ' + 
              'Visit https://nylas.com for details.',
    to: [{ name: "Dorothy Vaughan", 
            email: "dorothy@example.com"}],
    cc: [{ name: "George Washington Carver", 
            email: "carver@example.com"}],
    bcc: [{ name: "Albert Einstein", 
            email: "al@example.com"}],
    reply_to: [{ name: "Stephanie Kwolek", 
            email: "skwolek@example.com"}],
   tracking_options: {label: "hey just testing", 
        opens: true, 
        links: true,
        thread_replies: true},
   attachments: [file]        
}

draft, _ = nylas.drafts.create(identifier: "<NYLAS_GRANT_ID>", request_body: request_body)
puts "Draft \"#{draft[:subject]}\" was created with ID: #{draft[:id]}"

```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;
import com.nylas.util.FileUtils;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

public class CreateDraft {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    CreateAttachmentRequest attachment = FileUtils.attachFileRequestBuilder("src/main/java/Nylas_Logo.png");
    List<CreateAttachmentRequest> request = new ArrayList<>();
    request.add(attachment);

    CreateDraftRequest requestBody = new CreateDraftRequest.Builder().
        to(Collections.singletonList(new EmailName("swag@example.com", "Nylas"))).
        cc(Collections.singletonList(new EmailName("dorothy@example.com", "Dorothy Vaughan"))).
        bcc(Collections.singletonList(new EmailName("Lamarr@example.com", "Hedy Lamarr"))).
        subject("With Love, from Nylas").
        body("This email was sent using the Nylas email API. Visit https://nylas.com for details.").
        attachments(request).
        build();

    Response<Draft> drafts = nylas.drafts().create("<NYLAS_GRANT_ID>", requestBody);

    System.out.println("Draft " + drafts.getData().getSubject() + 
        " was created with ID " + drafts.getData().getId());
  }
}

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.util.FileUtils

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(
      apiKey = "<NYLAS_API_KEY>"
  )
  
  val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder("src/main/kotlin/Nylas_Logo.png")

  val requestBody = CreateDraftRequest(
      to = listOf(EmailName("swag@example.com", "Nylas")),
      cc = listOf(EmailName("dorothy@example.com", "Dorothy Vaughan")),
      bcc = listOf(EmailName("Lamarr@example.com", "Hedy Lamarr")),
      subject = "With Love, from Nylas",
      body = "This email was sent using the Nylas Email API. Visit https://nylas.com for details.",
      attachments = listOf(attachment)
  )

  val draft = nylas.drafts().create("<NYLAS_GRANT_ID>", requestBody).data
  
  print("Draft " + draft.subject + " was created with ID: " + draft.id)
}

```