Forward Email Contacts API

openapi: 3.2.0
info:
  title: Forward Email Contacts 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: Contacts
  description: 'Alias contacts management endpoints (CardDAV)


    >[!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 CRUD operations for contact management with vCard support, including creation, retrieval, updating, and deletion of contacts. You can provide either vCard content directly or individual contact fields that will be converted to vCard format.'
paths:
  /v1/contacts:
    get:
      tags:
      - Contacts
      summary: List contacts
      description: Retrieve a list of all contacts for the authenticated alias. This endpoint supports pagination and returns contacts in CardDAV format.
      operationId: listContacts
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Contacts 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/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Contacts
      summary: Create contact
      description: Create a new contact. You can provide either vCard content directly or individual contact fields that will be converted to vCard format. If a contact with the same ID already exists, a conflict error will be returned.
      operationId: createContact
      security:
      - AliasAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInput'
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/contacts/{id}:
    get:
      tags:
      - Contacts
      summary: Retrieve contact
      description: Retrieve a specific contact by its ID. The contact is returned in the standard Contact format with vCard content and parsed fields.
      operationId: retrieveContact
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/contactId'
      responses:
        '200':
          description: Contact retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Contacts
      summary: Update contact
      description: Update an existing contact. You can provide either updated vCard content or individual fields to update. The contact's vCard will be regenerated if individual fields are provided.
      operationId: updateContact
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/contactId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactUpdateInput'
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Contacts
      summary: Delete contact
      description: Delete a specific contact permanently. This action cannot be undone.
      operationId: deleteContact
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/contactId'
      responses:
        '200':
          description: Contact deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      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:
    contactId:
      name: id
      in: path
      required: true
      description: Contact ID
      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:
    ContactInput:
      type: object
      properties:
        content:
          type: string
          description: vCard content (if not provided, will be generated from other fields)
        full_name:
          type: string
          description: Contact's full name
        contact_id:
          type: string
          description: Custom contact ID (if not provided, will be auto-generated)
        uid:
          type: string
          description: Contact UID (if not provided, will be auto-generated)
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
              type:
                type: string
                default: INTERNET
            required:
            - value
          description: Array of email addresses
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
                default: CELL
            required:
            - value
          description: Array of phone numbers
        phones:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
                default: CELL
            required:
            - value
          description: Array of phone numbers (alias for phone_numbers)
        addresses:
          type: array
          items:
            type: object
            properties:
              street:
                type: string
              city:
                type: string
              state:
                type: string
              postalCode:
                type: string
              country:
                type: string
              type:
                type: string
          description: Array of addresses
        is_group:
          type: boolean
          description: Whether contact is a group
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    Contact:
      type: object
      required:
      - id
      - uid
      - full_name
      - content
      - etag
      - is_group
      - emails
      - phone_numbers
      - created_at
      - updated_at
      - object
      properties:
        id:
          type: string
          description: Contact ID (contact_id from CardDAV)
        uid:
          type: string
          description: Contact UID
        full_name:
          type: string
          description: Contact's full name
        content:
          type: string
          description: vCard content
        etag:
          type: string
          description: ETag for versioning
        is_group:
          type: boolean
          description: Whether contact is a group
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
              type:
                type: string
                default: INTERNET
            required:
            - value
          description: Array of email addresses
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
                default: CELL
            required:
            - value
          description: Array of phone numbers
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        object:
          type: string
          enum:
          - contact
      example:
        id: contact123
        uid: uid123
        full_name: John Doe
        content: BEGIN:VCARD\nVERSION:3.0\nUID:uid123\nFN:John Doe\nEMAIL;TYPE=INTERNET:john@example.com\nEND:VCARD
        etag: etag123
        is_group: false
        emails:
        - value: john@example.com
          type: INTERNET
        phone_numbers:
        - value: '+1234567890'
          type: CELL
        created_at: '2025-01-01T00:00:00.000Z'
        updated_at: '2025-01-01T00:00:00.000Z'
        object: contact
    ContactUpdateInput:
      type: object
      properties:
        content:
          type: string
          description: vCard content
        full_name:
          type: string
          description: Contact's full name
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
              type:
                type: string
                default: INTERNET
            required:
            - value
          description: Array of email addresses
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
                default: CELL
            required:
            - value
          description: Array of phone numbers
        phones:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
                default: CELL
            required:
            - value
          description: Array of phone numbers (alias for phone_numbers)
        addresses:
          type: array
          items:
            type: object
            properties:
              street:
                type: string
              city:
                type: string
              state:
                type: string
              postalCode:
                type: string
              country:
                type: string
              type:
                type: string
          description: Array of addresses
        is_group:
          type: boolean
          description: Whether contact is a group
  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=

        ```

        '