# Create a Folder

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

Source: https://developer.nylas.com/docs/reference/api/folders/post-folder/

Creates a folder.

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `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. |
| `shared_from` | string | No | (Microsoft only) When provided, Nylas returns items that were shared from the specified email address. It also accepts grant ID. This parameter only accepts single email address or grant ID. Check out the [Shared folders](/docs/provider-guides/microsoft/shared-folders) guide for more information. |

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

- `name` (string) **(required)** - Creates a folder with the specified display name.
- `parent_id` (string) - (Microsoft and EWS only) The ID of the parent folder.
- `text_color` (string) - (Google only) The text color of the folder, in hexadecimal format (for example, `#0099EE`). See the [list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color) for more information.
- `background_color` (string) - (Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`). See the [list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color) for more information.

## Responses

### 200 - Folder

- `request_id` (string) - The request ID.
- `data` (object) - An email folder or label.
  - `background_color` (string) - (Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`).
See the
[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for more information.
  - `child_count` (integer) - (Microsoft and EWS only) The number of immediate child folders nested under the specified folder.
  - `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.
  - `name` (string) - The name of the folder.
  - `object` (string) - The type of object.
  - `parent_id` (string) - (Microsoft and EWS only) The ID of the parent folder.
  - `single_level` (boolean) - (Microsoft only) If `true`, retrieves folders from a single-level hierarchy only. If `false`, retrieves folders across a multi-level hierarchy.
  - `system_folder` (boolean) - (Google only) If `true`, the folder is a standard folder created by Google. If `false`, the folder
was created by the user.
  - `text_color` (string) - (Google only) The text color of the folder, in hexadecimal format (for example, `#0099EE`). See
the
[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for more information.
  - `total_count` (integer) - The number of items inside the folder.
  - `unread_count` (integer) - The number of unread items inside the folder.
  - `attributes` (array) - An array of attribute descriptors shared by system folders across providers. For example, folders
that contain sent messages ("Sent Items" on Microsoft, or "SENT" on other providers) have the
`["\\Sent"]` attribute. For more information, see
[Common folder attributes](/docs/v3/email/folders/#common-folder-attributes). If a folder does not have one of the standard system folders, Nylas returns the `attributes` array empty.

You can't query for folders using attributes, but you _can_ manually filter through folders to
find any that match the attributes you're looking for.

### 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 POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "text_color": "#000000",
    "name": "new folder",
    "background_color": "#73AFFF"
  }'
```

### 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 createFolder = async () => {
  try {
    const folder = await nylas.folders.create({
      identifier,
      requestBody: {
        name: "New Folder",
      },
    });

    console.log("Folder created:", folder);
  } catch (error) {
    console.error("Error creating folder:", error);
  }
};

createFolder();

```

### Python SDK

```python
from nylas import Client

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

grant_id = "<NYLAS_GRANT_ID>"

folder = nylas.folders.create(
  grant_id,
  request_body={
    "name": 'New Folder',
  }
)

print(folder)
```

### Ruby SDK

```ruby
require 'nylas'

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

request_body = {
  name: "My Custom label"
}

folder = nylas.folders.create(identifier: "<NYLAS_GRANT_ID>", 
    request_body: request_body)
```

### Java SDK

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

public class CreateFolder {

    public static void main(String[] args) throws 
    NylasSdkTimeoutError, NylasApiError {

        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        CreateFolderRequest request = 
        new CreateFolderRequest("My Custom folder", "", "", "");

        Response<Folder> label =  
        nylas.folders().create("<NYLAS_GRANT_ID>", request);
    }
}

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.CreateFolderRequest

fun main(args: Array<String>) {

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

   val request = CreateFolderRequest("My Custom folder")
   val folder = nylas.folders().create("<NYLAS_GRANT_ID>",  request).data
   println(folder.name)
}

```