Add a status page subscriber

Adds an e-mail subscriber with optional resource and update-type filters.

POST https://app.upfour.io/v1/status-pages/{pageID}/subscribers

A real request. Sending it changes data in your up4 account.

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs status_page.subscriber.write.

Path

pageIDpath · requiredPart of the request path.

Body

emailrequired

More fields1

subscribed_to all (the default), incident or maintenance.

1 more field is only available in JSON.

Headers

Idempotency-KeyheaderGenerated automatically when empty. How it works

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope status_page.subscriber.write stable Idempotency-Key supported returns 201

Parameters

Field	Type	Description
`pageID` required	uuid	path parameter

Body

application/json required 3 fields

emailstringrequired

All other fields2 fields

resource_idsuuid[]

Components of this page to follow; empty follows all.

subscribed_tostring

all (the default), incident or maintenance.

allincidentmaintenance

Returns

A successful request returns 201 with application/json.

Response fields 1 top-level fields

Field Type Description

data StatusPageSubscriber

StatusPageSubscriber · 15 fields

Field	Type	Description
`channel`	string one of`emailwebhook`
`confirmed`	boolean
`created_at`	string (date-time)
`email`	string
`failure_count`	integer
`id`	uuid
`resource_ids`	uuid[] · nullable
`status_page_id`	uuid
`subscribed_to`	string one of`allincidentmaintenance`
`disabled_at`	string (date-time)
`last_delivery_at`	string (date-time)
`last_failure_at`	string (date-time)
`suppression`	string one of`hard_bouncecomplaint`	Why nothing is mailed to the address; empty when it is not suppressed.
`suppression_liftable`	boolean	True for a hard bounce, which an owner or admin may release; a complaint stays with up4.
`webhook_target`	string	The webhook URL in masked form; never the full URL or its secret.

Errors

Only the errors this operation can return. Every error uses the same envelope.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
402	`billing_action_unavailable`	The Company's billing state does not allow this action. When: A metered or limited action while the billing state, such as paused or without credit, blocks it; details holds the action and billing_state. Fix: Top up the credit or change the plan, then retry.
429	`confirmation_rate_limited`	Subscriber confirmation emails are being sent faster than the limits allow. When: Adding subscribers faster than the confirmation limits allow; details.reason says which limit, and details.retry_at and Retry-After say when to try again. Fix: Wait until details.retry_at, then add the remaining addresses. `confirmation_rate_limited`: no further confirmation mail can go to this address right now. `error.details.reason` is `too_soon` (2 minutes between mails per page and address), `daily` (3 per 24 hours) or `open` (5 open confirmations per address); `error.details.retry_at` and the `Retry-After` header say when the same request can succeed.
404	`not_found`	The requested resource does not exist or is outside the caller's scope.
403	`permission_denied`	The credentials do not permit this action.
503	`quota_gate_unavailable`	The limit check itself failed, so the action was not carried out. When: The quota service could not decide while the request ran. Fix: Retry in a moment; nothing was changed.
403 / 429	`quota_limit_reached`	A usage or inventory limit of the Company was reached. When: Counters and concurrency limits answer 429 with Retry-After, inventory and capacity limits answer 403; details holds purpose, limit and window. Fix: On 429 wait Retry-After seconds; on 403 free something up, request a higher limit where details.raise_request is true, or buy an extension.
422	`subscriber_confirmations_full`	Too many addresses are waiting for confirmation. When: An import or sign-up that would exceed the number of unconfirmed addresses allowed; nothing was added, details gives new_addresses and free_places. Fix: Wait for confirmations or remove unconfirmed addresses, then add fewer addresses.
402	`subscriber_import_requires_payment`	Subscriber import is locked while the Company is on its starting credit. When: Importing subscribers before the first payment. Fix: Top up the credit, then import.
409	`subscriber_import_running`	Another subscriber import of this Company is still running. When: Starting an import while a previous one has not finished. Fix: Wait for the running import to finish, then start the next.
413	`subscriber_import_too_large`	The subscriber file is over the size limit. When: Uploading a subscriber file larger than details.max_bytes. Fix: Split the file into smaller ones.
422	`subscriber_import_too_many_rows`	The subscriber import has too many rows. When: An import with more rows than details.max_rows; nothing was imported. Fix: Split the import into several files.

Every call can also return unauthorized (401), rate_limit_exceeded (429) or internal_error (500 / 502). See Responses and errors.

curl -s -X POST "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "carla@example.com", "subscribed_to": "all" }'

const res = await fetch("https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ email: "carla@example.com", subscribed_to: "all", }), }); console.log(res.status, await res.json());

import os import requests res = requests.post( "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "email": "carla@example.com", "subscribed_to": "all", }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "email": "carla@example.com", "subscribed_to": "all" }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) }

<?php $payload = <<<'JSON' { "email": "carla@example.com", "subscribed_to": "all" } JSON; $ch = curl_init("https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch);

{ "data": { "channel": "email", "confirmed": false, "created_at": "2026-10-27T09:00:00Z", "email": "carla@example.com", "failure_count": 0, "id": "00000000-0000-4000-8000-000000000002", "resource_ids": null, "status_page_id": "00000000-0000-4000-8000-000000000001", "subscribed_to": "all" } }