Forward Email Account API

openapi: 3.2.0
info:
  title: Forward Email Account 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: Account
  description: Account management endpoints
paths:
  /v1/account:
    get:
      tags:
      - Account
      summary: Retrieve account
      description: 'Retrieve your account information.


        **Authentication:** This endpoint supports both API token authentication and alias credentials authentication.


        - **User Account (API Token):** When authenticated with your API token, this endpoint returns your user account information including plan details, email, and API token.


        - **Alias Account (Alias Credentials):** When authenticated with alias credentials (email and generated password), this endpoint returns alias/mailbox information including storage used/quota and a nested `settings` object (mail special folders, label settings, and alias defaults). This is useful for IMAP/POP3/CalDAV/CardDAV clients to check storage status and preferences.'
      operationId: retrieveAccount
      security:
      - ApiKeyAuth: []
      - AliasAuth: []
      responses:
        '200':
          description: Account retrieved successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Account'
                - $ref: '#/components/schemas/AliasAccount'
              examples:
                userAccount:
                  summary: User Account (API Token Authentication)
                  description: Response when authenticated with API token
                  value:
                    sessions: []
                    has_newsletter: true
                    plan: enhanced_protection
                    email: user@example.com
                    max_quota_per_alias: 10737418240
                    full_email: user@example.com
                    display_name: John Doe
                    otp_enabled: false
                    last_locale: en
                    address_country: US
                    id: 683fb2e81cc5d449a0d4cd9d
                    object: user
                    locale: en
                    created_at: '2025-06-04T02:43:52.646Z'
                    updated_at: '2025-06-04T02:43:55.350Z'
                    address_html: ''
                    api_token: 15ac16ae21784aa2cb4d5508
                aliasAccount:
                  summary: Alias Account (Alias Credentials Authentication)
                  description: Response when authenticated with alias email and generated password. Useful for IMAP/POP3/CalDAV/CardDAV storage information.
                  value:
                    id: 683fb2e81cc5d449a0d4cd9e
                    object: alias
                    name: user
                    email: user@example.com
                    domain_id: 683fb2e81cc5d449a0d4cd9f
                    domain_name: example.com
                    storage_used: 524288000
                    storage_quota: 10737418240
                    has_imap: true
                    has_pgp: false
                    public_key: ''
                    has_smime: false
                    smime_certificate: ''
                    has_wkd_disabled: false
                    locale: en
                    settings:
                      mail:
                        archive_folder: null
                        sent_folder: null
                        drafts_folder: null
                      label_settings: {}
                      aliases:
                        defaults: {}
                    created_at: '2025-06-04T02:43:52.646Z'
                    updated_at: '2025-06-04T02:43:55.350Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Account
      summary: Update account
      description: 'Update your account information.


        - **User Account (API Token):** Update user profile fields.

        - **Alias Account (Alias Credentials):** Update alias-scoped settings using the nested `settings` object. Legacy flat fields are accepted for compatibility. The response matches `GET /v1/account`.'
      operationId: updateAccount
      security:
      - ApiKeyAuth: []
      - AliasAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                settings:
                  type: object
                  description: Alias settings (alias authentication only)
                  properties:
                    mail:
                      type: object
                      properties:
                        archive_folder:
                          type:
                          - string
                          - 'null'
                          description: Alias mail archive folder
                        sent_folder:
                          type:
                          - string
                          - 'null'
                          description: Alias mail sent folder
                        drafts_folder:
                          type:
                          - string
                          - 'null'
                          description: Alias mail drafts folder
                    label_settings:
                      type: object
                      description: Alias label map keyed by keyword
                      additionalProperties:
                        $ref: '#/components/schemas/SettingsLabelUpdate'
                    aliases:
                      type: object
                      properties:
                        defaults:
                          type: object
                          description: Free-form alias defaults such as display_name or signature
                          additionalProperties: true
                display_name:
                  type: string
                  description: Display name
                locale:
                  type: string
                  description: Locale preference
                email:
                  type: string
                  format: email
                  description: Current email address (user authentication only). The login email cannot be changed through the API; sending a different value returns a 400 error. Change it under My Account > Profile instead.
                avatar_url:
                  type: string
                  format: uri
                  description: Avatar URL (user authentication only)
      responses:
        '200':
          description: Account updated successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Account'
                - $ref: '#/components/schemas/AliasAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/account/api-token:
    delete:
      tags:
      - Account
      summary: Disable API token
      description: '`DELETE /v1/account/api-token` immediately disables the authenticated API token. The response is `{ "api_token_disabled": true }`.


        The disabled token can no longer authenticate HTTP API or WebSocket requests. To re-enable API access, sign in to My Security and reset the token, which generates a replacement. Alias-password authentication is unchanged.'
      operationId: disableApiToken
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: API token disabled successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - api_token_disabled
                properties:
                  api_token_disabled:
                    type: boolean
                    description: True after the authenticated API token has been disabled.
              example:
                api_token_disabled: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    AliasAccount:
      type: object
      required:
      - id
      - object
      - name
      - email
      - domain_id
      - domain_name
      - storage_used
      - storage_quota
      properties:
        id:
          type: string
          description: Alias ID
        object:
          type: string
          example: alias
          description: Object type
        name:
          type: string
          description: Alias name (local part of email)
        email:
          type: string
          format: email
          description: Full alias email address
        domain_id:
          type: string
          description: Domain ID
        domain_name:
          type: string
          description: Domain name
        storage_used:
          type: integer
          format: int64
          description: Storage used in bytes for this alias/mailbox
        storage_quota:
          type: integer
          format: int64
          description: Storage quota in bytes for this alias/mailbox
        has_imap:
          type: boolean
          description: Whether IMAP is enabled for this alias
        has_pgp:
          type: boolean
          description: Whether PGP encryption is enabled
        public_key:
          type: string
          description: PGP public key if available
        has_smime:
          type: boolean
          description: Whether S/MIME encryption is enabled
        smime_certificate:
          type: string
          description: S/MIME X.509 certificate in PEM format
        has_wkd_disabled:
          type: boolean
          description: Whether WKD (Web Key Directory) public key lookup is disabled for this alias
        locale:
          type: string
          description: Locale preference
        settings:
          type: object
          description: Alias settings
          properties:
            mail:
              type: object
              properties:
                archive_folder:
                  type:
                  - string
                  - 'null'
                  description: Alias mail archive folder
                sent_folder:
                  type:
                  - string
                  - 'null'
                  description: Alias mail sent folder
                drafts_folder:
                  type:
                  - string
                  - 'null'
                  description: Alias mail drafts folder
            label_settings:
              type: object
              description: Alias label map keyed by keyword
              additionalProperties:
                $ref: '#/components/schemas/SettingsLabelUpdate'
            aliases:
              type: object
              properties:
                defaults:
                  type: object
                  description: Free-form alias defaults such as display_name or signature.
                  additionalProperties: true
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
      example:
        id: 683fb2e81cc5d449a0d4cd9e
        object: alias
        name: user
        email: user@example.com
        domain_id: 683fb2e81cc5d449a0d4cd9f
        domain_name: example.com
        storage_used: 524288000
        storage_quota: 10737418240
        has_imap: true
        has_pgp: false
        public_key: ''
        has_smime: false
        smime_certificate: ''
        has_wkd_disabled: false
        locale: en
        settings:
          mail:
            archive_folder: null
            sent_folder: null
            drafts_folder: null
          label_settings: {}
          aliases:
            defaults: {}
        created_at: '2025-06-04T02:43:52.646Z'
        updated_at: '2025-06-04T02:43:55.350Z'
    SettingsLabelUpdate:
      type: object
      description: Fields allowed when updating a label definition.
      properties:
        name:
          type: string
          description: Human-readable label name shown in the UI
        color:
          type: string
          pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$
          description: Hex color used for UI rendering
        hidden:
          type: boolean
          description: Hide the label in the UI while preserving the keyword
        source:
          type: string
          description: Label origin for filtering and migrations
          enum:
          - custom
          - system
          - imported
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    Account:
      type: object
      required:
      - id
      - email
      - plan
      - object
      properties:
        sessions:
          type: array
          items:
            type: string
        has_newsletter:
          type: boolean
        plan:
          type: string
          example: free
        email:
          type: string
          format: email
        max_quota_per_alias:
          type: integer
          format: int64
        full_email:
          type: string
          format: email
        display_name:
          type: string
        otp_enabled:
          type: boolean
        last_locale:
          type: string
        address_country:
          type:
          - string
          - 'null'
        id:
          type: string
        object:
          type: string
          example: user
        locale:
          type: string
        preferred_locale:
          type: string
          description: User's preferred language setting that overrides automatic detection
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        address_html:
          type: string
        api_token:
          type: string
          format: uuid
      example:
        sessions: []
        has_newsletter: true
        plan: free
        email: test1@test1.com
        max_quota_per_alias: 10737418240
        full_email: test1@test1.com
        display_name: test1@test1.com
        otp_enabled: false
        last_locale: en
        address_country: None
        id: 683fb2e81cc5d449a0d4cd9d
        object: user
        locale: en
        created_at: '2025-06-04T02:43:52.646Z'
        updated_at: '2025-06-04T02:43:55.350Z'
        address_html: ''
        api_token: 15ac16ae21784aa2cb4d5508
  responses:
    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'
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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=

        ```

        '