Forward Email API

https://forwardemail.net/en/email-api
Admin
Forward Email API is a comprehensive RESTful email API for managing email forwarding, domains,...
Tokens:6,345
Snippets:47
Trust Score:10
Update:54 minutes ago
Show doc for...
Tokens:
Raw
### Retrieve Account - Response Example

Source: https://forwardemail.net/en/email-api

Example response for the /v1/account endpoint when authenticated with a user account (API token). Returns user account information including plan details, email, and API token.

```json
{
  "sessions": [],
  "has_newsletter": true,
  "plan": "enhanced_protection",
  "email": "user@example.com",
  "max_quota_per_alias": 10737418240,
  "full_email": "user@example.com",
  "display_name": "John Doe",
  "otp_enabled": false,
  "last_locale": "en",
  "address_country": "US",
  "id": "683fb2e81cc5d449a0d4cd9d",
  "object": "user",
  "locale": "en",
  "created_at": "2025-06-04T02:43:52.646Z",
  "updated_at": "2025-06-04T02:43:55.350Z",
  "address_html": "",
  "api_token": "15ac16ae21784aa2cb4d5508"
}
```

--------------------------------

### GET /v1/logs/download

Source: https://forwardemail.net/en/email-api

Downloads logs for the account. This endpoint is part of the Logs management operations.

```APIDOC
## GET /v1/logs/download

### Description
Downloads logs for the account.

### Method
GET

### Endpoint
/v1/logs/download

```

--------------------------------

### Authorization Header Example

Source: https://forwardemail.net/en/email-api

Use your API Key as the username for Basic Authentication, leaving the password field empty. The Base64 encoded value for the Authorization header is shown.

```http
Authorization: Basic WU9VUl9BUElfS0VZOg==
```

--------------------------------

### Update account success response (200)

Source: https://forwardemail.net/en/email-api

Example JSON response returned when the account is updated successfully. Shows the user object fields including plan, email, and api_token.

```json
{
  "sessions": [],
  "has_newsletter": true,
  "plan": "free",
  "email": "test1@test1.com",
  "max_quota_per_alias": 10737418240,
  "full_email": "test1@test1.com",
  "display_name": "test1@test1.com",
  "otp_enabled": false,
  "last_locale": "en",
  "address_country": "None",
  "id": "683fb2e81cc5d449a0d4cd9d",
  "object": "user",
  "locale": "en",
  "created_at": "2025-06-04T02:43:52.646Z",
  "updated_at": "2025-06-04T02:43:55.350Z",
  "address_html": "",
  "api_token": "15ac16ae21784aa2cb4d5508"
}
```

--------------------------------

### GET /v1/domains/{domain_id}/catch-all-passwords

Source: https://forwardemail.net/en/email-api

Retrieves catch-all passwords for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## GET /v1/domains/{domain_id}/catch-all-passwords

### Description
Retrieves catch-all passwords for a specific domain.

### Method
GET

### Endpoint
/v1/domains/{domain_id}/catch-all-passwords

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain.

```

--------------------------------

### GET /v1/emails

Source: https://forwardemail.net/en/email-api

Retrieves a list of emails for the account. This endpoint is part of the Email management operations.

```APIDOC
## GET /v1/emails

### Description
Retrieves a list of emails for the account.

### Method
GET

### Endpoint
/v1/emails

```

--------------------------------

### GET /v1/domains

Source: https://forwardemail.net/en/email-api

Retrieves a list of domains for the account. This endpoint is part of the Domain management operations.

```APIDOC
## GET /v1/domains

### Description
Retrieves a list of domains for the account.

### Method
GET

### Endpoint
/v1/domains

```

--------------------------------

### GET /v1/account

Source: https://forwardemail.net/en/email-api

Retrieves account information. When authenticated with an API token, returns user account details including plan, email, and API token. When authenticated with alias credentials, returns alias/mailbox information including storage usage and settings.

```APIDOC
## [GET] /v1/account

### Description
Retrieves your account information. Supports both API token authentication and alias credentials authentication.

### Method
GET

### Endpoint
/v1/account

### Authentication
Basic Authentication with API Key as username and empty password.

### Request Example
```curl
curl https://api.forwardemail.net/v1/account \
  --header 'Authorization: Basic username:password'
```

### Response
#### Success Response (200)
Account retrieved successfully

#### Response Example
```json
{
  "sessions": [],
  "has_newsletter": true,
  "plan": "enhanced_protection",
  "email": "user@example.com",
  "max_quota_per_alias": 10737418240,
  "full_email": "user@example.com",
  "display_name": "John Doe",
  "otp_enabled": false,
  "last_locale": "en",
  "address_country": "US",
  "id": "683fb2e81cc5d449a0d4cd9d",
  "object": "user",
  "locale": "en",
  "created_at": "2025-06-04T02:43:52.646Z",
  "updated_at": "2025-06-04T02:43:55.350Z",
  "address_html": "",
  "api_token": "15ac16ae21784aa2cb4d5508"
}
```

#### Error Responses
- 400 Bad Request
- 401 Unauthorized
- 500 Internal Server Error
```

--------------------------------

### GET /v1/domains/{domain_id}/verify-records

Source: https://forwardemail.net/en/email-api

Verifies DNS records for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## GET /v1/domains/{domain_id}/verify-records

### Description
Verifies DNS records for a specific domain.

### Method
GET

### Endpoint
/v1/domains/{domain_id}/verify-records

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain to verify.

```

--------------------------------

### GET /v1/emails/limit

Source: https://forwardemail.net/en/email-api

Retrieves the email limit for the account. This endpoint is part of the Email management operations.

```APIDOC
## GET /v1/emails/limit

### Description
Retrieves the email limit for the account.

### Method
GET

### Endpoint
/v1/emails/limit

```

--------------------------------

### GET /v1/domains/{domain_id}

Source: https://forwardemail.net/en/email-api

Retrieves a specific domain by its ID or name. This endpoint is part of the Domain management operations.

```APIDOC
## GET /v1/domains/{domain_id}

### Description
Retrieves a specific domain by its ID or name.

### Method
GET

### Endpoint
/v1/domains/{domain_id}

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain to retrieve.

```

--------------------------------

### GET /v1/emails/{id}

Source: https://forwardemail.net/en/email-api

Retrieves a specific email by its ID. This endpoint is part of the Email management operations.

```APIDOC
## GET /v1/emails/{id}

### Description
Retrieves a specific email by its ID.

### Method
GET

### Endpoint
/v1/emails/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the email to retrieve.

```

--------------------------------

### GET /v1/domains/{domain_id}/verify-smtp

Source: https://forwardemail.net/en/email-api

Verifies SMTP settings for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## GET /v1/domains/{domain_id}/verify-smtp

### Description
Verifies SMTP settings for a specific domain.

### Method
GET

### Endpoint
/v1/domains/{domain_id}/verify-smtp

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain to verify.

```

--------------------------------

### Disable API token success response (200)

Source: https://forwardemail.net/en/email-api

Example JSON response returned when the API token is disabled successfully.

```json
{
  "api_token_disabled": true
}
```

--------------------------------

### PUT /v1/account

Source: https://forwardemail.net/en/email-api

Updates account information. For user accounts, updates profile fields. For alias accounts, updates alias-scoped settings using the nested settings object. The response matches GET /v1/account.

```APIDOC
## [PUT] /v1/account

### Description
Updates account information. For user accounts, updates profile fields. For alias accounts, updates alias-scoped settings using the nested settings object. The response matches GET /v1/account.

### Method
PUT

### Endpoint
/v1/account

### Parameters
#### Request Body
- **settings** (object) - Required - Alias settings (alias authentication only). Contains nested fields: display_name (string), locale (string), email (string, format: email, user authentication only), avatar_url (string, format: uri, user authentication only).
- **display_name** (string) - Optional - Display name.
- **locale** (string) - Optional - Locale preference.
- **email** (string, format: email) - Optional - Current email address (user authentication only). The login email cannot be changed through the API; sending a different value returns a 400 error. Change it under My Account > Profile instead.
- **avatar_url** (string, format: uri) - Optional - Avatar URL (user authentication only).

### Request Example
```json
{
  "settings": {
    "mail": {
      "archive_folder": null,
      "sent_folder": null,
      "drafts_folder": null
    },
    "label_settings": {
      "ANY_ADDITIONAL_PROPERTY": {
        "name": "",
        "color": "",
        "hidden": true,
        "source": "custom"
      }
    },
    "aliases": {
      "defaults": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "display_name": "",
  "locale": "",
  "email": "",
  "avatar_url": ""
}
```

### Response
#### Success Response (200)
Account updated successfully. Response schema matches GET /v1/account.

#### Response Example
```json
{
  "sessions": [],
  "has_newsletter": true,
  "plan": "free",
  "email": "test1@test1.com",
  "max_quota_per_alias": 10737418240,
  "full_email": "test1@test1.com",
  "display_name": "test1@test1.com",
  "otp_enabled": false,
  "last_locale": "en",
  "address_country": "None",
  "id": "683fb2e81cc5d449a0d4cd9d",
  "object": "user",
  "locale": "en",
  "created_at": "2025-06-04T02:43:52.646Z",
  "updated_at": "2025-06-04T02:43:55.350Z",
  "address_html": "",
  "api_token": "15ac16ae21784aa2cb4d5508"
}
```

#### Error Responses
- **400** Bad Request
- **401** Unauthorized
- **500** Internal Server Error
```

--------------------------------

### Update account with PUT /v1/account (curl)

Source: https://forwardemail.net/en/email-api

Sends a PUT request to update account information. For user authentication, the email field cannot be changed via the API; sending a different value returns a 400 error. The response matches GET /v1/account.

```curl
curl https://api.forwardemail.net/v1/account \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "settings": {
    "mail": {
      "archive_folder": null,
      "sent_folder": null,
      "drafts_folder": null
    },
    "label_settings": {
      "ANY_ADDITIONAL_PROPERTY": {
        "name": "",
        "color": "",
        "hidden": true,
        "source": "custom"
      }
    },
    "aliases": {
      "defaults": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "display_name": "",
  "locale": "",
  "email": "",
  "avatar_url": ""
}'
```

--------------------------------

### Pagination Query Parameters

Source: https://forwardemail.net/en/email-api

Endpoints returning lists support pagination via query parameters. The parameters include page, limit, and pagination, with pagination headers providing metadata about the result set.

```APIDOC
## Pagination

### Description
Endpoints returning lists support pagination via query parameters.

### Parameters
#### Query Parameters
- **page** (Integer) - Optional - Page number to retrieve. Default: 1. Constraints: `>= 1`.
- **limit** (Integer) - Optional - Number of results per page. Default: 25. Constraints: `>= 1`, `<= 100`.
- **pagination** (Boolean) - Optional - Opt-in to pagination behavior (required before Nov 1st, 2024 for some endpoints). Default: 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:
```
```

--------------------------------

### Basic Authentication Header with API Key

Source: https://forwardemail.net/en/email-api

Use this HTTP header to authenticate API requests. Provide your API key as the username in Basic Authentication, leaving the password empty. Replace 'API_TOKEN' with your actual key before Base64 encoding.

```http
Authorization: Basic QVBJX1RPS0VOOg==
```

--------------------------------

### POST /v1/domains/{domain_id}/catch-all-passwords

Source: https://forwardemail.net/en/email-api

Creates a catch-all password for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## POST /v1/domains/{domain_id}/catch-all-passwords

### Description
Creates a catch-all password for a specific domain.

### Method
POST

### Endpoint
/v1/domains/{domain_id}/catch-all-passwords

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain.

```

--------------------------------

### Paginated API request with curl

Source: https://forwardemail.net/en/email-api

Use this curl command to request a paginated list of domains from the Forward Email API. It sets the page to 2, limit to 20, and enables pagination via the `pagination=true` query parameter. The `-u API_TOKEN:` flag supplies the API token for authentication.

```bash
curl "https://api.forwardemail.net/v1/domains?page=2&limit=20&pagination=true" \
  -u API_TOKEN:
```

--------------------------------

### POST /v1/domains

Source: https://forwardemail.net/en/email-api

Creates a new domain. This endpoint is part of the Domain management operations.

```APIDOC
## POST /v1/domains

### Description
Creates a new domain.

### Method
POST

### Endpoint
/v1/domains

```

--------------------------------

### Authentication

Source: https://forwardemail.net/en/email-api

Most endpoints require authentication using your API Key. Provide the API Key as the username in the Basic Authentication header, leaving the password empty.

```APIDOC
## Authentication

### Description
Most endpoints require authentication using your API Key. Provide the API Key as the `username` in the Basic Authentication header, leaving the password empty.

### Method
Basic Authentication

### Endpoint
N/A

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Basic authentication header with API Key as username and empty password.

### Request Example
```http
Authorization: Basic QVBJX1RPS0VOOg==
```

### Response
#### Success Response (200)
- No response body specified.

#### Response Example
No response example provided.
```

--------------------------------

### POST /v1/emails

Source: https://forwardemail.net/en/email-api

Creates a new email. This endpoint is part of the Email management operations.

```APIDOC
## POST /v1/emails

### Description
Creates a new email.

### Method
POST

### Endpoint
/v1/emails

```

--------------------------------

### DELETE /v1/domains/{domain_id}/catch-all-passwords/{token_id}

Source: https://forwardemail.net/en/email-api

Deletes a specific catch-all password for a domain. This endpoint is part of the Domain management operations.

```APIDOC
## DELETE /v1/domains/{domain_id}/catch-all-passwords/{token_id}

### Description
Deletes a specific catch-all password for a domain.

### Method
DELETE

### Endpoint
/v1/domains/{domain_id}/catch-all-passwords/{token_id}

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain.
- **token_id** (string) - Required - The ID of the catch-all password token to delete.

```

--------------------------------

### Retrieve Account - cURL Request

Source: https://forwardemail.net/en/email-api

Retrieve your account information using the /v1/account endpoint. Supports both API token authentication and alias credentials authentication.

```curl
curl https://api.forwardemail.net/v1/account \
  --header 'Authorization: Basic username:password'
```

--------------------------------

### POST /v1/domains/{domain_id}/test-s3-connection

Source: https://forwardemail.net/en/email-api

Tests the S3 connection for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## POST /v1/domains/{domain_id}/test-s3-connection

### Description
Tests the S3 connection for a specific domain.

### Method
POST

### Endpoint
/v1/domains/{domain_id}/test-s3-connection

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain to test.

```

--------------------------------

### DELETE /v1/account/api-token

Source: https://forwardemail.net/en/email-api

Immediately disables the authenticated API token. The response is { "api_token_disabled": true }. The disabled token can no longer authenticate HTTP API or WebSocket requests. To re-enable API access, sign in to My Security and reset the token, which generates a replacement. Alias-password authentication is unchanged.

```APIDOC
## [DELETE] /v1/account/api-token

### Description
Immediately disables the authenticated API token. The response is { "api_token_disabled": true }. The disabled token can no longer authenticate HTTP API or WebSocket requests. To re-enable API access, sign in to My Security and reset the token, which generates a replacement. Alias-password authentication is unchanged.

### Method
DELETE

### Endpoint
/v1/account/api-token

### Parameters
None

### Request Example
```curl
curl https://api.forwardemail.net/v1/account/api-token \
  --request DELETE \
  --header 'Authorization: Basic username:password'
```

### Response
#### Success Response (200)
API token disabled successfully.

#### Response Example
```json
{
  "api_token_disabled": true
}
```

#### Error Responses
- **400** Bad Request
- **401** Unauthorized
- **429** Too Many Requests
- **500** Internal Server Error
```

--------------------------------

### PUT /v1/domains/{domain_id}

Source: https://forwardemail.net/en/email-api

Updates a specific domain by its ID or name. This endpoint is part of the Domain management operations.

```APIDOC
## PUT /v1/domains/{domain_id}

### Description
Updates a specific domain by its ID or name.

### Method
PUT

### Endpoint
/v1/domains/{domain_id}

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain to update.

```

--------------------------------

### PUT /v1/domains/{domain_id}/denylist

Source: https://forwardemail.net/en/email-api

Updates the denylist for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## PUT /v1/domains/{domain_id}/denylist

### Description
Updates the denylist for a specific domain.

### Method
PUT

### Endpoint
/v1/domains/{domain_id}/denylist

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain.

```

--------------------------------

### PUT /v1/domains/{domain_id}/allowlist

Source: https://forwardemail.net/en/email-api

Updates the allowlist for a specific domain. This endpoint is part of the Domain management operations.

```APIDOC
## PUT /v1/domains/{domain_id}/allowlist

### Description
Updates the allowlist for a specific domain.

### Method
PUT

### Endpoint
/v1/domains/{domain_id}/allowlist

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain.

```

--------------------------------

### DELETE /v1/domains/{domain_id}

Source: https://forwardemail.net/en/email-api

Deletes a specific domain by its ID or name. This endpoint is part of the Domain management operations.

```APIDOC
## DELETE /v1/domains/{domain_id}

### Description
Deletes a specific domain by its ID or name.

### Method
DELETE

### Endpoint
/v1/domains/{domain_id}

### Parameters
#### Path Parameters
- **domain_id** (string) - Required - The ID or name of the domain to delete.

```

--------------------------------

### Disable API token with DELETE /v1/account/api-token (curl)

Source: https://forwardemail.net/en/email-api

Sends a DELETE request to immediately disable the authenticated API token. The disabled token can no longer authenticate HTTP API or WebSocket requests. To re-enable, sign in to My Security and reset the token.

```curl
curl https://api.forwardemail.net/v1/account/api-token \
  --request DELETE \
  --header 'Authorization: Basic username:password'
```

--------------------------------

### DELETE /v1/emails/{id}

Source: https://forwardemail.net/en/email-api

Deletes a specific email by its ID. This endpoint is part of the Email management operations.

```APIDOC
## DELETE /v1/emails/{id}

### Description
Deletes a specific email by its ID.

### Method
DELETE

### Endpoint
/v1/emails/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the email to delete.

```
Tokens:
Raw