---
title: "Create a Folder"
method: POST
path: "/v3/grants/{grant_id}/folders"
tags: ["Folders"]
---

# Create a Folder

`POST /v3/grants/{grant_id}/folders`

Creates a folder.

## Query parameters

- `select` string
- `shared_from` string

## Request body

- CreateFolder
  - `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.

## Response `200`

Folder

- object
  - `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` string[] — 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.

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