Subscription API - Fields Reference

This article describes all fields available through the Subscription API. Use this as a reference when reading, creating, or updating subscriptions.

Overview

The Subscription API lets you manage email subscriptions in your Envoke account programmatically. Subscriptions represent communication types that contacts can opt in to or out of — for example, a weekly newsletter, event announcements, or alumni updates. They appear on your public preference page where contacts manage their own communication preferences.

Subscriptions can be organised into groups, given translated display names and descriptions for public-facing contexts, and optionally hidden from the public preference page using prefpage_access.

All endpoints require HTTP Basic Auth using your API ID and API Key.

Fields

Field	Type	Read-only	Required on Create	Description
`id`	string	Yes	—	Unique identifier assigned on creation.
`external_id`	string	Yes	—	Externally visible identifier used in public-facing integrations.
`name`	string	No	Yes	The subscription name.
`group`	string	No	No	Group the subscription belongs to. Empty string (`""`) when unassigned.
`prefpage_access`	string	No	No	Controls preference page visibility. `"public"` (default) or `"private"`.
`display_names`	object	No	No	Translated display labels keyed by ISO language code.
`display_descriptions`	object	No	No	Translated descriptions keyed by ISO language code.

Field Details

`id`

Type: String
Read-only: Yes — assigned automatically on creation.
Example: "12"

Used to identify the subscription in update, delete, and contact assignment requests.

`external_id`

Type: String
Read-only: Yes — assigned automatically on creation.
Example: "a1b2c3d4e5f6"

An externally visible identifier used in public-facing contexts such as preference page URLs. Not the same as id.

`name`

Type: String
Read-only: No — updatable via PATCH.
Required on create: Yes
Example: "Campus Weekly Newsletter"

The subscription name as it appears within your Envoke account. This is the internal label used by account administrators.

`group`

Type: String
Read-only: No — updatable via PATCH.
Required on create: No
Accepted values (write): Group name (string) or group ID (integer). The group must be of type subscription.
Returned value (read): The group name as a string. Returns "" (empty string) when no group is assigned.
Example: "Student Communications", ""

Pass "" (empty string) or null to remove an existing group assignment via PATCH.

`prefpage_access`

Type: String
Read-only: No — updatable via PATCH.
Required on create: No
Accepted values: "public" or "private"
Default: "public"
Example: "public"

Controls whether this subscription appears on the public preference page.

"public" — The subscription is visible to contacts on the preference page. This is the default.
"private" — The subscription is hidden from the public preference page. It can still be assigned to contacts via the API or within your account. Requires the private subscriptions feature. Attempting to set this value without the feature enabled returns a validation error.

`display_names`

Type: Object
Read-only: No — updatable via PATCH.
Required on create: No
Format: { "<language_code>": "<display_text>" }
Example: { "en": "Campus Weekly Newsletter", "fr": "Bulletin hebdomadaire du campus" }

Translated display labels for the subscription, keyed by ISO language code. These are shown to contacts on the public preference page as the subscription's visible name. A value of "" means no translation has been set for that language. All enabled account languages are included as keys in responses even if no translation exists.

`display_descriptions`

Type: Object
Read-only: No — updatable via PATCH.
Required on create: No
Format: { "<language_code>": "<description_text>" }
Example: { "en": "A weekly roundup of campus news, events, and announcements.", "fr": "Un résumé hebdomadaire des nouvelles et événements du campus." }

Translated descriptions for the subscription, keyed by ISO language code. These are shown alongside the display name on the public preference page to help contacts understand what they are subscribing to. A value of "" means no description has been set for that language. All enabled account languages are included as keys in responses even if no description exists.

Error Responses

Validation errors (missing required fields, invalid values):

{   "success": false,   "result_text": "Validation failed, see 'result_data' -> 'errors'",   "result_data": {     "errors": [       "The field 'name' is required"     ]   } }

Not-found behaviour varies by method:

GET /subscriptions/{id} — when the ID is not found, returns an empty array ([]).
PATCH /subscriptions/{id} — when the ID is not found, returns a validation error:

{   "success": false,   "result_text": "Validation failed, see 'result_data' -> 'errors'",   "result_data": {     "errors": ["Item with id '999999' not found"]   } }

DELETE /subscriptions/{id} — when the ID is not found, returns a validation error:

{   "success": false,   "result_text": "Validation failed, see 'result_data' -> 'errors'",   "result_data": {     "errors": ["Item with id '999999' not found"]   } }

For code examples and interactive testing, visit api.envoke.com.