# Subscription Lists

Subscription Lists are lists of channels that can be used to target messages to specific groups of users.


## Contact Subscription List object {#contactsubscriptionlistobject}

A list of subscription list items associated with the specified contact. Each item consists of a list of list IDs and an optional scope.

[Jump to examples ↓](#contactsubscriptionlistobject-examples)

- **`list_ids`** `array` <[List ID]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistid)> **REQUIRED**

  A list of subscription lists associated to the specified scope. If no scope is specified these subscription lists are not scoped.

  Min items: 1, Max items: 100

  Example: `example_listId-1,example_listId-5`

- **`scope`** `string` <[Scopes]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#scopes)>

  The channel types where membership applies. The `app` scope includes `iOS`, `Android`, and `Amazon` channels.

  Possible values: `app`, `web`, `email`, `sms`


**Used in:**

- [Named User subscription lists listing]({{< ref "/developer/rest-api/ua/operations/subscription-lists/" >}}#getnamedusersubscriptionlists)

**Examples**

*Example contact Subscription Lists object*

```json
{
   "list_ids": ["example_listId-2", "example_listId-4"],
   "scope": "app"
}

```

---

## Contact Subscription List object {#contactsubscriptionlistsobject}

Defines the Subscription List changes.

- **`subscribe`** `array[string]`

  Subscribe to the specified Subscription List identifier.

- **`unsubscribe`** `array[string]`

  Unsubscribe the specified Subscription List identifier.


---

## List ID {#subscriptionlistid}

A list ID that contains only alphanumeric characters, underscores, or hyphens.

**Used in:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend)
- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Create pipeline (automated message)]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#createpipeline)
- [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment)
- [Create template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#createtemplate)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [Individual pipeline lookup]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipeline)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List existing pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipelines)
- [List filtered pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getfilteredpipelines)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [List templates]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplates)
- [Look up a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplate)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [Named User subscription lists listing]({{< ref "/developer/rest-api/ua/operations/subscription-lists/" >}}#getnamedusersubscriptionlists)
- [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate)
- [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)
- [Subscription lists listing]({{< ref "/developer/rest-api/ua/operations/subscription-lists/" >}}#getsubscriptionlists)
- [Update pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#updatepipeline)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment)
- [Update template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#updatetemplate)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate)
- [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)
- [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush)
- [Validate pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#validatepipeline)

---

## Named User scoped batch item {#scopedbatchitem}

Contains `scope` and `subscription_lists`.

[Jump to examples ↓](#scopedbatchitem-examples)

- **`scope`** `array` <[Scopes]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#scopes)> **REQUIRED**
- **`subscription_lists`** `object` <[Named User Subscription List object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#namedusersubscriptionlistsobject)> **REQUIRED**

  Defines the Subscription List changes.


**Used in:**

- [Scoped Named User batch operations]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#performnameduserscopedbatchoperations)

**Examples**

*Example scoped batch item*

```json
{
    "scope": ["app"],
    "subscription_lists": {
        "subscribe": ["stickers", "gifs"],
        "unsubscribe": ["cookies"]
    }
}

```

---

## Named User Subscription List object {#namedusersubscriptionlistsobject}

Defines the Subscription List changes.

[Jump to examples ↓](#namedusersubscriptionlistsobject-examples)

- **`subscribe`** `array[string]`

  Subscribe to the specified Subscription List identifier.

- **`unsubscribe`** `array[string]`

  Unsubscribe the specified Subscription List identifier.


**Used in:**

- [Scoped Contact batch operations]({{< ref "/developer/rest-api/ua/operations/contacts/" >}}#performscopedcontactbatchoperations)
- [Scoped Named User batch operations]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#performnameduserscopedbatchoperations)

**Examples**

*Example Subscription Lists object*

```json
{
    "subscribe": ["stickers", "gifs"],
    "unsubscribe": ["cookies"]
}

```

---

## Scopes {#scopes}

The channel types where membership applies. The `app` scope includes `iOS`, `Android`, and `Amazon` channels.

`string`

Allowed values: `app`, `web`, `email`, `sms`

**Used in:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend)
- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Create pipeline (automated message)]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#createpipeline)
- [Create template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#createtemplate)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [Individual pipeline lookup]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipeline)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List existing pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipelines)
- [List filtered pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getfilteredpipelines)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [List templates]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplates)
- [Look up a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplate)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [Named User subscription lists listing]({{< ref "/developer/rest-api/ua/operations/subscription-lists/" >}}#getnamedusersubscriptionlists)
- [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Scoped Contact batch operations]({{< ref "/developer/rest-api/ua/operations/contacts/" >}}#performscopedcontactbatchoperations)
- [Scoped Named User batch operations]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#performnameduserscopedbatchoperations)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)
- [Subscription lists listing]({{< ref "/developer/rest-api/ua/operations/subscription-lists/" >}}#getsubscriptionlists)
- [Update pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#updatepipeline)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Update template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#updatetemplate)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)
- [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush)
- [Validate pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#validatepipeline)

---

## Subscription List action {#subscriptionlistmutation}

A string representing the membership mutation action to be taken for a given list.

`string`

Allowed values: `subscribe`, `unsubscribe`

**Used in:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend)
- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Create pipeline (automated message)]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#createpipeline)
- [Create template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#createtemplate)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [Individual pipeline lookup]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipeline)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List existing pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipelines)
- [List filtered pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getfilteredpipelines)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [List templates]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplates)
- [Look up a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplate)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)
- [Update pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#updatepipeline)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Update template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#updatetemplate)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)
- [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush)
- [Validate pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#validatepipeline)

---

## Subscription List item object {#namedusersubscriptionlistitem}

An item consisting of a list of list IDs and scope.

[Jump to examples ↓](#namedusersubscriptionlistitem-examples)

- **`list_ids`** `array` <[List ID]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistid)> **REQUIRED**

  A list of subscription lists associated to the specified scope. If no scope is specified these subscription lists are not scoped.

  Min items: 1, Max items: 100

  Example: `example_listId-1,example_listId-5`

- **`scope`** `string`

  Scope as a string.

  Possible values: `app`, `email`, `sms`, `web`


**Used in:**

- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)

**Examples**

*Example Subscription List item*

```json
{
  "list_ids": ["example_listId-2", "example_listId-3"],
  "scope": "app"
}

```

---

## Subscription List object {#subscriptionlistobject}

[Jump to examples ↓](#subscriptionlistobject-examples)

- **`action`** `object` **REQUIRED**
  **One of:**

  - **Channel Subscription List action** `object`

    Alters Subscription List membership for a channel.

    - **`action`** `string` <[Subscription List action]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistmutation)> **REQUIRED**

      A string representing the membership mutation action to be taken for a given list.

      Possible values: `subscribe`, `unsubscribe`

    - **`list_id`** `string` <[List ID]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistid)> **REQUIRED**

      A list ID that contains only alphanumeric characters, underscores, or hyphens.

    - **`type`** `string` **REQUIRED**

      Possible values: `channel`

  - **Contact subscription list action** `object`

    Alters subscription list membership for a contact.

    - **`action`** `string` <[Subscription List action]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistmutation)> **REQUIRED**

      A string representing the membership mutation action to be taken for a given list.

      Possible values: `subscribe`, `unsubscribe`

    - **`list_id`** `string` <[List ID]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistid)> **REQUIRED**

      A list ID that contains only alphanumeric characters, underscores, or hyphens.

    - **`scope`** `string` <[Scopes]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#scopes)> **REQUIRED**

      The channel types where membership applies. The `app` scope includes `iOS`, `Android`, and `Amazon` channels.

      Possible values: `app`, `web`, `email`, `sms`

    - **`type`** `string` **REQUIRED**

      Possible values: `contact`


- **`list_id`** `string` <[List ID]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistid)> **REQUIRED**

  A list ID that contains only alphanumeric characters, underscores, or hyphens.

- **`timestamp`** `string`

  The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. Server time is used when not present.


  Format: `date-time`


**Used in:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)

**Examples**

*Example Subscription List object*

```json
{
  "action": "subscribe",
  "list_id": "exciting_news"
}

```

---

## Subscription List result object {#subscriptionlistresultobject}

Defines the subscription list result object.

[Jump to examples ↓](#subscriptionlistresultobject-examples)

- **`default_opted_in`** `boolean` **REQUIRED**

  `True` if the audience defined by `scopes` are opted in by default, otherwise `false`.

- **`description`** `object`

  Description of the subscription list.

- **`list_id`** `string` <[List ID]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistid)> **REQUIRED**

  A list ID that contains only alphanumeric characters, underscores, or hyphens.

- **`message_type`** `string`

  The message type.

  Possible values: `transactional`, `commercial`

- **`name`** `string`

  Human readable name.

  Example: `A nice name readable name 1`

- **`scopes`** `array` <[Scopes]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#scopes)> **REQUIRED**

  An array of scopes applicable to the subscription list. Valid scopes are `app`, `web`, `email`, and `sms`.

  Min items: 1, Max items: 100


**Used in:**

- [Subscription lists listing]({{< ref "/developer/rest-api/ua/operations/subscription-lists/" >}}#getsubscriptionlists)

**Examples**

*Example Subscription List result object*

```json
{
   "list_id": "example_listId-2",
   "name": "A nice readable name 2",
   "description": "A very nice description for you.",
   "scopes": ["app", "web"],
   "default_opted_in": true
}

```

---