---
title: "Register push token"
method: POST
path: "/v1/push-tokens"
tags: ["Push Tokens"]
---

# Register push token

`POST /v1/push-tokens`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/push-tokens`
- Auth: one of:
  - HTTP basic
  - HTTP basic

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.

## Request body

- PushTokenInput
  - `platform` 'apns' | 'fcm' | 'unified-push' | 'web-push', required: Push notification platform
  - `token` string, required: 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` string: Optional human-readable device name for management
  - `alias_id` string: Required when using API token authentication. The alias ID to register the token for.

## Response `201`

Push token registered successfully

- PushToken
  - `id` string: Unique push token document ID
  - `alias` string: Alias ID this token belongs to
  - `platform` 'apns' | 'fcm' | 'unified-push' | 'web-push': Push notification platform
  - `token` string: Device token, registration token, or push endpoint URL
  - `device_name` string: Optional human-readable device name
  - `last_used_at` string, date-time, nullable: Last successful push delivery timestamp
  - `failure_count` integer: Consecutive delivery failure count (auto-pruned at 3)
  - `expires_at` string, date-time: Token expiry (auto-extended on successful delivery)
  - `created_at` string, date-time: Registration timestamp
  - `updated_at` string, date-time: Last update timestamp
  - `object` 'push_token': Object type identifier

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

---

[API](https://skmtc.dev/forwardemail/apis/forward-email-api.md) · [All operations](https://skmtc.dev/forwardemail/apis/forward-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forwardemail/apis/forward-email-api/revisions/ecefab4527f6?raw)