Forward Email Folders API

openapi: 3.2.0
info:
  title: Forward Email Folders API
  description: 'Welcome to the comprehensive API documentation for Forward Email. This API allows you to manage email forwarding, domains, aliases, outbound emails, and more programmatically.


    ## Key Features

    * **Domain Management:** Create, retrieve, update, delete, and verify domains.

    * **Alias Management:** Manage email aliases, including creation, updates, and recipient management.

    * **Outbound SMTP:** Send emails via SMTP, manage limits, and track sent emails.

    * **Account & Logs:** Manage your account details and download activity logs.

    * **Security:** Encrypt TXT records and manage domain members/invites.

    * **CardDAV Contacts:** Full CRUD operations for contact management with vCard support.

    * **CalDAV Calendars:** Complete calendar management with timezone and color support.

    * **IMAP/POP3 Messages:** Comprehensive message management with advanced search capabilities.

    * **IMAP/POP3 Folders:** Full folder management including creation, renaming, and deletion.


    ## Authentication

    Most endpoints require authentication using your **API Key**. Provide the API Key as the `username` in the Basic Authentication header, leaving the password empty.


    ```http

    Authorization: Basic QVBJX1RPS0VOOg==

    ```

    (Replace `API_TOKEN` with your actual key before Base64 encoding)


    Endpoints related to **Alias Contacts, Calendars, Messages, and Folders** require a generated alias username and password for Basic Authentication.


    ## Errors

    The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with a `message` field detailing the error.


    | Status Code | Meaning |

    |-------------|---------------------|

    | 200 | OK |

    | 400 | Bad Request |

    | 401 | Unauthorized |

    | 403 | Forbidden |

    | 404 | Not Found |

    | 409 | Conflict |

    | 412 | Precondition Failed |

    | 429 | Too Many Requests |

    | 500 | Internal Server Error|

    | 501 | Not Implemented |

    | 502 | Bad Gateway |

    | 503 | Service Unavailable |

    | 504 | Gateway Time-out |


    *If you encounter a `5xx` error, please contact api@forwardemail.net.*


    ## Localization

    API responses are translated based on the user''s detected locale or the `Accept-Language` header. Over 25 languages are supported.


    ## Pagination

    Endpoints returning lists support pagination via query parameters.


    | Parameter | Type | Optional | Description | Default | Constraints |

    |--------------|---------|----------|-----------------------------------------------------------------------------|---------|--------------------|

    | `page` | Integer | Yes | Page number to retrieve. | 1 | `>= 1` |

    | `limit` | Integer | Yes | Number of results per page. | 25 | `>= 1`, `<= 100` |

    | `pagination` | Boolean | Yes | Opt-in to pagination behavior (required before Nov 1st, 2024 for some endpoints). | false | |


    **Pagination Headers:**

    * `X-Page-Count`: Total page count.

    * `X-Page-Current`: Current page number.

    * `X-Page-Size`: Number of items on the current page.

    * `X-Item-Count`: Total number of items across all pages.

    * `Link`: Navigation links (prev, next, first, last).


    **Example:**

    ```bash

    curl "https://api.forwardemail.net/v1/domains?page=2&limit=20&pagination=true" \

    -u API_TOKEN:

    ```


    ## Recommended Libraries

    * **Ruby:** Faraday

    * **Python:** requests

    * **Java:** OkHttp

    * **PHP:** Guzzle

    * **JavaScript/Node.js:** superagent (Maintained by Forward Email)

    * **Go:** `net/http`

    * **.NET:** RestSharp'
  version: 1.0.0
  contact:
    name: Forward Email Support
    url: https://forwardemail.net
    email: api@forwardemail.net
servers:
- url: https://api.forwardemail.net
  description: Forward Email API Server
tags:
- name: Folders
  description: 'Alias folders management endpoints (IMAP/POP3)


    >[!TIP]

    > Folder endpoints with a folder''s path /v1/folders/:path as their endpoint are interchangeable with a folder''s ID :id. This means you can refer to the folder by either its path or id value.


    >[!NOTE]

    > Unlike other API endpoints, these require Authentication "username" equal to the alias username and "password" equal to the alias generated password as Basic Authorization headers.


    >[!TIP]

    > These endpoints provide full folder management including creation, renaming, and deletion. Folder paths can include parent folders (e.g., ''INBOX/Subfolder''), and parent folders will be created automatically if they don''t exist.'
paths:
  /v1/folders:
    get:
      tags:
      - Folders
      summary: List folders
      description: Retrieve a list of all IMAP folders/mailboxes for the authenticated alias. This endpoint supports pagination and filtering by subscription status.
      operationId: listFolders
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - name: subscribed
        in: query
        description: Filter folders by subscription status
        schema:
          type: boolean
      responses:
        '200':
          description: Folders retrieved successfully
          headers:
            X-Page-Count:
              description: Total number of pages
              schema:
                type: integer
            X-Page-Current:
              description: Current page number
              schema:
                type: integer
            X-Page-Size:
              description: Number of items on current page
              schema:
                type: integer
            X-Item-Count:
              description: Total number of items
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Folders
      summary: Create folder
      description: Create a new IMAP folder/mailbox. The folder path is required and can include parent folders (e.g., 'INBOX/Subfolder'). If the parent folders don't exist, they will be created automatically.
      operationId: createFolder
      security:
      - AliasAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderInput'
      responses:
        '201':
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/folders/{id}:
    get:
      tags:
      - Folders
      summary: Retrieve folder
      description: Retrieve a specific folder by its ID or path. You can use either the folder's ObjectID or its full path (e.g., 'INBOX/Subfolder') as the identifier.
      operationId: retrieveFolder
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description: Folder retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Folders
      summary: Update folder
      description: Update/rename an existing folder. This operation renames the folder to the new path specified in the request body. You can use either the folder's ObjectID or its current path as the identifier. Folders inside it are renamed with it (e.g., 'Work/Clients' becomes 'Jobs/Clients' when 'Work' is renamed to 'Jobs'). INBOX cannot be renamed.
      operationId: updateFolder
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/folderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderUpdateInput'
      responses:
        '200':
          description: Folder updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Folders
      summary: Delete folder
      description: Delete a specific folder. Its messages are moved to Trash (messages in Trash or Junk are deleted permanently), and folders inside it are kept. INBOX cannot be deleted. You can use either the folder's ObjectID or its path as the identifier.
      operationId: deleteFolder
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    folderId:
      name: id
      in: path
      required: true
      description: Folder ID or path
      schema:
        type: string
    page:
      name: page
      in: query
      description: Page of results to return. If not specified, value will be 1. Must be a number greater than or equal to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    limit:
      name: limit
      in: query
      description: Number of results to return per page. Defaults to 25 if not specified. Must be a number greater than or equal to 1, and less than or equal to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    FolderUpdateInput:
      type: object
      required:
      - path
      properties:
        path:
          type: string
          description: New folder path/name
    Folder:
      type: object
      required:
      - id
      - path
      - name
      - parent
      - uid_validity
      - uid_next
      - modify_index
      - subscribed
      - flags
      - retention
      - special_use
      - created_at
      - updated_at
      - object
      properties:
        id:
          type: string
          description: Folder ID
        path:
          type: string
          description: Full folder path
        name:
          type: string
          description: Folder name (last part of path)
        parent:
          type:
          - string
          - 'null'
          description: Parent folder path
        uid_validity:
          type: integer
          description: IMAP UID validity
        uid_next:
          type: integer
          description: Next UID value
        modify_index:
          type: integer
          description: Modification index
        subscribed:
          type: boolean
          description: Whether folder is subscribed
        flags:
          type: array
          items:
            type: string
          description: Folder flags
        retention:
          type:
          - integer
          - 'null'
          description: Message retention period
        special_use:
          type:
          - string
          - 'null'
          description: Special use designation
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        object:
          type: string
          enum:
          - folder
      example:
        id: folder123
        path: INBOX/Subfolder
        name: Subfolder
        parent: INBOX
        uid_validity: 123456
        uid_next: 1
        modify_index: 1
        subscribed: true
        flags: []
        retention: null
        special_use: null
        created_at: '2025-01-01T00:00:00.000Z'
        updated_at: '2025-01-01T00:00:00.000Z'
        object: folder
    FolderInput:
      type: object
      required:
      - path
      properties:
        path:
          type: string
          description: Folder path/name
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: basic
      description: '

        Use your API Key as the **username** for Basic Authentication. Leave the password field empty.


        **Example:**

        If your API Key is `YOUR_API_KEY`, the Base64 encoded value for the `Authorization` header would be `echo -n "YOUR_API_KEY:" | base64`.


        ```http

        Authorization: Basic WU9VUl9BUElfS0VZOg==

        ```

        '
    AliasAuth:
      type: http
      scheme: basic
      description: '

        Use the generated **alias username and password** for Basic Authentication. This applies to endpoints under:

        *   Alias Contacts (CardDAV)

        *   Alias Calendars (CalDAV)

        *   Alias Messages (IMAP/POP3)

        *   Alias Folders (IMAP/POP3)

        *   Alias Sieve Scripts


        **Example:**

        If the alias username is `alias@domain.com` and password is `GENERATED_PASSWORD`, the Base64 encoded value would be `echo -n "alias@domain.com:GENERATED_PASSWORD" | base64`.


        ```http

        Authorization: Basic YWxpYXNAZG9tYWluLmNvbTpHRU5FUkFURURfUEFTU1dPUkQ=

        ```

        '