Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/forward-email:forward-email-account-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Forward Email Account 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: Account
description: Account management endpoints
paths:
/v1/account:
get:
tags:
- Account
summary: Retrieve account
description: 'Retrieve your account information.
**Authentication:** This endpoint supports both API token authentication and alias credentials authentication.
- **User Account (API Token):** When authenticated with your API token, this endpoint returns your user account information including plan details, email, and API token.
- **Alias Account (Alias Credentials):** When authenticated with alias credentials (email and generated password), this endpoint returns alias/mailbox information including storage used/quota and a nested `settings` object (mail special folders, label settings, and alias defaults). This is useful for IMAP/POP3/CalDAV/CardDAV clients to check storage status and preferences.'
operationId: retrieveAccount
security:
- ApiKeyAuth: []
- AliasAuth: []
responses:
'200':
description: Account retrieved successfully
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AliasAccount'
examples:
userAccount:
summary: User Account (API Token Authentication)
description: Response when authenticated with API token
value:
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
aliasAccount:
summary: Alias Account (Alias Credentials Authentication)
description: Response when authenticated with alias email and generated password. Useful for IMAP/POP3/CalDAV/CardDAV storage information.
value:
id: 683fb2e81cc5d449a0d4cd9e
object: alias
name: user
email: user@example.com
domain_id: 683fb2e81cc5d449a0d4cd9f
domain_name: example.com
storage_used: 524288000
storage_quota: 10737418240
has_imap: true
has_pgp: false
public_key: ''
has_smime: false
smime_certificate: ''
has_wkd_disabled: false
locale: en
settings:
mail:
archive_folder: null
sent_folder: null
drafts_folder: null
label_settings: {}
aliases:
defaults: {}
created_at: '2025-06-04T02:43:52.646Z'
updated_at: '2025-06-04T02:43:55.350Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
put:
tags:
- Account
summary: Update account
description: 'Update your account information.
- **User Account (API Token):** Update user profile fields.
- **Alias Account (Alias Credentials):** Update alias-scoped settings using the nested `settings` object. Legacy flat fields are accepted for compatibility. The response matches `GET /v1/account`.'
operationId: updateAccount
security:
- ApiKeyAuth: []
- AliasAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
settings:
type: object
description: Alias settings (alias authentication only)
properties:
mail:
type: object
properties:
archive_folder:
type:
- string
- 'null'
description: Alias mail archive folder
sent_folder:
type:
- string
- 'null'
description: Alias mail sent folder
drafts_folder:
type:
- string
- 'null'
description: Alias mail drafts folder
label_settings:
type: object
description: Alias label map keyed by keyword
additionalProperties:
$ref: '#/components/schemas/SettingsLabelUpdate'
aliases:
type: object
properties:
defaults:
type: object
description: Free-form alias defaults such as display_name or signature
additionalProperties: true
display_name:
type: string
description: Display name
locale:
type: string
description: Locale preference
email:
type: string
format: email
description: 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:
type: string
format: uri
description: Avatar URL (user authentication only)
responses:
'200':
description: Account updated successfully
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AliasAccount'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/account/api-token:
delete:
tags:
- Account
summary: Disable API token
description: '`DELETE /v1/account/api-token` 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.'
operationId: disableApiToken
security:
- ApiKeyAuth: []
responses:
'200':
description: API token disabled successfully
content:
application/json:
schema:
type: object
required:
- api_token_disabled
properties:
api_token_disabled:
type: boolean
description: True after the authenticated API token has been disabled.
example:
api_token_disabled: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
AliasAccount:
type: object
required:
- id
- object
- name
- email
- domain_id
- domain_name
- storage_used
- storage_quota
properties:
id:
type: string
description: Alias ID
object:
type: string
example: alias
description: Object type
name:
type: string
description: Alias name (local part of email)
email:
type: string
format: email
description: Full alias email address
domain_id:
type: string
description: Domain ID
domain_name:
type: string
description: Domain name
storage_used:
type: integer
format: int64
description: Storage used in bytes for this alias/mailbox
storage_quota:
type: integer
format: int64
description: Storage quota in bytes for this alias/mailbox
has_imap:
type: boolean
description: Whether IMAP is enabled for this alias
has_pgp:
type: boolean
description: Whether PGP encryption is enabled
public_key:
type: string
description: PGP public key if available
has_smime:
type: boolean
description: Whether S/MIME encryption is enabled
smime_certificate:
type: string
description: S/MIME X.509 certificate in PEM format
has_wkd_disabled:
type: boolean
description: Whether WKD (Web Key Directory) public key lookup is disabled for this alias
locale:
type: string
description: Locale preference
settings:
type: object
description: Alias settings
properties:
mail:
type: object
properties:
archive_folder:
type:
- string
- 'null'
description: Alias mail archive folder
sent_folder:
type:
- string
- 'null'
description: Alias mail sent folder
drafts_folder:
type:
- string
- 'null'
description: Alias mail drafts folder
label_settings:
type: object
description: Alias label map keyed by keyword
additionalProperties:
$ref: '#/components/schemas/SettingsLabelUpdate'
aliases:
type: object
properties:
defaults:
type: object
description: Free-form alias defaults such as display_name or signature.
additionalProperties: true
created_at:
type: string
format: date-time
description: Creation timestamp
updated_at:
type: string
format: date-time
description: Last update timestamp
example:
id: 683fb2e81cc5d449a0d4cd9e
object: alias
name: user
email: user@example.com
domain_id: 683fb2e81cc5d449a0d4cd9f
domain_name: example.com
storage_used: 524288000
storage_quota: 10737418240
has_imap: true
has_pgp: false
public_key: ''
has_smime: false
smime_certificate: ''
has_wkd_disabled: false
locale: en
settings:
mail:
archive_folder: null
sent_folder: null
drafts_folder: null
label_settings: {}
aliases:
defaults: {}
created_at: '2025-06-04T02:43:52.646Z'
updated_at: '2025-06-04T02:43:55.350Z'
SettingsLabelUpdate:
type: object
description: Fields allowed when updating a label definition.
properties:
name:
type: string
description: Human-readable label name shown in the UI
color:
type: string
pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$
description: Hex color used for UI rendering
hidden:
type: boolean
description: Hide the label in the UI while preserving the keyword
source:
type: string
description: Label origin for filtering and migrations
enum:
- custom
- system
- imported
Error:
type: object
required:
- message
properties:
message:
type: string
description: Error message
Account:
type: object
required:
- id
- email
- plan
- object
properties:
sessions:
type: array
items:
type: string
has_newsletter:
type: boolean
plan:
type: string
example: free
email:
type: string
format: email
max_quota_per_alias:
type: integer
format: int64
full_email:
type: string
format: email
display_name:
type: string
otp_enabled:
type: boolean
last_locale:
type: string
address_country:
type:
- string
- 'null'
id:
type: string
object:
type: string
example: user
locale:
type: string
preferred_locale:
type: string
description: User's preferred language setting that overrides automatic detection
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
address_html:
type: string
api_token:
type: string
format: uuid
example:
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
responses:
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'
TooManyRequests:
description: Too Many Requests
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=
```
'