# Folders
Folders group inbound inboxes within an account. Every inbox belongs to exactly one folder.
## List folders
> Returns all inbound folders in the account.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"folders","description":"Folders group inbound inboxes within an account. Every inbox belongs to\nexactly one folder.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"schemas":{"Folder":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}}}},"paths":{"/api/inbound/folders":{"get":{"operationId":"listInboundFolders","summary":"List folders","description":"Returns all inbound folders in the account.","tags":["folders"],"responses":{"200":{"description":"List of folders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```
## Create a folder
> Create a new inbound folder.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"folders","description":"Folders group inbound inboxes within an account. Every inbox belongs to\nexactly one folder.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"schemas":{"FolderInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100}}},"Folder":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}},"UnprocessableEntity":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"UnprocessableEntity":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/inbound/folders":{"post":{"operationId":"createInboundFolder","summary":"Create a folder","description":"Create a new inbound folder.","tags":["folders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderInput"}}}},"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
## Get a folder
> Returns a single inbound folder.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"folders","description":"Folders group inbound inboxes within an account. Every inbox belongs to\nexactly one folder.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"folder_id":{"name":"folder_id","in":"path","required":true,"description":"Inbound folder ID","schema":{"type":"integer"}}},"schemas":{"Folder":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/inbound/folders/{folder_id}":{"get":{"operationId":"getInboundFolder","summary":"Get a folder","description":"Returns a single inbound folder.","tags":["folders"],"parameters":[{"$ref":"#/components/parameters/folder_id"}],"responses":{"200":{"description":"Folder details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Delete a folder
> Permanently delete an inbound folder along with all of its inboxes.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"folders","description":"Folders group inbound inboxes within an account. Every inbox belongs to\nexactly one folder.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"folder_id":{"name":"folder_id","in":"path","required":true,"description":"Inbound folder ID","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}}}},"paths":{"/api/inbound/folders/{folder_id}":{"delete":{"operationId":"deleteInboundFolder","summary":"Delete a folder","description":"Permanently delete an inbound folder along with all of its inboxes.\n","tags":["folders"],"parameters":[{"$ref":"#/components/parameters/folder_id"}],"responses":{"204":{"description":"Folder deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Update a folder
> Update an inbound folder.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"folders","description":"Folders group inbound inboxes within an account. Every inbox belongs to\nexactly one folder.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"folder_id":{"name":"folder_id","in":"path","required":true,"description":"Inbound folder ID","schema":{"type":"integer"}}},"schemas":{"FolderInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100}}},"Folder":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}},"UnprocessableEntity":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/inbound/folders/{folder_id}":{"patch":{"operationId":"updateInboundFolder","summary":"Update a folder","description":"Update an inbound folder.","tags":["folders"],"parameters":[{"$ref":"#/components/parameters/folder_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderInput"}}}},"responses":{"200":{"description":"Folder updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mailtrap.io/developers/inbound/folders.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.