The newsletters this site offers

GET

/v1/newsletters/lists

const url = 'https://your-tenant-host/v1/newsletters/lists';
const options = {
  method: 'GET',
  headers: {'x-edgekit-site-id': 'site_example', Authorization: 'Bearer <token>'}
};

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

curl --request GET \
  --url https://your-tenant-host/v1/newsletters/lists \
  --header 'Authorization: Bearer <token>' \
  --header 'x-edgekit-site-id: site_example'

The deployed list set for the selected site. A disabled list is left out of the deployed document entirely, so it cannot appear here and there is no flag to filter on. A tenant that has never deployed answers an empty set, the same as a tenant with no newsletters: by design, nothing distinguishes the two.

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.

Responses

200

Every deployed list for this site.

application/json

object

lists

required

The deployed set for the selected site. A disabled list is left out of the deployed document entirely, so it cannot appear here and there is no enabled field to read.

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

Example

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

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."
  }
}

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."
  }
}