Replace one person’s standing on this site

PUT

/v1/newsletters/subscriptions

const url = 'https://your-tenant-host/v1/newsletters/subscriptions';
const options = {
  method: 'PUT',
  headers: {
    'x-edgekit-site-id': 'site_example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"subscribed":["01999b1e-7a40-7c2d-9e51-2a4c8d0f6b31"],"email":"subscriber@example.com","userId":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://your-tenant-host/v1/newsletters/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-edgekit-site-id: site_example' \
  --data '{ "subscribed": [ "01999b1e-7a40-7c2d-9e51-2a4c8d0f6b31" ], "email": "subscriber@example.com", "userId": "example" }'

Full replacement, not a patch. Anything this site deploys and subscribed omits becomes unsubscribed. One exception: a list currently pending stays pending, named or omitted. The response echoes the full resulting set, so the client sees everything the replacement changed. 202 rather than 200 when anything is left awaiting confirmation: a fresh confirmation email has just gone out and the standing is not final. Every other outcome is 200. The anonymous path, an email and no credential, adds and never removes: an omitted list is left as it is. Its echo is what a never-seen address would get (named lists pending or subscribed, the rest unknown), whether or not the address already belonged to a user. Removing a standing needs an EdgeKit session, a verified upstream credential, or a site-pinned API key. Safe to retry: a repeat converges on the same standing, but re-sends the confirmation for every list still pending.

Authorizations

ApiKeyAuth
ApiKeyHeader
UserSession
None

Parameters

Header Parameters

x-edgekit-site-id

required

The site this request is for, within this tenant. Every official EdgeKit SDK sets it from the client you configured; set it yourself only when calling this API directly.

string

>= 1 characters <= 128 characters

Example

site_example

The site this request is for, within this tenant. Every official EdgeKit SDK sets it from the client you configured; set it yourself only when calling this API directly.

Request Body^required

application/json

object

subscribed

required

Full replacement: the list ids that should end up subscribed. Anything this site deploys and this array omits becomes unsubscribed, with one exception: a list currently pending stays pending whether it is named or omitted, because a replacement does not resolve a state the subscriber never answered. An empty array is a complete unsubscribe, allowed under a credential that names the user. With only an email, omission removes nothing: that path only adds, and the echo answers unknown for whatever it did not name.

Array<string>

Example

[
  "01999b1e-7a40-7c2d-9e51-2a4c8d0f6b31"
]

email

The only way the anonymous browser path names a subject. The address resolves to its existing user, or creates one. A 400 when the credential already names a user: an EdgeKit session or a verified upstream credential already says who this is, and accepting a second answer would let the page write to somebody else unnoticed.

string

>= 1 characters

Example

subscriber@example.com

userId

Allowed only when the credential is an API key; a 400 otherwise, never ignored. Dropping an identity assertion with no error would let a server-side integration write to the wrong user unnoticed.

string

>= 1 characters

Responses

200

The full resulting set. Nothing is awaiting confirmation.

application/json

object

subscriptions

required

Every deployed list for the site, including those this person has no record on. On a PUT this is the full resulting set, which shows what a full replacement removed: a client that renders four lists and sends four ids has just unsubscribed the fifth.

Array<object>

object

required

The list’s id (UUIDv7). A list is named by its id, never by its slug.

string format: uuid

slug

required

^[a-z][a-z0-9_]*$, unique per site: two sites in one organization can both run a morning_briefing, so it is not unique per tenant.

string

label

required

What a preference centre renders and what the confirmation email says it is confirming. Tenant-authored, staged and deployed.

string

description

required

A sentence, or null. Shown in the confirmation email beside the label; without it, somebody subscribing to two lists gets two identical emails.

string | null

status

required

unknown means EdgeKit has no record of this person on this list. pending is double opt-in’s: the address was given and the confirmation link has not been clicked yet. A pending address is never sent to the delivery vendor. Open: render an unknown member as unknown.

string

Example

{
  "subscriptions": [
    {
      "id": "01999b1e-7a40-7c2d-9e51-2a4c8d0f6b31",
      "slug": "morning_briefing",
      "label": "The Morning Briefing",
      "status": "subscribed"
    }
  ]
}

202

The full resulting set, with at least one list pending. A confirmation email carrying a fresh link has been sent for each.

application/json

object

subscriptions

required

Array<object>

object

required

The list’s id (UUIDv7). A list is named by its id, never by its slug.

string format: uuid

slug

required

^[a-z][a-z0-9_]*$, unique per site: two sites in one organization can both run a morning_briefing, so it is not unique per tenant.

string

label

required

What a preference centre renders and what the confirmation email says it is confirming. Tenant-authored, staged and deployed.

string

description

required

A sentence, or null. Shown in the confirmation email beside the label; without it, somebody subscribing to two lists gets two identical emails.

string | null

status

required

string

Example

{
  "subscriptions": [
    {
      "id": "01999b1e-7a40-7c2d-9e51-2a4c8d0f6b31",
      "slug": "morning_briefing",
      "label": "The Morning Briefing",
      "status": "subscribed"
    }
  ]
}

400

Invalid request.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

401

Missing or invalid credential.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403

Not allowed.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

404

Resource not found.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

422

Request validation failed.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

429

Too many requests. Retry-After says when to retry.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

500

Unexpected error.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

503

With Retry-After, briefly unavailable; without it, not configured.

application/json

object

error

required

object

code

required

string

message

required

string

details

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

Replace one person’s standing on this site

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Example

Example

Responses

200

Example

202

Example

400

Example

401

Example

403

Example

404

Example

422

Example

429

Example

500

Example

503

Example

Request Body^required