Subscription API - Insert

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.

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