Making Subscription Requests

The subscription operations provide a programmatic way to create and manage your subscriptions as well as add and remove end users to subscriptions. Read this page to find out how to use subscription operations, and try out the operations using cURL.

You can create simple subscriptions known as mailing list subscriptions using these operations. These can store subscriber details but do not provide automated processing. If you want to create a subscription with automated processing then you will need to use the MEP GUI.

Before we begin

Before beginning, you'll need a MEP account provisioned. Once provisioned, log into MEP and make sure in the MEP user account that you have the following settings:

  • In Main Roles:
    • Either Subscriptions Manager or Subscriptions User
  • In Other Roles:
    • View and download user details
    • HTTP Subscription API user

Make sure you have access to the correct subscription collections (Subscriptions - Subscription Collections). Note that users with the manager permission automatically have full access to these collections.

Screenshot showing the user permissions required for the subscription operations

Create a subscription collection

You'll need to create a subscription collection first. These are folders that group together related subscriptions. You can create them using the MEP user interface:

  1. Click on the Subscriptions tab in MEP
  2. Click "Create Subscription Collection". This opens a modal window.
  3. In the modal, add a name for your collection.
  4. Save the collection.

To retrieve the collection ID, left-click on the name of the collection. This opens a similar modal to before, where you can edit the name and description. You will also see the collection ID. Note this down, as you'll need it for your first API call.

Screenshot showing how to find a Subscription Collection ID.

Create a subscription

(Operation: Create a Subscription)

Now that you've got a subscription collection, you can start using API operations. Start by creating your first subscription. In the cURL call, you'll need to change the:

  • username and password to your own details
  • example subscription collection ID 1A2B3C4D5E to the ID of your own collection
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/createsubscription?username=MyUsername&password=P4S5W0Rd&collection=1A2B3C4D5E&name=My+New+Subscription"

If your request is successful, OpenMarket will return a synchronous response, similar to the following. 

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:14:43 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="ISO-8859-1"?>
<subscriptions>
   <subscription>
   <id>F9E8D7C6B5</id>
   <name>My New Subscription</name>
   <description/>
   <collection>1A2B3C4D5E</collection>
   <enabled>true</enabled>
   </subscription>
</subscriptions>

You'll need the returned id (in this example: F9E8D7C6B5) to add users to the subscription, so make a note of this.

Add an end user to the subscription

(Operation: Add End User to a Subscription)

Let's add our first end user to the subscription. You can use the mobile number that is already in the cURL example — it's one of the many that are reserved for fictional use (like television shows) in the United States.

In the cURL call, you'll need to change the:

  • username and password to your own details
  • example subscription ID F9E8D7C6B5 to the ID of your own subscription
curl -D - -X GET "http://cmx2api.openmarket.com/subscriptionapi/adduser?username=MyUsername&password=P4S5W0Rd&subscription=F9E8D7C6B5&msisdn=12515550100&network=CINGULARUS"

If your request is successful, OpenMarket will return a synchronous response, similar to the following. 

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:36:54 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="ISO-8859-1"?>
<users>
   <user>
   <msisdn>12515550100</msisdn>
   <network>CINGULARUS</network>
   <enabled>true</enabled>
   </user>
</users>

Get the end users in the subscription

(Operation: Get End Users in a Subscription)

Now that we have an end user in the subscription, let's make a call to see the subscription members.

In the cURL call, you'll need to change the:

  • username and password to your own details
  • example subscription ID F9E8D7C6B5 to the ID of your own subscription
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/viewsubscriptionusers?username=MyUsername&password=P4S5W0Rd&subscription=F9E8D7C6B5"

If your request is successful, OpenMarket will return a synchronous response, similar to the following.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:39:17 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="ISO-8859-1"?>
<users>
   <user>
   <msisdn>12515550100</msisdn>
   <network>CINGULARUS</network>
   <enabled>true</enabled>
   <startDate>2016-03-15 16:36:54</startDate>
   </user>
</users>

Get the subscriptions for an end user

(Operation: Get Subscriptions for an End User)

You can also check the subscriptions that an end user is in. In the cURL call, change the:

  • username and password to your own details
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/viewusersubscriptions?username=MyUsername&password=P4S5W0Rd&msisdn=12515550100&all=true"

If your request is successful, OpenMarket will return a synchronous response, similar to the following.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:51:01 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="ISO-8859-1"?>
<subscriptions>
   <subscription>
   <id>F9E8D7C6B5</id>
   <name>My New Subscription</name>
   <description/>
   <collection>1A2B3C4D5E</collection>
   <enabled>true</enabled>
   </subscription>
</subscriptions>

Remove the end user from the subscription

(Operation: Remove an End User from a Subscription)

To remove the end user from the subscription, make the following cURL call. You'll need to change the:

  • username and password to your own details
  • example subscription ID F9E8D7C6B5 to the ID of your own subscription
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/removeuser?username=MyUsername&password=P4S5W0Rd&subscription=F9E8D7C6B5&msisdn=12515550100"

If your request is successful, OpenMarket will return a synchronous response:

  • If the mobile number was in the subscription, you'll receive a response similar to the below. The enabled element set to false identifies that the user is no longer a part of the subscription.
  • If the mobile number wasn't in the subscription, the response will have an empty users element. 
HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 17:17:15 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="ISO-8859-1"?>
<users>
   <user>
   <msisdn>12515550100</msisdn>
   <network>CINGULARUS</network>
   <enabled>false</enabled>
   </user>
</users>

Get your subscription collections

(Operation: Get Subscription Collections)

You can make an API call to find out details about the collections you have access to in MEP. This can be useful for retrieving all your collection IDs quickly.

In the cURL call, change the:

  • username and password to your own details
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/getsubscriptioncollections?username=MyUsername&password=P4S5W0Rd"

If your request is successful, OpenMarket will return a synchronous response, similar to the following. We've added an extra subscription collection in the example. 

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 17:32:14 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="ISO-8859-1"?>
<collections>
   <collection>
   <id>1A2B3C4D5E</id>
   <name>ACME collection</name>
   <description>All subscriptions for ACME messaging</description>
   <enabled>true</enabled>
   </collection>
   <collection>
   <id>C4D5E1A2B3</id>
   <name>BRAVO collection</name>
   <description/>
   <enabled>true</enabled>
   </collection>
</collections>

Get your subscriptions inside a collection

(Operation: Get Subscriptions)

You may also want to retrieve details about subscriptions in a particular collection. In the cURL call, change the:

  • username and password to your own details
  • example collection ID 1A2B3C4D5E to the ID of your own subscription
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/getsubscriptionsincollection?username=MyUsername&password=P4S5W0Rd&collection=1A2B3C4D5E"

If your request is successful, OpenMarket will return a synchronous response, similar to the following.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 17:46:55 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain
					
<?xml version="1.0" encoding="ISO-8859-1"?>
<subscriptions>
   <subscription>
      <id>F9E8D7C6B5</id>
      <name>My New Subscription</name>
      <description/>
      <collection>1A2B3C4D5E</collection>
      <enabled>true</enabled>
   </subscription>
   <subscription>
      <id>D7C6B5F9E8</id>
      <name>test</name>
      <description/>
      <collection>1A2B3C4D5E</collection>
      <enabled>true</enabled>
   </subscription>
</subscriptions>

Disable the subscription

(Operation: Disable a Subscription)

Let's look at how to disable the subscription. This has the following effect:

  • Once disabled, MEP ignores the subscription when processing SMS or MMS messages. For example, a broadcasts to the subscription will not send messages.
  • You will not be able to add or remove end users via the Add End User to a Subscription or Remove an End User from a Subscription operations.
  • You will not be able to add or remove end users manually in the MEP UI.
  • However, MEP will continue to add or remove users if the subscription is part of a service.

Let's disable the subscription. In the cURL call, change the:

  • username and password to your own details
  • example subscription ID F9E8D7C6B5 to the ID of your own subscription
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/disablesubscription?username=MyUsername&password=P4S5W0Rd&subscription=F9E8D7C6B5"

If your request is successful, OpenMarket will return a synchronous response, similar to the following.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 18:02:57 GMT
Server: Apache-Coyote/1.1
Content-Length: 2
Content-Type: text/plain

OK

If you need to re-enable the subscription, you can do this from the MEP user interface. See also Creating, Disabling, and Re-enabling Subscriptions.