Forward Email Aliases API

openapi: 3.2.0
info:
  title: Forward Email Aliases 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: Aliases
  description: Domain alias management endpoints
paths:
  /v1/domains/{domain_id}/aliases/{alias_id}/generate-password:
    post:
      summary: Generate an alias password
      description: Generate a password for an alias. If `emailed_instructions` is not provided, the response will contain the generated username and password.
      tags:
      - Aliases
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Fully qualified domain name (FQDN)
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier of the alias
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAliasPasswordInput'
      responses:
        '200':
          description: Alias credentials returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    example: alias@yourdomain.com
                  password:
                    type: string
                    example: some-generated-password
                required:
                - username
                - password
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postV1DomainsByDomainIdAliasesByAliasIdGeneratePassword
      x-operation-id-source: derived
  /v1/domains/{domain_id}/aliases:
    parameters:
    - $ref: '#/components/parameters/domainId'
    get:
      summary: List domain aliases
      description: '>[!NOTE]

        >As of November 1st, 2024 the API endpoints for `List domains` and `List domain aliases` will default to `1000` max results per page. If you would like to opt-in to this behavior early, you can pass `?paginate=true` as an additional querystring parameter to the URL for the endpoint query. See Pagination for more insight.'
      tags:
      - Aliases
      security:
      - ApiKeyAuth: []
      parameters:
      - name: q
        in: query
        description: Search for aliases in a domain by name, label, or recipient (RegExp supported)
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: Search for aliases in a domain by name (RegExp supported)
        required: false
        schema:
          type: string
      - name: recipient
        in: query
        description: Search for aliases in a domain by recipient (RegExp supported)
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: Sort by a specific field (prefix with a single hyphen - to sort in reverse). Defaults to created_at.
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of domain aliases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alias'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1DomainsByDomainIdAliases
      x-operation-id-source: derived
    post:
      summary: Create new domain alias
      description: 'Create a new alias for a specific domain. Note: this endpoint does not accept `password` or `new_password` fields. To set or change alias credentials, use the "POST /v1/domains/:domain_id/aliases/:alias_id/generate-password" endpoint.'
      tags:
      - Aliases
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AliasInput'
      responses:
        '200':
          description: Domain alias created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alias'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: postV1DomainsByDomainIdAliases
      x-operation-id-source: derived
  /v1/domains/{domain_id}/aliases/{alias_id}:
    parameters:
    - $ref: '#/components/parameters/domainId'
    - $ref: '#/components/parameters/aliasId'
    get:
      summary: Retrieve domain alias
      description: Retrieve a specific alias for a domain.
      tags:
      - Aliases
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Domain alias retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alias'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1DomainsByDomainIdAliasesByAliasId
      x-operation-id-source: derived
    put:
      summary: Update domain alias
      description: 'Update a specific alias for a domain. Note: this endpoint does not accept `password` or `new_password` fields. To set or change alias credentials, use the "POST /v1/domains/:domain_id/aliases/:alias_id/generate-password" endpoint.'
      tags:
      - Aliases
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AliasUpdateInput'
      responses:
        '200':
          description: Domain alias updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alias'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: putV1DomainsByDomainIdAliasesByAliasId
      x-operation-id-source: derived
    delete:
      summary: Delete domain alias
      description: Delete a specific alias for a domain.
      tags:
      - Aliases
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Domain alias deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Alias deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteV1DomainsByDomainIdAliasesByAliasId
      x-operation-id-source: derived
components:
  schemas:
    GenerateAliasPasswordInput:
      type: object
      properties:
        new_password:
          type: string
          description: Your custom new password to use for the alias. Custom mailbox passwords must be 128 characters or fewer, cannot start or end with whitespace, and cannot contain quotes or apostrophes.
        password:
          type: string
          description: Existing password for alias to change it without deleting mailbox storage
        is_override:
          type: boolean
          description: Override existing password and delete IMAP storage (use with caution)
        emailed_instructions:
          type: string
          format: email
          description: Email address to send alias password and setup instructions
    AliasInput:
      type: object
      properties:
        name:
          type: string
          description: Alias name (if not provided or if blank, then a random alias is generated)
        recipients:
          oneOf:
          - type: string
            description: Line-break/space/comma separated string of valid email addresses, FQDNs, IPs, or webhook URLs
          - type: array
            items:
              type: string
              format: email
            description: Array of valid recipients
          description: List of recipients. If not provided or empty, defaults to the requester's email
        description:
          type: string
          description: Alias description
        labels:
          oneOf:
          - type: string
            description: Line-break/space/comma separated string of labels
          - type: array
            items:
              type: string
            description: Array of labels
        has_recipient_verification:
          type: boolean
          description: Require recipients to click verification link (defaults to domain setting)
        is_enabled:
          type: boolean
          description: Whether to enable or disable this alias
        error_code_if_disabled:
          type: number
          enum:
          - 250
          - 421
          - 550
          description: Error code if alias is disabled. Defaults to 250
        has_imap:
          type: boolean
          description: Enable or disable IMAP storage for this alias
        has_pgp:
          type: boolean
          description: Enable or disable OpenPGP encryption for this alias
        public_key:
          type: string
          description: OpenPGP public key in ASCII Armor format
        has_smime:
          type: boolean
          description: Enable or disable S/MIME encryption for this alias
        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
        max_quota:
          type: string
          description: Storage max quota (e.g. '1 GB')
        vacation_responder_is_enabled:
          type: boolean
          description: Enable or disable vacation responder
        vacation_responder_start_date:
          type: string
          description: Start date (e.g. 'YYYY-MM-DD') for vacation responder
        vacation_responder_end_date:
          type: string
          description: End date (e.g. 'YYYY-MM-DD') for vacation responder
        vacation_responder_subject:
          type: string
          description: Plaintext subject for vacation responder
        vacation_responder_message:
          type: string
          description: Plaintext message for vacation responder
        retention:
          type: integer
          minimum: 0
          maximum: 365
          description: Retention period in days (0-365) for Trash and Junk mailbox cleanup. Set to 0 to use automatic storage-based scaling.
        smtp_limit:
          type: integer
          minimum: 0
          default: 0
          description: Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit.
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    Alias:
      type: object
      properties:
        user:
          type: object
          properties:
            email:
              type: string
              format: email
            display_name:
              type: string
            id:
              type: string
          required:
          - email
          - display_name
          - id
        domain:
          type: object
          properties:
            name:
              type: string
            id:
              type: string
          required:
          - name
          - id
        name:
          type: string
        labels:
          type: array
          items:
            type: string
        is_enabled:
          type: boolean
        has_recipient_verification:
          type: boolean
        verified_recipients:
          type: array
          items:
            type: string
            format: email
        pending_recipients:
          type: array
          items:
            type: string
            format: email
        recipients:
          type: array
          items:
            type: string
            format: email
        id:
          type: string
        object:
          type: string
          enum:
          - alias
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        storage_location:
          type: string
        has_imap:
          type: boolean
        retention:
          type: integer
          minimum: 0
          maximum: 365
          description: Retention period in days (0-365) for Trash and Junk mailbox cleanup. 0 means automatic storage-based scaling.
        smtp_limit:
          type: integer
          minimum: 0
          default: 0
          description: Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit.
        is_smtp_suspended:
          type: boolean
          default: false
          description: Whether this alias is currently suspended from outbound SMTP access.
          readOnly: true
        smtp_suspended_sent_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time when the alias was suspended from outbound SMTP.
          readOnly: true
      required:
      - user
      - domain
      - name
      - labels
      - is_enabled
      - has_recipient_verification
      - verified_recipients
      - pending_recipients
      - recipients
      - id
      - object
      - created_at
      - updated_at
      - storage_location
      - has_imap
      - retention
      example:
        user:
          email: test@test.com
          display_name: test@test.com
          id: 5efabd39xxxxxxx4512890b8
        domain:
          name: mailsire.com
          id: 5e3c0550xxxxxxx09b7ba023
        name: abc123
        labels: []
        is_enabled: true
        has_recipient_verification: false
        verified_recipients: []
        pending_recipients: []
        recipients:
        - abc@test1.com
        id: 62fa3dcxxxxxxx79dda83ff2
        object: alias
        created_at: '2022-08-15T12:36:26.593Z'
        updated_at: '2022-08-15T12:36:26.593Z'
        storage_location: storage_loc
        has_imap: false
        retention: 0
    AliasUpdateInput:
      type: object
      properties:
        name:
          type: string
          description: Alias name
        recipients:
          oneOf:
          - type: string
            description: Line-break/space/comma separated string of valid email addresses, FQDNs, IPs, or webhook URLs
          - type: array
            items:
              type: string
              format: email
            description: Array of valid recipients. Pass an empty array to remove all forwarding recipients (e.g. for IMAP-only aliases).
          description: If omitted, existing recipients are preserved. Pass an empty array to clear all forwarding recipients.
        description:
          type: string
          description: Alias description
        labels:
          oneOf:
          - type: string
            description: Line-break/space/comma separated string of labels
          - type: array
            items:
              type: string
            description: Array of labels
        has_recipient_verification:
          type: boolean
          description: Require recipients to click verification link (defaults to domain setting)
        is_enabled:
          type: boolean
          description: Enable or disable alias
        error_code_if_disabled:
          type: number
          enum:
          - 250
          - 421
          - 550
          description: Error code to use if alias is disabled (defaults to 250)
        has_imap:
          type: boolean
          description: Enable or disable IMAP storage
        has_pgp:
          type: boolean
          description: Enable or disable OpenPGP encryption
        public_key:
          type: string
          description: OpenPGP public key in ASCII Armor format
        has_smime:
          type: boolean
          description: Enable or disable S/MIME encryption
        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
        max_quota:
          type: string
          description: Storage maximum quota (e.g., '1 GB')
        vacation_responder_is_enabled:
          type: boolean
          description: Enable or disable vacation responder
        vacation_responder_start_date:
          type: string
          description: Vacation responder start date (e.g. YYYY-MM-DD)
        vacation_responder_end_date:
          type: string
          description: Vacation responder end date (e.g. YYYY-MM-DD)
        vacation_responder_subject:
          type: string
          description: Plaintext subject of vacation responder
        vacation_responder_message:
          type: string
          description: Plaintext message of vacation responder
        retention:
          type: integer
          minimum: 0
          maximum: 365
          description: Retention period in days (0-365) for Trash and Junk mailbox cleanup. Set to 0 to use automatic storage-based scaling.
        smtp_limit:
          type: integer
          minimum: 0
          default: 0
          description: Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit.
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: Error response
      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'
  parameters:
    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
    aliasId:
      name: alias_id
      in: path
      required: true
      description: Alias ID
      schema:
        type: string
    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
    domainId:
      name: domain_id
      in: path
      required: true
      description: Domain ID
      schema:
        type: string
  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=

        ```

        '