Forward Email Push Tokens API
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.
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.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/forward-email:forward-email-push-tokens-api"
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.
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: 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=
```
'