Create a recipient
Creates a recipient.
Creates a recipient.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/recipients - Scope
notify:write - Effect
write— a successful call changes state. - Collection recipients
- Query
recipient_id,validate_only
Request
| Field | Type | What it is |
|---|---|---|
parent | string | The parent to create in. Required. |
recipient_id | string | The recipient id, the final name segment; the server assigns one when empty. |
recipient | Recipient | The recipient to create; only caller-writable fields are read. Required. |
validate_only | bool | Validate and return the result without writing anything. |
Recipient
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/recipients/{recipient}. |
meta | ResourceMeta | Resource metadata. |
external_key | string | The customer's own id for this user, for example an Auth end user name. |
email_addresses | string[] | Email addresses, first is preferred. |
phone_numbers | string[] | E.164 phone numbers, first is preferred. |
language_code | string | BCP 47 language for templates; default the environment's. |
time_zone | string | IANA time zone for quiet hours and digests. |
test | bool | A test recipient: its messages are rendered and captured on the Message, never delivered. An email address whose local part carries +sylphx_test is a test address whatever this says. |
ResourceMeta
| Field | Type | What it is |
|---|---|---|
labels | map<string, string> | Caller-writable, indexed labels (AIP-122 label rules). |
annotations | map<string, string> | Caller-writable, unindexed annotations. |
display_name | string | Caller-writable human-readable name. |
Response
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/recipients/{recipient}. |
uid | string | rcp_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
external_key | string | The customer's own id for this user, for example an Auth end user name. |
email_addresses | string[] | Email addresses, first is preferred. |
phone_numbers | string[] | E.164 phone numbers, first is preferred. |
devices | PushDevice[] | Redacted push-device receipts. Use registerPushDevice and unregisterPushDevice; create/update never replace this array. Output only. |
language_code | string | BCP 47 language for templates; default the environment's. |
time_zone | string | IANA time zone for quiet hours and digests. |
test | bool | A test recipient: its messages are rendered and captured on the Message, never delivered. An email address whose local part carries +sylphx_test is a test address whatever this says. |
ResourceMeta
| Field | Type | What it is |
|---|---|---|
generation | int64 | Increases by one on every change to spec. Output only. |
etag | string | Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only. |
create_time | timestamp | When the Resource was created. Output only. |
update_time | timestamp | When the Resource last changed. Output only. |
delete_time | timestamp | Set while the Resource is being deleted. Output only. |
labels | map<string, string> | Caller-writable, indexed labels (AIP-122 label rules). |
annotations | map<string, string> | Caller-writable, unindexed annotations. |
display_name | string | Caller-writable human-readable name. |
creator | string | The principal that created the Resource. Output only. |
PushDevice
| Field | Type | What it is |
|---|---|---|
platform | PushPlatform | The platform. Required. One of apns, fcm, web_push. |
device_token | string | Write-only. For web_push, the exact JSON string returned by a browser's PushSubscription.toJSON(): endpoint, optional expirationTime, and keys containing base64url p256dh and auth. APNs and FCM are not yet served. Required. Never returned again. |
token_last4 | string | The last four characters of the token, for display. Output only. |
sender | string | The push Sender the token belongs to. Required. |
registration_id | string | Opaque registration receipt, stable across renewal at the same endpoint. RegisterPushDevice and UnregisterPushDevice preserve other devices. Output only. |
recipient_uid | string | Immutable Notify Recipient UID, not an authenticated application principal. The client binds this receipt to its independently verified active principal. Output only. |
registration_generation | int64 | Changes on every registration, including unregister/re-register. JSON uses a decimal string: clients must compare exactly, never convert to a JS Number. Output only. |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.UNKNOWN_FIELD— The request has a field the schema does not know.INVALID_FIELD— A field failed validation.RESOURCE_ALREADY_EXISTS— A Resource with this name exists.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.PLAN_LIMIT_REACHED— The plan's limit is reached.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/recipients" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'