Forward Email Push Tokens API

openapi: 3.2.0
info:
  title: Forward Email Push Tokens 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: Push Tokens
  description: Register and manage push notification tokens for APNs, FCM, UnifiedPush, and Web Push. Tokens are scoped to an alias and used to deliver notifications when the app is backgrounded or closed.
paths:
  /v1/push-tokens:
    get:
      tags:
      - Push Tokens
      summary: List push tokens
      description: Retrieve all active (non-expired) push tokens for the authenticated alias. Supports optional platform filtering via query parameter.
      operationId: listPushTokens
      security:
      - AliasAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: platform
        in: query
        required: false
        schema:
          type: string
          enum:
          - apns
          - fcm
          - unified-push
          - web-push
        description: Filter tokens by platform
      - name: alias_id
        in: query
        required: false
        schema:
          type: string
        description: Required when using API token authentication
      responses:
        '200':
          description: Push tokens retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PushToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Push Tokens
      summary: Register push token
      description: Register a new push token or refresh an existing one (upsert). If a token with the same (alias, platform, token) combination already exists, its expiry is extended and failure count is reset. Tokens are automatically pruned after 90 days of inactivity or 3 consecutive delivery failures.
      operationId: createPushToken
      security:
      - AliasAuth: []
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushTokenInput'
      responses:
        '201':
          description: Push token registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Push Tokens
      summary: Remove all push tokens
      description: Remove all push tokens for the authenticated alias. Useful for logout or account deletion flows.
      operationId: removeAllPushTokens
      security:
      - AliasAuth: []
      - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                alias_id:
                  type: string
                  description: Required when using API token authentication
      responses:
        '200':
          description: All push tokens removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushTokenDeletion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/push-tokens/{id}:
    delete:
      tags:
      - Push Tokens
      summary: Remove push token
      description: Remove a specific push token by ID. Only the owning user/alias can delete their own tokens.
      operationId: removePushToken
      security:
      - AliasAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Push token document ID
      responses:
        '204':
          description: Push token removed successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
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'
    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'
  schemas:
    PushTokenInput:
      type: object
      required:
      - platform
      - token
      properties:
        platform:
          type: string
          enum:
          - apns
          - fcm
          - unified-push
          - web-push
          description: Push notification platform
        token:
          type: string
          maxLength: 4096
          description: Device token (APNs hex), registration token (FCM), or a JSON push subscription with `endpoint` and `keys` (UnifiedPush and Web Push). Web Push endpoints must belong to a browser push service (Firebase Cloud Messaging, Mozilla, Apple or Windows); UnifiedPush endpoints must use HTTPS on port 443 or on port 1024 and above.
        device_name:
          type: string
          maxLength: 255
          description: Optional human-readable device name for management
        alias_id:
          type: string
          description: Required when using API token authentication. The alias ID to register the token for.
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    PushTokenDeletion:
      type: object
      properties:
        deleted_count:
          type: integer
          description: Number of tokens deleted
        object:
          type: string
          enum:
          - push_token_deletion
    PushToken:
      type: object
      properties:
        id:
          type: string
          description: Unique push token document ID
        alias:
          type: string
          description: Alias ID this token belongs to
        platform:
          type: string
          enum:
          - apns
          - fcm
          - unified-push
          - web-push
          description: Push notification platform
        token:
          type: string
          description: Device token, registration token, or push endpoint URL
        device_name:
          type: string
          description: Optional human-readable device name
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Last successful push delivery timestamp
        failure_count:
          type: integer
          description: Consecutive delivery failure count (auto-pruned at 3)
        expires_at:
          type: string
          format: date-time
          description: Token expiry (auto-extended on successful delivery)
        created_at:
          type: string
          format: date-time
          description: Registration timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        object:
          type: string
          enum:
          - push_token
          description: Object type identifier
  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=

        ```

        '