[Internal] Old Keyword Marketing Short Code Docs

The US-only short code for Keyword marketing was discontinued for new customers in August 2015 so the docs were removed from the customer-facing KB. This is the content from the old docs and is for our reference for existing customers still using the Keyword Marketing Short Code.

To use Nexmo keyword marketing shared short code, you must first enable it on your account through Nexmo Dashboard.

URL Endpoint

Nexmo provides you with an option of a response as a JSON object, or an XML string-you get to choose which response by selecting the appropriate base URL for your request.

JSON Endpoint

https://rest.nexmo.com/sc/us/marketing/json

XML Endpoint

https://rest.nexmo.com/sc/us/marketing/xml

HTTP Methods

All requests are submitted through the HTTP POST or GET method using UTF-8 encoding and URL encoded values.

Expected "Content-Type" for POST is "application/x-www-form-urlencoded", however we also support "application/json", "application/jsonrequest", "application/x-javascript", "text/json", "text/javascript", "text/x-javascript", "text/x-json" when posting parameters as a JSON object.

Security

To ensure privacy we recommend you to use HTTPS for all Nexmo API requests.

Authentication

All requests require your API credentials, you will find them in "API Settings" in Nexmo Dashboard.

Parameter	Description
api_key	Required. Your API Key. Ex: api_key=n3xm0rocks
api_secret	Required. Your API Secret. Ex: api_secret=12ab34cd

Keyword Marketing Parameters

Parameter	Description
from	Required. Nexmo Shared Short Code, can be found on your Dashboard
keyword	Required. The keyword you have selected during Shared Short Code sign up process
to	Required. Mobile number in US format and one recipient per request. Ex: to=16365553226
text	Required. Body of the text message

Example

curl "https://rest.nexmo.com/sc/us/marketing/json?api_key={api_key}&api_secret={api_secret}&keyword=NEXMO&to=16365553226&text=Hello"

The response is similar to SMS and you can also get Delivery Receipt.

Keyword Campaign Subscription Management

For the keyword shared short code, we forward subscribe and unsubscribe requests to your account level callback URL. We do manage the campaign subscription list on your behalf, but you can also listen to the incoming subscription requests and manage this mailing list accordingly on your side. Any outbound SMS sent to a recipient opted-out or not yet opted-in will be dropped.

An example of subscribe request:

msisdn=15555554715&to=62687&messageId=020000004165D987&text=discount&type=text&keyword=discount&message-timestamp=2014-10-13+18%3A12%3A00

and unsubscribe request:

msisdn=15551124352&to=62687&messageId=0300000050A775C8&text=Stop&type=text&keyword=keyword&message-timestamp=2014-09-02+15%3A27%3A15

Additionally, you can use the following API to see a list of numbers and their current subscription status.

https://rest.nexmo.com/sc/us/marketing/opt-in/query/json?api_key={api_key}&api_secret={api_secret}&keyword=cupcake

to get a response such as one of the following...

{"opt-in-count":"1","opt-in-list":[{"msisdn":"14449301529","opt-in":"true","opt-in-date":"2014-08-21 17:26:43","opt-out":"false"}]}

{"opt-in-count":"1","opt-in-list":[{"msisdn":"14449301529","opt-in":"false","opt-in-date":"2014-08-21 17:26:43","opt-out":"true","opt-out-date":"2014-08-21 17:27:17"}]}

Once a user unsubscribes from a campaign, the user can text in your keyword to re-subscribe the campaign.