Forward Email Calendar Events API

openapi: 3.2.0
info:
  title: Forward Email Calendar Events 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: Calendar Events
  description: 'Alias calendar events 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 comprehensive calendar event management with full iCalendar (RFC 5545) support. Events are stored as iCal data and automatically parsed to extract common properties like summary, description, location, and dates for easy access. Events support soft deletion and can be filtered by calendar, date range, and deletion status.'
paths:
  /v1/calendar-events:
    get:
      tags:
      - Calendar Events
      summary: List calendar events
      description: Retrieve a list of calendar events for the authenticated alias. This endpoint supports pagination and filtering by calendar, date range, and deletion status.
      operationId: listCalendarEvents
      security:
      - AliasAuth: []
      parameters:
      - name: calendar_id
        in: query
        description: Filter events by calendar ID
        required: false
        schema:
          type: string
      - name: start_date
        in: query
        description: Filter events starting from this date (ISO 8601 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: Filter events ending before this date (ISO 8601 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: include_deleted
        in: query
        description: Include soft-deleted events in results
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of calendar events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Calendar Events
      summary: Create calendar event
      description: Create a new calendar event with iCalendar data. The event will be validated and parsed to extract common properties for easy access.
      operationId: createCalendarEvent
      security:
      - AliasAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarEventInput'
      responses:
        '200':
          description: Calendar event created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/calendar-events/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: Calendar event ID
      schema:
        type: string
    get:
      tags:
      - Calendar Events
      summary: Retrieve calendar event
      description: Retrieve a specific calendar event by its ID. The event is returned with all its properties including parsed iCalendar data.
      operationId: retrieveCalendarEvent
      security:
      - AliasAuth: []
      responses:
        '200':
          description: Calendar event retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Calendar Events
      summary: Update calendar event
      description: Update a specific calendar event. You can modify the iCalendar data or move the event to a different calendar.
      operationId: updateCalendarEvent
      security:
      - AliasAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarEventUpdateInput'
      responses:
        '200':
          description: Calendar event updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Calendar Events
      summary: Delete calendar event
      description: Soft delete a specific calendar event. The event will be marked as deleted but not permanently removed from the database.
      operationId: deleteCalendarEvent
      security:
      - AliasAuth: []
      responses:
        '200':
          description: Calendar event deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CalendarEvent:
      type: object
      required:
      - id
      - calendar_id
      - ical
      - created_at
      - updated_at
      - object
      properties:
        id:
          type: string
          description: Calendar event ID (eventId from CalDAV)
        calendar_id:
          type: string
          description: ID of the calendar this event belongs to
        ical:
          type: string
          description: iCalendar (RFC 5545) data for the event
        summary:
          type: string
          description: Event title/summary (extracted from iCal data)
        description:
          type: string
          description: Event description (extracted from iCal data)
        location:
          type: string
          description: Event location (extracted from iCal data)
        start_date:
          type: string
          format: date-time
          description: Event start date/time (extracted from iCal data)
        end_date:
          type: string
          format: date-time
          description: Event end date/time (extracted from iCal data)
        uid:
          type: string
          description: Unique identifier from iCal data
        status:
          type: string
          description: Event status (extracted from iCal data)
        organizer:
          type: string
          description: Event organizer (extracted from iCal data)
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Soft deletion timestamp
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        object:
          type: string
          enum:
          - calendar_event
      example:
        id: event123
        calendar_id: calendar123
        ical: 'BEGIN:VCALENDAR

          VERSION:2.0

          PRODID:-//Example Corp//Example Calendar//EN

          BEGIN:VEVENT

          UID:event123@example.com

          DTSTART:20250101T120000Z

          DTEND:20250101T130000Z

          SUMMARY:Example Event

          DESCRIPTION:This is an example event

          LOCATION:Conference Room A

          STATUS:CONFIRMED

          END:VEVENT

          END:VCALENDAR'
        summary: Example Event
        description: This is an example event
        location: Conference Room A
        start_date: '2025-01-01T12:00:00.000Z'
        end_date: '2025-01-01T13:00:00.000Z'
        uid: event123@example.com
        status: CONFIRMED
        organizer: null
        deleted_at: null
        created_at: '2025-01-01T00:00:00.000Z'
        updated_at: '2025-01-01T00:00:00.000Z'
        object: calendar_event
    CalendarEventUpdateInput:
      type: object
      properties:
        calendar_id:
          type: string
          description: Move event to a different calendar
        ical:
          type: string
          description: Updated iCalendar (RFC 5545) data for the event
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    CalendarEventInput:
      type: object
      required:
      - calendar_id
      - ical
      properties:
        calendar_id:
          type: string
          description: ID of the calendar to add the event to
        event_id:
          type: string
          description: Custom event ID (if not provided, will be auto-generated)
        ical:
          type: string
          description: iCalendar (RFC 5545) data for the event. Must be valid iCal format.
      example:
        calendar_id: calendar123
        ical: 'BEGIN:VCALENDAR

          VERSION:2.0

          PRODID:-//Example Corp//Example Calendar//EN

          BEGIN:VEVENT

          UID:event123@example.com

          DTSTART:20250101T120000Z

          DTEND:20250101T130000Z

          SUMMARY:Example Event

          DESCRIPTION:This is an example event

          LOCATION:Conference Room A

          STATUS:CONFIRMED

          END:VEVENT

          END:VCALENDAR'
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      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:
    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=

        ```

        '