# Add a status page subscriber — API reference > Adds an e-mail subscriber with optional resource and update-type filters. Source: https://upfour.io/docs/api/status-pages/add-a-status-page-subscriber [Developers](https://upfour.io/docs/api.md)/[Status pages](https://upfour.io/docs/api/status-pages.md) Adds an e-mail subscriber with optional resource and update-type filters. POST https://app.upfour.io/v1/status-pages/{pageID}/subscribers scope status_page.subscriber.write stable [Idempotency-Key supported](https://upfour.io/docs/api/idempotency.md) returns 201 ## Parameters | Field | Type | Description | | --- | --- | --- | | `pageID` required | uuid | path parameter | ## Body `application/json` required 3 fields emailstring (required) 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 FieldTypeDescription `channel` string one of`email` `webhook` `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`all` `incident` `maintenance` `disabled_at` string (date-time) `last_delivery_at` string (date-time) `last_failure_at` string (date-time) `suppression` string one of`hard_bounce` `complaint` 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](https://upfour.io/docs/api/responses.md). | Status | Code | Meaning | | --- | --- | --- | | 400 | [bad_request](https://upfour.io/docs/api/errors#code-bad_request) | The request is malformed or fails validation. | | 402 | [billing_action_unavailable](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-not_found) | The requested resource does not exist or is outside the caller's scope. | | 403 | [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) | The credentials do not permit this action. | | 503 | [quota_gate_unavailable](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/responses.md). [PreviousList status page subscribers](https://upfour.io/docs/api/status-pages/list-status-page-subscribers.md) [NextCount status page subscribers](https://upfour.io/docs/api/status-pages/count-status-page-subscribers.md) ## Request ### cURL ```bash 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" }' ``` ### JavaScript ```javascript 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()); ``` ### Python ```python 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()) ``` ### Go ```go 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 ```php "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); ``` ## Response ### 201 ```json { "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" } } ``` ### 400 ```json { "error": { "code": "bad_request", "message": "The request is malformed or fails validation.", "request_id": "req_…" } } ``` ### 402 ```json { "error": { "code": "billing_action_unavailable", "message": "The Company's billing state does not allow this action.", "request_id": "req_…" } } ``` ### 403 ```json { "error": { "code": "permission_denied", "message": "The credentials do not permit this action.", "request_id": "req_…" } } ``` ### 404 ```json { "error": { "code": "not_found", "message": "The requested resource does not exist or is outside the caller's scope.", "request_id": "req_…" } } ``` ### 409 ```json { "error": { "code": "subscriber_import_running", "message": "Another subscriber import of this Company is still running.", "request_id": "req_…" } } ``` ### 413 ```json { "error": { "code": "subscriber_import_too_large", "message": "The subscriber file is over the size limit.", "request_id": "req_…" } } ``` ### 422 ```json { "error": { "code": "subscriber_confirmations_full", "message": "Too many addresses are waiting for confirmation.", "request_id": "req_…" } } ``` ### 429 ```json { "error": { "code": "confirmation_rate_limited", "message": "Subscriber confirmation emails are being sent faster than the limits allow.", "request_id": "req_…" } } ``` ### 503 ```json { "error": { "code": "quota_gate_unavailable", "message": "The limit check itself failed, so the action was not carried out.", "request_id": "req_…" } } ```