Skip to main content

Subscription API - Insert

Written by Marcus Warren

Use this endpoint to create a new subscription in your account.

Endpoint

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

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

Request Body

Field

Type

Required

Description

name

string

Yes

The subscription name.

group

string or integer

No

Group name or group ID to assign the subscription to. The group must be of type subscription.

prefpage_access

string

No

Preference page visibility: "public" (default) or "private". Setting to "private" requires the private subscriptions feature.

display_names

object

No

Translated display labels keyed by ISO language code (e.g. { "en": "...", "fr": "..." }).

display_descriptions

object

No

Translated descriptions keyed by ISO language code (e.g. { "en": "...", "fr": "..." }).

Response

On success, the API returns the newly created subscription object:

{   "success": true,   "result_text": "Created",   "result_data": {     "id": "12",     "external_id": "a1b2c3d4e5f6",     "name": "Campus Weekly Newsletter",     "group": "Student Communications",     "prefpage_access": "public",     "display_names": { "en": "Campus Weekly Newsletter", "fr": "" },     "display_descriptions": { "en": "A weekly roundup of campus news and events.", "fr": "" }   } }

result_data.id is the Envoke subscription ID. Store this if you need to update, delete, or assign contacts to the subscription later.

Validation Errors

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

Common validation errors:

Error

Cause

Request body may not be empty

No JSON body was provided.

The field 'name' is required

name was missing or blank.

Invalid 'group': '{value}'

The group name or ID was not found, or is not of type subscription.

'prefpage_access' must be 'public' or 'private'

An unrecognised value was provided for prefpage_access.

Setting 'prefpage_access' to 'private' requires the private subscriptions feature

The account does not have the private subscriptions feature enabled.

Examples

Create a basic subscription

curl -X POST -gs \   -u "$API_ID:$API_KEY" \   -H "Content-Type: application/json" \   -d '{"name": "Campus Weekly Newsletter"}' \   "https://e1.envoke.com/v2/subscriptions"

Create with a group

curl -X POST -gs \   -u "$API_ID:$API_KEY" \   -H "Content-Type: application/json" \   -d '{"name": "Alumni Quarterly", "group": "Alumni Relations"}' \   "https://e1.envoke.com/v2/subscriptions"

Create with translated display names and descriptions

curl -X POST -gs \   -u "$API_ID:$API_KEY" \   -H "Content-Type: application/json" \   -d '{     "name": "Campus Weekly Newsletter",     "group": "Student Communications",     "display_names": {"en": "Campus Weekly Newsletter", "fr": "Bulletin hebdomadaire du campus"},     "display_descriptions": {"en": "A weekly roundup of campus news and events.", "fr": "Un résumé hebdomadaire des nouvelles et événements du campus."}   }' \   "https://e1.envoke.com/v2/subscriptions"

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

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

Did this answer your question?