If you have existing subscribers in an internal database or have an alternative method for collecting subscribers, you can use the API in a batch process to add subscribers and move them into GovDelivery. This is helpful if, for example, you have a group of users stored in a database, such as Oracle, or directory services, like Active Directory, that you'd like to register for email updates.
There are a number of approaches you can take, based on what you want to accomplish, but one approach might be:
This is done in the Communications Cloud administrative interface using a .CSV file.
Set up a nightly process to look for any deleted subscribers in your internal database.
Set up your system to send a call using the delete a subscriber method for any subscribers tracked as deleted in your internal database.
Send a DELETE to /api/account/ACCOUNT_CODE/subscribers/ENCODED_SUBSCRIBER_ID.xml
This operation will cause the system to send a Subscriber Deleted confirmation message to the subscriber. To avoid sending this message, send the DELETE operation using the following endpoint:
/api/account/ACCOUNT_CODE/subscribers/ENCODED_SUBSCRIBER_ID?send_notifications=false.
A successful operation will have a 200 OK response status and an empty response body.
Error message | Resource not available |
HTTP Code | 403 |
Cause | The administrator trying to read a subscriber does not have the Read Subscriber permission. Contact support@granicus.com for assistance with permissions. |
Error message | Subscriber not found. |
HTTP Code | 404 |
Cause | The subscriber specified is either deleted or invalid. |
Error message | Invalid Subscriber |
HTTP Code | 422 |
Cause | Data sent for creating or updating a subscriber is invalid. Possible causes include phone or email address is improperly specified. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to list a subscriber's category subscriptions does not have the Subscriber Category List permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update a subscriber's category subscriptions does not have the Subscriber Category Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to list subscriber responses does not have the Subscriber Response List permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update subscriber responses does not have the Subscriber Response Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to list subscriber topics does not have the Subscriber Topic List permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update subscriber topics does not have the Subscriber Topic Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to create subscribers does not have the Subscriber Create permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update subscribers does not have the Subscriber Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to delete subscribers does not have the Subscriber Delete permission. Contact support@granicus.com for assistance with permissions. |
Error message | Invalid Topic Subscription. |
HTTP Code | 422 |
Cause | The administrator trying to subscribe a subscriber to a topic that doesn't exist or is not available to the current user. |
Error message | Invalid Topic Subscription. |
HTTP Code | 422 |
Cause | The administrator trying to subscribe a subscriber to a restricted topic. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | Trying to subscribe a subscriber to a topic for which the user is not an administrator. |
This is done using the add a subscription method.
Send a POST to /api/account/ACCOUNT_CODE/subscriptions.xml
For an email subscriber, the input should look like:
<subscriber> <email>EMAIL@ADDRESS.COM</email> <send-notifications type='boolean'>false</send-notifications> <topics type='array'> <topic> <code>####</code> </topic> <topic> <code>####</code> </topic> </topics> </subscriber>
For a wireless subscriber, the input should look like:
<subscriber> <phone>###-###-####</phone> <country-code>#</country-code> <send-notifications type='boolean'>false</send-notifications> <topics type='array'> <topic> <code>####</code> </topic> <topic> <code>####</code> </topic> </topics> </subscriber>
<email> | The subscriber's email address. |
<phone> | The subscriber's phone number. |
<country-code> | The subscriber's country code. You can leave this blank to use the default country code set for your account, although we highly recommend setting the code (1 for United States, 44 for United Kingdom). To check the country code for your account, contact support@granicus.com |
<send-notification> | This field requires a value of either True or False and the type="boolean" attribute. Set this field to true send an email notification to the subscriber that their record has been updated. |
<topics> | This field must include the type="array" attribute. You will enter any topic for which you want the subscriber to be subscribed in each nested <topic> field. |
<code> | Enter the code of the topic for which the subscriber will receive updates. This field must be nested in a <topic> field, under the <topics> field. |
<?xml version="1.0" encoding="UTF-8"?> <subscriber> <to-param>ZW1haWxAdGVzdC5nb3ZkZWxpdmVyeS5jb20=</to-param> <link rel="self" href="/api/account/TOR_TEST/subscribers/ZW1haWxAdGVzdC5nb3ZkZWxpdmVyeS5jb20="/> <subscriber-uri>/api/account/ACCOUNT_CODE/subscribers/ZW1haWxAdGVzdC5nb3ZkZWxpdmVyeS5jb20=</subscriber-uri> </subscriber>
<?php /* Replace or create a subscriber's subscriptions */ require_once 'HTTP/Request2.php'; if($argc < 4) { print "Add subscriptions to a subscriber\n"; print "usage: $argv[0] account_code email_address \"topic1,topic2,topic3,...\" username password\n\n"; exit; } $account_code = $argv[1]; $destination = $argv[2]; $topics = $argv[3]; $username = $argv[4]; $password = $argv[5]; // lower case the email first, then base64 encode it $encoded_email = base64_encode(strtolower($email_address)); // split the list of topics $topic_list = split(",", $topics); $url = "https://stage-api.govdelivery.com/api/account/$account_code/subscriptions"; try { $request = new HTTP_Request2 ( $url, HTTP_Request2::METHOD_POST, array ('ssl_verify_peer' => false, 'ssl_verify_host' => false) ); $request -> setAuth($username, $password, HTTP_Request2::AUTH_BASIC); $request_body = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" . " <subscriber>"; if(substr_count($destination, "@") > 0) { $request_body .= " <email>$destination</email>"; } else { $request_body .= " <phone>$destination</phone>"; $request_body .= " <country-code>1</country-code>"; } $request_body .= " <send-notifications type='boolean'>false</send-notifications>"; $request_body .= " <topics type='array'>"; foreach($topic_list as &$topic) { $request_body .= " <topic>"; $request_body .= " <code>$topic</code>"; $request_body .= " </topic>"; } $request_body .= " </topics>"; $request_body .= " </subscriber>"; $request -> setHeader('Content-type: text/xml; charset=utf-8') -> setBody($request_body); print "Connecting with "; print_r($request); print "\n"; $response = $request -> send(); echo "Response status: " . $response -> getStatus() . "\n"; echo "Human-readable reason phrase: " . $response -> getReasonPhrase() . "\n"; echo "Response HTTP version: " . $response -> getVersion() . "\n"; echo "Response object:\n"; print_r($response) . "\n"; if($response->getHeader('content-encoding') == 'gzip') { echo "Gzipped!\n"; $response_body = $response -> decodeGzip($response->getBody()); } else { $response_body = $response -> getBody(); } echo "Response payload\n"; echo $response_body; if($response -> getStatus() != 200) { // log an error print "Got a non-successful return code, please inspect the response body\n"; } } catch(Exception $e) { print "\n"; echo "ERROR " . $e->getMessage() . "\n"; print_r($e) . "\n"; print "Response: \n"; print_r($response) . "\n"; } ?>
Error message | Resource not available |
HTTP Code | 403 |
Cause | The administrator trying to read a subscriber does not have the Read Subscriber permission. Contact support@granicus.com for assistance with permissions. |
Error message | Subscriber not found. |
HTTP Code | 404 |
Cause | The subscriber specified is either deleted or invalid. |
Error message | Invalid Subscriber |
HTTP Code | 422 |
Cause | Data sent for creating or updating a subscriber is invalid. Possible causes include phone or email address is improperly specified. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to list a subscriber's category subscriptions does not have the Subscriber Category List permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update a subscriber's category subscriptions does not have the Subscriber Category Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to list subscriber responses does not have the Subscriber Response List permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update subscriber responses does not have the Subscriber Response Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to list subscriber topics does not have the Subscriber Topic List permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update subscriber topics does not have the Subscriber Topic Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to create subscribers does not have the Subscriber Create permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to update subscribers does not have the Subscriber Update permission. Contact support@granicus.com for assistance with permissions. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | The administrator trying to delete subscribers does not have the Subscriber Delete permission. Contact support@granicus.com for assistance with permissions. |
Error message | Invalid Topic Subscription. |
HTTP Code | 422 |
Cause | The administrator trying to subscribe a subscriber to a topic that doesn't exist or is not available to the current user. |
Error message | Invalid Topic Subscription. |
HTTP Code | 422 |
Cause | The administrator trying to subscribe a subscriber to a restricted topic. |
Error message | Resource not available. |
HTTP Code | 403 |
Cause | Trying to subscribe a subscriber to a topic for which the user is not an administrator. |
Was this page helpful? Can't find what you need? Let us know