Subscription API - Read

View as Markdown OpenAPI

Use the read endpoints to retrieve subscriptions for your account. You can list all subscriptions with filtering and sorting, or retrieve a single subscription by ID.

Endpoints

Method	URL	Description
GET	`https://e1.envoke.com/v2/subscriptions`	Return a list of subscriptions.
GET	`https://e1.envoke.com/v2/subscriptions/{ID}`	Return a single subscription.

Authentication is via HTTP Basic Auth using your API ID and API Key.

List Subscriptions

GET https://e1.envoke.com/v2/subscriptions

Returns a JSON array of subscriptions for your account, sorted alphabetically by name by default. Supports filtering, sorting, pagination, and field selection.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`10`	Maximum number of results to return. Hard cap is `100` unless `?fields=` or `?result_type=kvp` is also set (see note below).
`skip`	integer	`0`	Number of records to skip. Use with `limit` to paginate.
`fields`	string	(all)	Comma-separated list of fields to include in each result. See limit note below.
`result_type`	string	(array)	Set to `kvp` to receive results as a key-value object (`{ "id": "name" }`). See limit note below.
`filter[id]`	string	—	Filter by subscription ID.
`filter[name]`	string	—	Filter by subscription name.
`filter[external_id]`	string	—	Filter by external ID.
`filter[group]`	string	—	Filter by group name.
`filter[prefpage_access]`	string	—	Filter by preference page access (`public` or `private`).
`sort[name]`	string	—	Sort by name. Value: `asc` or `desc`.

Note — limit behaviour with ?fields= and ?result_type=kvp: When either of these parameters is present, the default limit increases to 10,000 (returning all records if no explicit limit is specified) and a ?limit= value above 100 is honoured as-is. This allows full exports and dropdown population without pagination.

Filter Operators

All filter[field] parameters support exact match and the not-equal operator:

Operator	Example	Description
(none)	`?filter[name]=Campus Weekly`	Exact match
`(ne)`	`?filter[group][(ne)]=Archived`	Not equal

Note: URL-encode brackets in production requests (e.g. %5B for [).

Response

A JSON array of subscription objects. Returns an empty array ([]) if no subscriptions exist or no results match the filter.

[
  {
    "id": "12",
    "external_id": "a1b2c3d4e5f6",
    "name": "Campus Weekly Newsletter",
    "group": "Student Communications",
    "prefpage_access": "public",
    "display_names": { "en": "Campus Weekly Newsletter", "fr": "Bulletin hebdomadaire du campus" },
    "display_descriptions": { "en": "A weekly roundup of campus news and events.", "fr": "" }
  }
]

display_names and display_descriptions are always present in list responses. All enabled account languages appear as keys, with empty strings where no translation has been set.

Get a Single Subscription

GET https://e1.envoke.com/v2/subscriptions/{ID}

Returns a single subscription object. Replace {ID} with the Envoke subscription ID.

If the ID is not found, the API returns an empty array ([]).

Response

{
  "id": "12",
  "external_id": "a1b2c3d4e5f6",
  "name": "Campus Weekly Newsletter",
  "group": "Student Communications",
  "prefpage_access": "public",
  "display_names": { "en": "Campus Weekly Newsletter", "fr": "Bulletin hebdomadaire du campus" },
  "display_descriptions": { "en": "A weekly roundup of campus news and events.", "fr": "" }
}

Examples

Return all subscriptions (default pagination)

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions"

Paginate through results

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?limit=10&skip=10"

Filter by group

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?filter%5Bgroup%5D=Student+Communications"

Filter by name

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?filter%5Bname%5D=Campus+Weekly+Newsletter"

Filter by prefpage_access

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?filter%5Bprefpage_access%5D=public"

Filter excluding a group

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?filter%5Bgroup%5D%5B%28ne%29%5D=Alumni+Relations"

Sort by name descending

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?sort%5Bname%5D=desc"

Return only specific fields

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?fields=id,name,group"

Return as a key-value map (for dropdowns)

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions?result_type=kvp"

Response:

{ "12": "Campus Weekly Newsletter", "13": "Alumni Quarterly" }

Get a single subscription by ID

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/subscriptions/12"

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.