Forward Email Calendars API

openapi: 3.2.0
info:
  title: Forward Email Calendars 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: Calendars
  description: 'Alias calendars management endpoints (CalDAV)


    >[!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 complete calendar management with timezone and color support, including creation, retrieval, updating, and deletion of calendars. Calendar names are required, while other properties like color, timezone, and description are optional.'
paths:
  /v1/calendars:
    get:
      tags:
      - Calendars
      summary: List calendars
      description: Retrieve a list of all calendars for the authenticated alias. This endpoint supports pagination and returns calendars in CalDAV format.
      operationId: listCalendars
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Calendars 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/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Calendars
      summary: Create calendar
      description: Create a new calendar. The calendar name is required, while other properties like color, timezone, and description are optional. If a calendar with the same name already exists, a conflict error will be returned.
      operationId: createCalendar
      security:
      - AliasAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarInput'
      responses:
        '201':
          description: Calendar created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '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/calendars/{id}:
    get:
      tags:
      - Calendars
      summary: Retrieve calendar
      description: Retrieve a specific calendar by its ID. The calendar is returned with all its properties including name, description, color, timezone, and order.
      operationId: retrieveCalendar
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/calendarId'
      responses:
        '200':
          description: Calendar retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Calendars
      summary: Update calendar
      description: Update an existing calendar. You can update any of the calendar properties including name, description, color, timezone, and order. If you change the name to one that already exists, a conflict error will be returned.
      operationId: updateCalendar
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/calendarId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarUpdateInput'
      responses:
        '200':
          description: Calendar updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Calendars
      summary: Delete calendar
      description: Delete a specific calendar permanently. This action cannot be undone and will also delete all events within the calendar.
      operationId: deleteCalendar
      security:
      - AliasAuth: []
      parameters:
      - $ref: '#/components/parameters/calendarId'
      responses:
        '200':
          description: Calendar deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Calendar:
      type: object
      required:
      - id
      - name
      - description
      - color
      - timezone
      - order
      - created_at
      - updated_at
      - object
      properties:
        id:
          type: string
          description: Calendar ID (calendarId from CalDAV)
        name:
          type: string
          description: Calendar name
        description:
          type: string
          description: Calendar description
        color:
          type: string
          description: Calendar color (hex format)
        timezone:
          type: string
          description: Calendar timezone
        order:
          type: integer
          description: Calendar display order
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        object:
          type: string
          enum:
          - calendar
      example:
        id: calendar123
        name: Personal Calendar
        description: My personal calendar
        color: '#ff0000'
        timezone: America/New_York
        order: 0
        created_at: '2025-01-01T00:00:00.000Z'
        updated_at: '2025-01-01T00:00:00.000Z'
        object: calendar
    CalendarUpdateInput:
      type: object
      properties:
        name:
          type: string
          description: Calendar name
        description:
          type: string
          description: Calendar description
        color:
          type: string
          description: Calendar color (hex format)
        timezone:
          type: string
          description: Calendar timezone
        order:
          type: integer
          description: Calendar display order
    CalendarInput:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Calendar name
        calendar_id:
          type: string
          description: Custom calendar ID (if not provided, will be auto-generated)
        description:
          type: string
          description: Calendar description
        color:
          type: string
          description: Calendar color (hex format, if not provided, will be auto-generated)
        timezone:
          type: string
          description: Calendar timezone (defaults to user's timezone or UTC)
        order:
          type: integer
          description: Calendar display order (defaults to 0)
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
  responses:
    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'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    calendarId:
      name: id
      in: path
      required: true
      description: Calendar 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
  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=

        ```

        '