You are here: Communications Cloud API v1 > Resources > Topics

Topics

Topics (or subscription topics) are used to organize your information in GovDelivery. When you create a topic, the public can subscribe to updates about that topic. Each topic has a mailing list and all subscribers who have signed up for updates for this topic will receive any sent bulletin tagged with that topic.

Methods
ClosedClick to view
Method Description Required Permissions
Create a Topic

When you POST to the topic resource, you create a new topic. If you enable the topic in your input, it will be available for selection when any authorized administrators create new bulletins.

Note: You cannot assign this topic to any categories using this method. To do so, you must create the topic using this method and then use the Update Topic Categories method.
  • Create Topic
  • Assign Topic Administrator
List all Topics

To see all topics for your account, send a GET to the topics resource. The list returned will include only enabled topics, with high-level details about each. To see additional details about a particular topic, use the Read a Topic method.
  • List Topic
Read a Topic

To see information about a topic, you will need the particular topic's code. This can be found using the List Topics method.

Note: You cannot view the categories assigned for this topic using this method. To do so, you must use the List Topic Categories method.

  • Read Topic
Update a Topic

You can update details about a topic by sending a PUT operation to that specific topic resource. You can use this operation to change a topic's code, however you will need to use the current code in the call. Simply change the code in your input.

Note: You cannot assign this topic to any categories using this method. To do so, you must use the Change Topic Categories method.

  • Update Topic
Delete a Topic

You can delete a topic from your GovDelivery account using this method. Note that any bulletins that have been tagged with this topic remain in your account.

  • Delete Topic
List a Topic's Categories

Categories help you organize your topics and bulletins. A topic can be assigned to one or more category. Use this method to see a list of categories for a particular topic.
  • List Topics
Change a Topic's Categories

Use this call to completely change a topic's list of categories. Keep in mind that this is a bulk operation, which will completely replace the current list. If you simply want to add a new category to this topic, use the List a Topic's Categories method to see the current list and then be sure to include those categories in your call.
  • Update Topic
Elements
ClosedClick to view

Note: Fields with an asterisk (*) are required.

<code> A code is systematically assigned by GovDelivery when a topic is created in the administrative interface. When creating a topic via the API, you choose the code, or leave it blank to have it be system-generated. Any code you choose must be unique (i.e., not used by an existing topic). This code can be changed by an administrator to anything that benefits their organizational purposes.
<name>* Name of the topic. This name is for internal purposes and is not displayed to the public.
<short-name>* A short version of the topic's name. This is the name that subscribers will see and can be modified for organizational purposes.
<description> Description of the topic. This is optional, but recommended. Topic descriptions can be seen by subscribers on your organization's subscription pages, giving them more information about the updates they'll receive. Because this field can be left empty, the nil="true" attribute is required.
<send-by-email-enabled> This is an optional feature that allows the user to send communications via GovDelivery using a third-party email device. Contact Customer Support at GovDelivery if you want this feature enabled. If this feature is not activated, enter a value of False. This field requires the type="boolean" attribute.
<wireless-enabled> This field requires a value of either True or False and the type="boolean" attribute. Set this field to true to enable wireless alerts (sent via SMS/text) for the topic.
<rss-feed-url> The URL for the topic's public RSS feed. This is an account option and must be enabled by GovDelivery prior to use. Contact Customer Support at GovDelivery if you want this feature enabled. Because this field can be left empty, the nil="true" attribute is required.
<rss-feed-title> The title of the topic's public RSS feed. Because this field can be left empty, the nil="true" attribute is required.
<rss-feed-description> A short description of the topic's public RSS feed. Because this field can be left empty, the nil="true" attribute is required.
<pagewatch-enabled> This field requires a value of either True or False and the type="boolean" attribute. Set this to true to enable Page Wage to automatically watch for content updates and notify subscribers of updates
<pagewatch-suspended> This field requires a value of either True or False and the type="boolean" attribute. Set this to true to temporarily suspend Page Watch. This does not remove any previous pagewatch results.
<default-pagewatch-results> Set the number of Page Watch results that are stored in GovDelivery. Note that GovDelivery saves the last (specified number) of changes, non-changes, and errors for each Page Watch URL. This field requires a number value and the type="integer" attribute. If you leave this field blank, GovDelivery save the last 10 Page Watch schedules by default. Because this field can be left empty, the nil="true" attribute is also required.
<pagewatch-autosend> This field requires a value of either True or False and the type="boolean" attribute. Set this to true to enable Page Watch to automatically notify your subscribers via a bulletin when your web pages are updated.
<pagewatch-type>

This field indicates the type of web accessible entity that will be monitored by Page Watch. There are three possible values for this field: 

  • 1: HTML page
  • 2: RSS/Atom feed
  • 3: File

Enter the number corresponding to the correct type. This field requires a number value and the type="integer" attribute. Because this field can be left empty, the nil="true" attribute is also required.
<watch-tagged-content> This field requires a value of either True or False and the type="boolean" attribute. Set this to true to enable GovDelivery to only watch particular sections of a web page by tagging content with this topic. Sections to be watched in a page are indicated by a set of HTML tags. Learn more about Page Watch.
<pages> This field must include the type="array" attribute. You will enter any pages you want to include in Page Watch in each nested <page> field.
<page> You can include multiple <page> fields in your input; one for each page to be monitored for this topic.
<URL> The URL of the web page or RSS feed to be monitored by Page Watch for this topic. These pages or feeds must be publicly accessible (i.e., not behind a firewall), and you must include "http://" in the URL. This field is nested within the <page> element.
<visibility>

This sets the visibility of the topic on the Quick Subscriber page. There are three possible values for this field:

  • Listed: The topic is displayed
  • Unlisted: The topic is not displayed. However, subscribers can sign up for updates by a direct link to the topic that can be placed on your website.
  • Restricted: The topic is not displayed. Subscribers can be added for this topic via API or by a CSV upload in the administrative interface.
<categories>

This field must include the type="array" attribute. You will enter any categories you want to include for this topic in each nested <category> field. Any categories not included this list are removed from the topic's categories list. To delete all categories from a topic, include an empty categories array.
<category>

You can include multiple <category> fields in your input; one for each category to be assigned to this topic. The code for the category will be included in a nested <code> element. Use the List Categories method to find the codes in your account.
Related Topics IconRelated Topics

 

Was this page helpful? Can't find what you need? Let us know

Open topic with navigation