Forward Email Sieve Scripts API

openapi: 3.2.0
info:
  title: Forward Email Sieve Scripts 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: Sieve Scripts
  description: 'Sieve script management endpoints


    >[!NOTE]

    > Sieve is a powerful email filtering language defined in RFC 5228. Scripts are executed on incoming mail to automatically organize, filter, and respond to messages.


    >[!TIP]

    > Supported extensions include: fileinto, reject, ereject, vacation, vacation-seconds, imap4flags, envelope, body, relational, comparator-i;ascii-numeric, copy, date, index, editheader, enotify, regex, subaddress, ihave, duplicate, special-use, mailbox, environment, and variables. Scripts are validated before saving to ensure they are syntactically correct.


    >[!NOTE]

    > **Two authentication methods are supported:**

    > - **API Token Auth** (`/v1/domains/{domain_id}/aliases/{alias_id}/sieve`): Use your API key as the username with Basic Auth. Requires domain_id and alias_id in the URL path.

    > - **Alias Auth** (`/v1/sieve-scripts`): Use the alias email and generated password as Basic Auth credentials. No domain_id or alias_id needed in the URL.


    >[!TIP]

    > Script ID parameters accept either the MongoDB ObjectId or the script name, allowing flexible script identification.'
paths:
  /v1/domains/{domain_id}/aliases/{alias_id}/sieve:
    get:
      summary: List Sieve Scripts
      description: List all Sieve scripts for an alias. Sieve is a powerful email filtering language defined in RFC 5228.
      tags:
      - Sieve Scripts
      security:
      - ApiKeyAuth: []
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Domain ID or name
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Alias ID or name
      responses:
        '200':
          description: List of Sieve scripts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SieveScript'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: getV1DomainsByDomainIdAliasesByAliasIdSieve
      x-operation-id-source: derived
    post:
      summary: Create Sieve Script
      description: Create a new Sieve script for an alias. The script will be validated before saving.
      tags:
      - Sieve Scripts
      security:
      - ApiKeyAuth: []
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Domain ID or name
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Alias ID or name
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - content
              properties:
                name:
                  type: string
                  description: Script name
                content:
                  type: string
                  description: Sieve script content
                is_active:
                  type: boolean
                  description: Whether the script is active
                  default: false
                priority:
                  type: integer
                  description: Script priority (lower = higher priority)
                  default: 0
      responses:
        '201':
          description: Sieve script created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: postV1DomainsByDomainIdAliasesByAliasIdSieve
      x-operation-id-source: derived
  /v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}:
    get:
      summary: Get Sieve Script
      description: Get a specific Sieve script by ID or name.
      tags:
      - Sieve Scripts
      security:
      - ApiKeyAuth: []
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Domain ID or name
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Alias ID or name
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      responses:
        '200':
          description: Sieve script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: getV1DomainsByDomainIdAliasesByAliasIdSieveByScriptId
      x-operation-id-source: derived
    put:
      summary: Update Sieve Script
      description: Update an existing Sieve script. The script will be validated before saving.
      tags:
      - Sieve Scripts
      security:
      - ApiKeyAuth: []
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Domain ID or name
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Alias ID or name
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: Sieve script content
                description:
                  type: string
                  description: Script description
                activate:
                  type: boolean
                  description: Whether to activate the script after update
                  default: false
      responses:
        '200':
          description: Sieve script updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: putV1DomainsByDomainIdAliasesByAliasIdSieveByScriptId
      x-operation-id-source: derived
    delete:
      summary: Delete Sieve Script
      description: Delete a Sieve script. Cannot delete an active script.
      tags:
      - Sieve Scripts
      security:
      - ApiKeyAuth: []
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Domain ID or name
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Alias ID or name
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      responses:
        '200':
          description: Sieve script deleted
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: deleteV1DomainsByDomainIdAliasesByAliasIdSieveByScriptId
      x-operation-id-source: derived
  /v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}/activate:
    post:
      summary: Activate Sieve Script
      description: Activate a Sieve script. Only one script can be active at a time - activating a script will deactivate any currently active script.
      tags:
      - Sieve Scripts
      security:
      - ApiKeyAuth: []
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
        description: Domain ID or name
      - name: alias_id
        in: path
        required: true
        schema:
          type: string
        description: Alias ID or name
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      responses:
        '200':
          description: Sieve script activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: postV1DomainsByDomainIdAliasesByAliasIdSieveByScriptIdActivate
      x-operation-id-source: derived
  /v1/sieve-scripts:
    get:
      summary: List Sieve Scripts (Alias Auth)
      description: List all Sieve scripts for the authenticated alias. Uses alias authentication instead of API token.
      tags:
      - Sieve Scripts
      security:
      - AliasAuth: []
      responses:
        '200':
          description: List of Sieve scripts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SieveScript'
        '401':
          $ref: '#/components/responses/Error'
      operationId: getV1SieveScripts
      x-operation-id-source: derived
    post:
      summary: Create Sieve Script (Alias Auth)
      description: Create a new Sieve script for the authenticated alias. Uses alias authentication instead of API token.
      tags:
      - Sieve Scripts
      security:
      - AliasAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - content
              properties:
                name:
                  type: string
                  description: Script name
                content:
                  type: string
                  description: Sieve script content
                description:
                  type: string
                  description: Script description
      responses:
        '201':
          description: Sieve script created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
      operationId: postV1SieveScripts
      x-operation-id-source: derived
  /v1/sieve-scripts/{script_id}:
    get:
      summary: Get Sieve Script (Alias Auth)
      description: Get a specific Sieve script by ID or name for the authenticated alias.
      tags:
      - Sieve Scripts
      security:
      - AliasAuth: []
      parameters:
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      responses:
        '200':
          description: Sieve script details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: getV1SieveScriptsByScriptId
      x-operation-id-source: derived
    put:
      summary: Update Sieve Script (Alias Auth)
      description: Update an existing Sieve script for the authenticated alias.
      tags:
      - Sieve Scripts
      security:
      - AliasAuth: []
      parameters:
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: Sieve script content
                description:
                  type: string
                  description: Script description
                activate:
                  type: boolean
                  description: Whether to activate the script after update
                  default: false
      responses:
        '200':
          description: Sieve script updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: putV1SieveScriptsByScriptId
      x-operation-id-source: derived
    delete:
      summary: Delete Sieve Script (Alias Auth)
      description: Delete a Sieve script for the authenticated alias. Cannot delete an active script.
      tags:
      - Sieve Scripts
      security:
      - AliasAuth: []
      parameters:
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      responses:
        '200':
          description: Sieve script deleted
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: deleteV1SieveScriptsByScriptId
      x-operation-id-source: derived
  /v1/sieve-scripts/{script_id}/activate:
    post:
      summary: Activate Sieve Script (Alias Auth)
      description: Activate a Sieve script for the authenticated alias. Only one script can be active at a time.
      tags:
      - Sieve Scripts
      security:
      - AliasAuth: []
      parameters:
      - name: script_id
        in: path
        required: true
        schema:
          type: string
        description: Sieve script ID or name
      responses:
        '200':
          description: Sieve script activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SieveScript'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      operationId: postV1SieveScriptsByScriptIdActivate
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    SieveScript:
      type: object
      required:
      - id
      - name
      - content
      - alias
      properties:
        id:
          type: string
          description: Unique script identifier
        name:
          type: string
          description: Script name
        content:
          type: string
          description: Sieve script content
        alias:
          type: string
          description: Alias ID this script belongs to
        is_active:
          type: boolean
          description: Whether the script is active
          default: false
        priority:
          type: integer
          description: Script priority (lower = higher priority)
          default: 0
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        object:
          type: string
          example: sieve_script
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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=

        ```

        '