# Return all Drafts

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

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

Return all drafts in the user's Drafts folder.

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination) for more information. |
| `page_token` | string | No | An identifier that specifies which page of data to return. You can get this value from the `next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more information. |
| `metadata_pair` | string | No | Pass a metadata key/value pair (for example, `?metadata_pair=key1:value`) to search for metadata associated with objects. See [Metadata](/docs/reference/api/#metadata) for more information. |
| `select` | string | No | Specify fields that you want Nylas to return, as a comma-separated list (for example, `select=id,updated_at`). This allows you to receive only the portion of object data that you're interested in. You can use `select` to optimize response size and reduce latency by limiting queries to only the information that you need. |
| `subject` | string | No | Return items with a matching subject. The filter is case insensitive and will match partial subjects. |
| `any_email` | string | No | Return messages that have been sent or received from this comma-separated list of email addresses (for example, `mail1@example.com,mail2@example.com`). You can specify a maximum of 25 email addresses. |
| `to` | string | No | Return items containing messages sent to this email address. |
| `cc` | string | No | Return items containing messages that were CC'd to this email address. |
| `bcc` | string | No | Return items containing messages that were BCC'd to this email address, likely sent from the parent account. (Most SMTP gateways remove BCC information, so this appears only if the user sent the email message, or received it because they were on the BCC list.) |
| `starred` | boolean | No | Return items with one or more starred messages. For EWS, this is only supported for Microsoft Exchange 2010 or later. |
| `thread_id` | string | No | Return items with a matching `thread_id`. |
| `has_attachment` | boolean | No | Return items with attachments. |
| `query_imap` | boolean | No | (IMAP, Yahoo, and iCloud only) When `true`, Nylas queries the IMAP server directly instead of the Nylas database. You also need to set the `in` query parameter in your request so Nylas knows which folder to query. |

### 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. |

## Responses

### 200 - Drafts

- `request_id` (string) - The request ID.
- `data` (array)
  - `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)**
- `next_cursor` (string,null) - A cursor pointing to the next page of results for the request.

### 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 --compressed --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'
```

### Node.js SDK

```javascript
import Nylas from "nylas";

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

async function fetchDrafts() {
  try {
    const identifier = "<NYLAS_GRANT_ID>";
    const threads = await nylas.drafts.list({
      identifier,
    });

    console.log("Recent Drafts:", threads);
  } catch (error) {
    console.error("Error fetching drafts:", error);
  }
}

fetchDrafts();

```

### Python SDK

```python
from nylas import Client

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

grant_id = "<NYLAS_GRANT_ID>"

drafts = nylas.drafts.list(
  grant_id,
)

print(drafts)
```

### Ruby SDK

```ruby
require 'nylas'

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

drafts, _ = nylas.drafts.list(identifier: "<NYLAS_GRANT_ID>")
drafts.each {|draft|
	puts "[#{Time.at(draft[:date]).strftime("%d/%m/%Y at %H:%M:%S")}] | \
#{draft[:id]} | \
#{draft[:subject]} | \
#{draft[:folders]}"
}

```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.text.SimpleDateFormat;

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

        ListResponse<Draft> drafts = nylas.drafts().list("<NYLAS_GRANT_ID>");

        for (Draft draft : drafts.getData()){
            String date = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
                    format(new java.util.Date((draft.getDate() * 1000L)));
            System.out.printf("[ %s] | %s | %s | %s",
                    date, draft.getId(), draft.getSubject(), draft.getFolders());
        }
    }
}

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.*
import java.text.SimpleDateFormat

fun main(args: Array<String>) {

    val nylas: NylasClient = NylasClient(
        apiKey = "<NYLAS_API_KEY>"
    )

    val simpleDateFormat = SimpleDateFormat("dd MMMM yyyy, HH:mm:ss")

    val drafts = nylas.drafts().list("<NYLAS_GRANT_ID>")

    for(draft in drafts.data){
        println("[${simpleDateFormat.format(draft.date * 1000L)}] | " +
                 "${draft.id} | ${draft.subject} | ${draft.folders}")
    }
}

```