Forward Email Emails API

openapi: 3.2.0
info:
  title: Forward Email Emails 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: Emails
  description: Email management endpoints
paths:
  /v1/emails:
    get:
      summary: List outbound SMTP emails
      description: '**List outbound SMTP emails**


        Note that this endpoint does not return property values for an email''s `message`, `headers`, nor `rejectedErrors`.


        To return those properties and their values, please use the Retrieve email endpoint with an email ID or Message-ID.


        **Authentication:** This endpoint supports both API token authentication and alias credentials authentication. You can authenticate using either your API key (recommended) or your alias email address and generated password.'
      tags:
      - Emails
      security:
      - ApiKeyAuth: []
      parameters:
      - name: q
        in: query
        description: Search for emails by metadata.
        schema:
          type: string
      - name: domain
        in: query
        description: Search for emails by domain name.
        schema:
          type: string
      - name: is_scheduled
        in: query
        description: Filter for scheduled emails (emails with future send date). Set to 'true' to show only emails scheduled to be sent in the future.
        schema:
          type: boolean
      - name: sort
        in: query
        description: Sort by a specific field (prefix with a single hyphen - to sort in the reverse direction of that field). Defaults to created_at if not set.
        schema:
          type: string
      - name: page
        in: query
        description: See Pagination for more insight.
        schema:
          type: string
      - name: limit
        in: query
        description: See Pagination for more insight.
        schema:
          type: string
      responses:
        '200':
          description: List of outbound SMTP emails
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Email'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: getV1Emails
      x-operation-id-source: derived
    post:
      summary: Create outbound SMTP email
      description: 'Our API for creating an email is inspired by and leverages Nodemailer''s message option configuration. Please defer to the Nodemailer message configuration for all body parameters below.


        Note that with the exception of `envelope` and `dkim` (since we set those automatically for you), we support all Nodemailer options. We automatically set `disableFileAccess` and `disableUrlAccess` options to `true` for security purposes.


        You should either pass the single option of `raw` with your raw full email including headers or pass individual body parameter options below.


        This API endpoint will automatically encode emojis for you if they are found in the headers (e.g. a subject line of `Subject: 🤓 Hello` gets converted to `Subject: =?UTF-8?Q?=F0=9F=A4=93?= Hello` automatically). Our goal was to make an extremely developer-friendly and dummy-proof email API.


        **Scheduled Sending:** To schedule an email for future delivery, set the `date` field to a future timestamp (must be at least 1 minute ahead and no more than 30 days from now). The email will be held until the specified time. You can cancel it using the Delete email endpoint.


        **Authentication:** This endpoint supports both API token authentication and alias credentials authentication. You can authenticate using either your API key (recommended) or your alias email address and generated password. See the Authentication section in the API documentation for details.


        A domain''s catch-all password also works here, with any address on the domain as the username. It can only send: the email is sent as the domain admin who generated the password, the From address can be any address on the domain, and the login cannot be used with any other endpoint.'
      tags:
      - Emails
      security:
      - ApiKeyAuth: []
      - AliasAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMTP'
      responses:
        '200':
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Email sent successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postV1Emails
      x-operation-id-source: derived
  /v1/emails/limit:
    get:
      summary: Get outbound SMTP email limit
      description: Returns a JSON object with the `count` of outbound SMTP messages you sent today and today's `limit`. Outbound SMTP is unlimited, and the `limit` is your current reputation-based threshold (see ), which grows over time. Bounce notifications and auto-replies do not count.
      tags:
      - Emails
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Email limit information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailLimit'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: getV1EmailsLimit
      x-operation-id-source: derived
  /v1/emails/{id}:
    parameters:
    - $ref: '#/components/parameters/emailId'
    get:
      summary: Retrieve outbound SMTP email
      description: 'Retrieve a specific outbound SMTP email by ID or Message-ID. You can pass either the email''s unique ID or its Message-ID header value.


        **Authentication:** This endpoint supports both API token authentication and alias credentials authentication.'
      tags:
      - Emails
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Email retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1EmailsById
      x-operation-id-source: derived
    delete:
      summary: Delete outbound SMTP email
      description: 'Email deletion will set the status to `"rejected"` (and subsequently not process it in the queue) if and only if the current status is one of `"pending"`, `"queued"`, or `"deferred"`. This is useful for canceling emails scheduled via a future `date` before they are sent. We may purge emails automatically after 30 days after they were created and/or sent – therefore you should keep a copy of outbound SMTP emails in your client, database, or application.


        **Authentication:** This endpoint supports both API token authentication and alias credentials authentication.'
      tags:
      - Emails
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Email deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Email deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteV1EmailsById
      x-operation-id-source: derived
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'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Email:
      type: object
      required:
      - id
      - object
      - status
      - alias
      - domain
      - user
      properties:
        is_redacted:
          type: boolean
        hard_bounces:
          type: array
          items:
            type: string
        soft_bounces:
          type: array
          items:
            type: string
        is_bounce:
          type: boolean
        is_dsn:
          type: boolean
          description: True for a delivery status notification (such as a bounce) about an email you sent
        alias:
          type: string
        domain:
          type: string
        user:
          type: string
        status:
          type: string
          enum:
          - pending
          - queued
          - sent
          - partially_sent
          - deferred
          - bounced
          - rejected
          description: The current status of the email. Scheduling is determined by the `date` field.
          example: sent
        is_locked:
          type: boolean
        envelope:
          type: object
          properties:
            from:
              type: string
              format: email
            to:
              type: array
              items:
                type: string
                format: email
        messageId:
          type: string
        date:
          type: string
          format: date-time
          description: The email's Date header. If set to a future time (more than 1 minute ahead), the email will be held until that time. Maximum 30 days in the future from creation.
        subject:
          type: string
        accepted:
          type: array
          items:
            type: string
            format: email
        id:
          type: string
        object:
          type: string
          example: email
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        link:
          type: string
          format: uri
        requireTLS:
          type: boolean
          description: Indicates if TLS is required for the entire delivery chain (RFC 8689).
      example:
        is_redacted: true
        hard_bounces: []
        soft_bounces: []
        is_bounce: false
        is_dsn: false
        alias: 67a180fxxxxxxxe46a3f0edf
        domain: 5efae85dxxxxxxxf4bb53c7a
        user: 5efabd3907xxxxxxx12890b8
        status: sent
        is_locked: false
        envelope:
          from: test@test.com
          to:
          - test@test1.com
        messageId: 1a04fee3-5230-4a85-9111-a2c376835885@forwardemail.net
        date: '2025-06-04T03:32:19.000Z'
        subject: testing
        accepted:
        - test@test1.com
        id: 683fbe4d5baef1b583a1xxxx
        object: email
        created_at: '2025-06-04T03:32:29.138Z'
        updated_at: '2025-06-04T03:32:33.847Z'
        link: https://forwardemail.net/my-account/emails/683fbe4d5baef1b583a11e54
    SMTP:
      type: object
      properties:
        from:
          type: string
          format: email
          description: The email address of the sender (must exist as an alias of the domain).
        to:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
              format: email
          description: Comma-separated list or an array of recipients for the 'To' header.
        cc:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
              format: email
          description: Comma-separated list or an array of recipients for the 'Cc' header.
        bcc:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
              format: email
          description: Comma-separated list or an array of recipients for the 'Bcc' header.
        subject:
          type: string
          description: The subject of the email.
        text:
          type: string
          description: The plaintext version of the message.
        html:
          type: string
          description: The HTML version of the message.
        attachments:
          type: array
          items:
            type: object
          description: An array of attachment objects (see Nodemailer's common fields).
        sender:
          type: string
          format: email
          description: The email address for the 'Sender' header.
        replyTo:
          type: string
          format: email
          description: The email address for the 'Reply-To' header.
        inReplyTo:
          type: string
          description: The Message-ID the message is in reply to.
        references:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Space-separated list or an array of Message-IDs.
        attachDataUrls:
          type: boolean
          description: 'If true, converts data: images in the HTML content to embedded attachments.'
        watchHtml:
          type: string
          description: Apple Watch specific HTML version of the message.
        amp:
          type: string
          description: AMP4EMAIL specific HTML version of the message.
        icalEvent:
          type: object
          description: An iCalendar event as an alternative message content.
        alternatives:
          type: array
          items:
            type: object
          description: An array of alternative message content.
        encoding:
          type: string
          description: Encoding for the text and HTML strings (e.g., 'utf-8', 'hex', 'base64').
        raw:
          type: string
          description: Custom generated RFC822 formatted message (instead of using Nodemailer generation).
        textEncoding:
          type: string
          enum:
          - quoted-printable
          - base64
          description: Encoding forced to be used for text values.
        priority:
          type: string
          enum:
          - high
          - normal
          - low
          description: Priority level for the email.
        headers:
          oneOf:
          - type: object
            additionalProperties: true
          - type: array
            items:
              type: object
          description: Object or array of additional header fields.
        messageId:
          type: string
          description: Optional Message-ID for the 'Message-ID' header.
        date:
          oneOf:
          - type: string
            format: date-time
          - type: string
          description: Optional Date header. If set to a future time (more than 1 minute ahead), the email will be held until that time. Cannot be more than 30 days in the future from creation.
          example: '2025-06-04T15:30:00.000Z'
        list:
          type: object
          description: Optional object of List-* headers.
        requireTLS:
          type: boolean
          description: If true, requires TLS for the entire delivery chain (RFC 8689). The message will only be transmitted over TLS-encrypted connections.
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
    EmailLimit:
      type: object
      properties:
        count:
          type: integer
          description: Outbound SMTP messages you sent today (UTC), not counting bounce notifications and auto-replies
        limit:
          type: integer
          description: Today's reputation-based threshold (at most what is left of the domain's and the account's thresholds today; 0 when you cannot send from the domain)
  parameters:
    emailId:
      name: id
      in: path
      required: true
      description: Email ID or Message-ID. You can pass either the unique email ID (e.g., '683fbe4d5baef1b583a11e54') or the email's Message-ID header value (e.g., '1a04fee3-5230-4a85-9111-a2c376835885@forwardemail.net').
      schema:
        type: string
  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=

        ```

        '