Forward Email Members API

openapi: 3.2.0
info:
  title: Forward Email Members 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: Members
  description: Domain member management endpoints
paths:
  /v1/domains/{domain_id}/members/{member_id}:
    parameters:
    - $ref: '#/components/parameters/domainId'
    - $ref: '#/components/parameters/memberId'
    put:
      summary: Update domain member
      description: 'Update a domain member.


        >[!IMPORTANT]

        >Updating another member to `admin` emails them an invite as an admin instead, and they stay a `user` until they accept it (the domain''s pending invites list it). Updating them back to `user` or removing them withdraws it.'
      tags:
      - Members
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  required: true
                  type: string
                  description: Group to update the user to the domain membership with (can be one of `"admin"` or `"user"`)
      responses:
        '200':
          description: Domain member updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: putV1DomainsByDomainIdMembersByMemberId
      x-operation-id-source: derived
    delete:
      summary: Remove domain member
      description: Remove a domain member.
      tags:
      - Members
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Domain member removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Member removed successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteV1DomainsByDomainIdMembersByMemberId
      x-operation-id-source: derived
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'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    memberId:
      name: member_id
      in: path
      required: true
      description: Member ID
      schema:
        type: string
    domainId:
      name: domain_id
      in: path
      required: true
      description: Domain ID
      schema:
        type: string
  schemas:
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    Member:
      type: object
      properties:
        id:
          type: string
          description: Member ID
        email:
          type: string
          format: email
          description: Member's email address
        role:
          type: string
          description: Member's role
  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=

        ```

        '