Import status page subscribers

Imports subscriber e-mail addresses from text or a multipart file and reports imported, invited and skipped counts.

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

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

emailsrequired The addresses as text

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 200

Parameters

Field	Type	Description
`pageID` required	uuid	path parameter

Body

application/json required 1 field

emailsstringrequired

The addresses as text

Returns

A successful request returns 200 with application/json.

Response fields 1 top-level fields

Field Type Description

data StatusPageSubscriberUploadResponse

StatusPageSubscriberUploadResponse · 3 fields

Field	Type	Description
`imported`	integer	Same number as invited, kept for older API clients.
`invited`	integer
`skipped`	integer	Invalid or duplicate addresses and addresses that unsubscribed before.

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.
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.
200 / 410 / 413 / 422	`request_failed`	The request could not be completed. The list is larger than 2 MiB (`error.details.max_bytes`). The code is `subscriber_import_too_large`, or `request_failed` when the upload is cut off in transit. Nothing is imported.
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. `subscriber_import_requires_payment`: importing subscriber lists is locked while the Company is on its starting credit.
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. `subscriber_import_running`: another subscriber import of this Company is still running; retry when it has finished.
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. `subscriber_import_too_many_rows`: the list has more than 10,000 rows (`error.details.max_rows`). Nothing is imported.
400	`upload_invalid`	The upload could not be read as a multipart form. When: A body that is not a valid multipart form, or whose file cannot be parsed. Fix: Send a well-formed multipart/form-data request. Stable codes next to the English message: `upload_no_file` (the form has no `file` part), `upload_invalid` (the upload could not be read).
400	`upload_no_file`	The multipart request has no file part. When: An upload request without a file field. Fix: Send the file as multipart/form-data in the field the operation names.

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/upload" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "emails": "anna@example.com" }'

const res = await fetch("https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers/upload", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ emails: "anna@example.com", }), }); 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/upload", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "emails": "anna@example.com", }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "emails": "anna@example.com" }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers/upload", 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' { "emails": "anna@example.com" } JSON; $ch = curl_init("https://app.upfour.io/v1/status-pages/00000000-0000-4000-8000-000000000001/subscribers/upload"); 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);