Register a device for push

POST/api/v1/mailbox/devices

Requires amailbox token— it acts as one mailbox holder, not as the organization.

From a phone app, after sign-in: the push token from APNs or FCM. New mail then raises a notification on this device. Registering the same token again just updates it.

Errors

Status	When
`401`	No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
`403`	The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.

Request body

tokenstringrequired
The device's push token from APNs or FCM.
platformstringrequired
ios or android.
app_versionstring or null
Your app's version, for support.

Request

POST/api/v1/mailbox/devices

curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/devices' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "fcm-or-apns-device-token",
    "platform": "ios",
    "app_version": "2.1.0"
  }'

const response = await fetch('https://courier.mailyte.com/api/v1/mailbox/devices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MAILBOX_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "token": "fcm-or-apns-device-token",
    "platform": "ios",
    "app_version": "2.1.0"
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://courier.mailyte.com/api/v1/mailbox/devices",
    headers={"Authorization": "Bearer MAILBOX_TOKEN"},
    json={
      "token": "fcm-or-apns-device-token",
      "platform": "ios",
      "app_version": "2.1.0"
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('MAILBOX_TOKEN')
    ->post('https://courier.mailyte.com/api/v1/mailbox/devices', [
    'token' => 'fcm-or-apns-device-token',
    'platform' => 'ios',
    'app_version' => '2.1.0',
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://courier.mailyte.com/api/v1/mailbox/devices")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer MAILBOX_TOKEN"
request["Content-Type"] = "application/json"
request.body = {
  "token": "fcm-or-apns-device-token",
  "platform": "ios",
  "app_version": "2.1.0"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

Successful Response

dataobject
- idstring
- platformstring
- app_versionstring or null
- created_atstring or null
- last_seen_atstring or null
- push_enabledboolean

200application/json

{
  "type": "success",
  "msg": "Device registered",
  "data": {
    "id": "01J9ZR...",
    "platform": "ios",
    "app_version": "2.1.0",
    "created_at": "2026-10-11T08:00:00+00:00",
    "last_seen_at": "2026-10-11T08:00:00+00:00",
    "push_enabled": true
  }
}

Returned inside the standard envelope.

Errors

Status	When
`401`	No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
`403`	The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
`422`	Unknown platform, or token too long
`500`	Database unavailable

Every status, with what causes it and what to do, is on the error reference.