Campaign Subscription Management

Messaging activities fall under the regulatory guidelines of several groups, depending on the nation in which you send the messages. For more information see Pre approved US Short Codes compliance requirements 

You use the The opt-in API to:

SMS Workflow

  1. Listen to the incoming requests and manage your recipient mailing list accordingly.
  2. Send a request.
  3. Check the response.

Unsubscribe to your campaign

Unsubscribe requests for Event Based Alerts are forwarded to the webhook endpoint you set in Dashboard  .

To handle unsubscribe requests:

  1. Listen to the incoming unsubscribe requests and manage your recipient mailing list accordingly. Once a recipient number has unsubscribed from your campaign, any outbound SMS to that number will be blocked.

  2. Send a request and see the list of phone numbers that are unsubscribed from your campaign:

    var https = require('https');
    
    var data = JSON.stringify({
     api_key: 'API_KEY',
     api_secret: 'API_SECRET'
    });
    
    var options = {
     host: 'rest.nexmo.com',
     path: 'sc/us/alert/opt-in/query/json',
     port: 443,
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Content-Length': Buffer.byteLength(data)
     }
    };
    
    var req = https.request(options);
    
    req.write(data);
    req.end();
    
    var responseData = '';
    req.on('response', function(res){
     res.on('data', function(chunk){
       responseData += chunk;
     });
    
     res.on('end', function(){
       console.log(JSON.parse(responseData));
     });
    });
    
    <?php
    $url = 'https://rest.nexmo.com/sc/us/alert/opt-in/query/json?' . http_build_query([
            'api_key' => 'API_KEY',
            'api_secret' => 'API_SECRET'
        ]);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    
    import urllib
    
    params = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET'
    }
    
    url = 'https://rest.nexmo.com/sc/us/alert/opt-in/query/json?' + urllib.urlencode(params)
    
    response = urllib.urlopen(url)
    print response.read()
    
    require "net/http"
    require "uri"
    
    uri = URI.parse("https://rest.nexmo.com/sc/us/alert/opt-in/query/json")
    params = {
        'api_key' => 'API_KEY',
        'api_secret' => 'API_SECRET'
    }
    
    response = Net::HTTP.post_form(uri, params)
    
    puts response.body
    
  3. Check the response:

    //Decode the json object you retrieved when you ran the request.
    
    var decodedResponse = JSON.parse(responseData);
    
    console.log('You sent ' + decodedResponse['message-count'] + ' messages.\n');
    
    decodedResponse['messages'].forEach(function(message) {
        if (message['status'] === "0") {
          console.log('Success ' + decodedResponse['message-id']);
        }
        else {
          console.log('Error ' + decodedResponse['status']  + ' ' +  decodedResponse['error-text']);
        }
    });
    
    <?php
    //Decode the json object you retrieved when you ran the request.
    $decoded_response = json_decode($response, true);
    
    error_log('You sent ' . $decoded_response['message-count'] . ' messages.');
    
    foreach ( $decoded_response['messages'] as $message ) {
        if ($message['status'] == 0) {
            error_log("Success " . $message['message-id']);
        } else {
            error_log("Error {$message['status']} {$message['error-text']}");
        }
    }
    
    import json
    
    #Using the response object from the request
    
    if response.code == 200 :
        data = response.read()
        #Decode JSON response from UTF-8
        decoded_response = json.loads(data.decode('utf-8'))
        # Check if your messages are succesful
        messages = decoded_response["messages"]
        for message in messages:
            if message["status"] == "0":
                print "success"
    else :
        #Check the errors
        print "unexpected http {code} response from nexmo api". response.code
    
    require 'json'
    
    #Decode the json object from the response object you retrieved from the request.
    if response.kind_of? Net::HTTPOK
      decoded_response = JSON.parse(response.body )
    
      messagecount = decoded_response["message-count"]
    
      decoded_response["messages"].each do |message|
        if message["status"] == "0"
            p "message " + message["message-id"] + " sent successfully.\n"
          else
            p "message has error " + message["status"]  + " " + message["error-text"]
        end
      end
    else
      puts response.code + " error sending message"
    end
    

Resubscribe to your campaign

Resubscribe requests for Event Based Alerts are handled through your Website.

To handle resubscribe requests:

  1. On your website, listen to the incoming resubscribe requests.

  2. Send a request to opt-in the phone number again:

    var https = require('https');
    
    var data = JSON.stringify({
     api_key: 'API_KEY',
     api_secret: 'API_SECRET',
     msisdn: 441632960960
    });
    
    var options = {
     host: 'rest.nexmo.com',
     path: '/sc/us/alert/opt-in/manage/json',
     port: 443,
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Content-Length': Buffer.byteLength(data)
     }
    };
    
    var req = https.request(options);
    
    req.write(data);
    req.end();
    
    var responseData = '';
    req.on('response', function(res){
     res.on('data', function(chunk){
       responseData += chunk;
     });
    
     res.on('end', function(){
       console.log(JSON.parse(responseData));
     });
    });
    
    <?php
    $url = 'https://rest.nexmo.com/sc/us/alert/opt-in/manage/json?' . http_build_query([
            'api_key' => 'API_KEY',
            'api_secret' => 'API_SECRET',
            "msisdn" => 441632960960
        ]);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    
    import urllib
    
    params = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'msisdn': 441632960960
    }
    
    url = 'https://rest.nexmo.com//sc/us/alert/opt-in/manage/json?' + urllib.urlencode(params)
    
    response = urllib.urlopen(url)
    print response.read()
    
    require "net/http"
    require "uri"
    
    uri = URI.parse("https://rest.nexmo.com/sc/us/alert/opt-in/manage/json")
    params = {
        "api_key" => 'API_KEY',
        "api_secret" => 'API_SECRET',
        "msisdn" => 441632960960
    }
    
    response = Net::HTTP.post_form(uri, params)
    
    puts response.body
    
  3. Check the response:

    //Decode the json object you retrieved when you ran the request.
    
    var decodedResponse = JSON.parse(responseData);
    
    console.log('You sent ' + decodedResponse['message-count'] + ' messages.\n');
    
    decodedResponse['messages'].forEach(function(message) {
        if (message['status'] === "0") {
          console.log('Success ' + decodedResponse['message-id']);
        }
        else {
          console.log('Error ' + decodedResponse['status']  + ' ' +  decodedResponse['error-text']);
        }
    });
    
    <?php
    //Decode the json object you retrieved when you ran the request.
    $decoded_response = json_decode($response, true);
    
    error_log('You sent ' . $decoded_response['message-count'] . ' messages.');
    
    foreach ( $decoded_response['messages'] as $message ) {
        if ($message['status'] == 0) {
            error_log("Success " . $message['message-id']);
        } else {
            error_log("Error {$message['status']} {$message['error-text']}");
        }
    }
    
    import json
    
    #Using the response object from the request
    
    if response.code == 200 :
        data = response.read()
        #Decode JSON response from UTF-8
        decoded_response = json.loads(data.decode('utf-8'))
        # Check if your messages are succesful
        messages = decoded_response["messages"]
        for message in messages:
            if message["status"] == "0":
                print "success"
    else :
        #Check the errors
        print "unexpected http {code} response from nexmo api". response.code
    
    require 'json'
    
    #Decode the json object from the response object you retrieved from the request.
    if response.kind_of? Net::HTTPOK
      decoded_response = JSON.parse(response.body )
    
      messagecount = decoded_response["message-count"]
    
      decoded_response["messages"].each do |message|
        if message["status"] == "0"
            p "message " + message["message-id"] + " sent successfully.\n"
          else
            p "message has error " + message["status"]  + " " + message["error-text"]
        end
      end
    else
      puts response.code + " error sending message"
    end