Creates a single subscription. A subscription indicates which event types to receive notifications for and which callback, or webhook, to receive them on. A new subscription can take up to two minutes to become active. You can create a subscription only for a verified callback and up to 200 subscriptions per callback.
| Name | Type | Description |
|---|---|---|
subscriptionName | string | Required. Name of the subscription. This name must be unique. |
callbackId | string | Required. Unique identifier of the callback that receives the notification events. This callback must already exist and must be verified. |
eventCategoryTypes | array | Required. Comma-separated list of fully qualified event types for which you’re requesting notifications. Expressed as NotificationEventCategory.NotificationEventType. Review Supported Notification Events for a list of supported event categories and types. |
filters | array | Each string in the array is a key:value pair to filter on. Review Subscription Filters for a list of data items available for filtering. |
To create a subscription, send a POST request to the /platform/v1/ens-subscriptions endpoint.
The subscription you create is in active status, and event notifications are sent to the associated callback. Ensure that the callback you specify is ready to receive events before creating a subscription for it.
Note
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /platform/v1/ens-subscriptions
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6[{
7 "callbackId": "65b885ab-c2b4-46fe-85d0-d6cb8be8057d",
8 "subscriptionName": "sub1",
9 "eventCategoryTypes": ["TransactionalSendEvents.EmailNotSent",
10 "TransactionalSendEvents.EmailSent"],
11 "filters": ["definitionKey=12345"]
12}]The response contains information about the subscription.
1HTTP/1.1 201 Created
2[{
3 "callbackId": "65b885ab-c2b4-46fe-85d0-d6cb8be8057d",
4 "callbackName": "cb1",
5 "subscriptionName": "sub1",
6 "eventCategoryTypes": ["TransactionalSendEvents.EmailNotSent",
7 "TransactionalSendEvents.EmailSent"],
8 "subscriptionId": "d89c87c4-70f8-43d6-be1e-f01dce97fe4c",
9 "filters": ["definitionKey=12345"],
10 "status": "active"
11}]| Response | Reason |
|---|---|
| 201 Created | Subscription is created. Review example response. |
| 304 No Change | Subscription already exists on the server. |
| 400 Bad Request | Invalid request |
| 403 Forbidden | Failed to pass authorization. |
| 404 Not Found | Callback ID doesn’t exist. |
| 500 Server Error | Internal error |
j