You are here: Communications Cloud API v1 > Common Uses > Automatically Send Content from Your CMS Upon Creation

Automatically Send Content from Your CMS Upon Creation

Communications Cloud offers two bulletin creation tools - standard and advanced. While these tools are easy to use and powerful, some of our clients require the ability to create bulletins without logging into our platform or needing to know the Web Services API credentials. You can use this API to automatically send content from an external system upon content creation. For example, if your organization has a Drupal site and you want to send out every post as an email update, you can use the API to send the content as a bulletin upon publishing each post. You might do this for court records, a public policy database, or an alert system. Using the API allows you to set up custom processes for generating and sending bulletins. You can even specify whether bulletins should be sent directly or created and held for approval from your Communications department.

There are a number of approaches you can take, based on what you want to accomplish, but one approach might be:

  1. Create the trigger for a bulletin
  2. Send content to the API
  3. Connect this trigger to the API
1. Create the trigger for a bulletin

Build in a way for your content creators to choose whether to send a bulletin with the content they are publishing. This might take the form of a Send Bulletin? check box on the New Post form or page in your CMS. If you're using the Create and Send method to automatically send the bulletin upon post publication, make sure that is explicitly stated in the check box label.

2. Send content to the API

Pass content from the post in your CMS to the API as the <subject>, <header>, and <body> of the bulletin.

3. Connect this trigger to the API

Decide if you want a bulletin sent automatically when a content creator publishes something in your CMS. The other option is creating a bulletin and holding it in draft form so an administrator in Communications Cloud can review it and send it.

ClosedTo create and send automatically
Operation

Send a POST to /api/account/ACCOUNT_CODE/bulletins/send_now

Note: Your ACCOUNT_CODE can be found via the administrative interface.

Example Input

Note: The input examples provided here are for informational purposes only. You would not directly generate these multipart bodies in your code; you would use a library such as HTTP/Request2 for PHP. The code examples below show how to use a library to generate the POST body for attachments, which generates the multipart POST body for you.

If you're sending an attachment with the bulletin, your input should look like:  

POST /api/account/<ACCOUNT_CODE>/bulletins/send_now HTTP/1.1
User-Agent: Jakarta Commons-HttpClient/4.1
Host: localhost
Content-Length: 498
Content-Type: multipart/form-data; boundary=--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a-

--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a-
Content-Disposition: form-data; name="bulletin[body]"

<p>Bulletin body</p>
--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a-
Content-Disposition: form-data; name="bulletin[subject]"

Web service bulletin
--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a-
Content-Disposition: form-data; name="bulletin[topics][][code]"

TOPIC1
--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a-
Content-Disposition: form-data; name="bulletin[bulletin_files][][attachment]"; filename="attachment1.txt"
Content-Type: text/plain

Content of file attachment one

--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a-
Content-Disposition: form-data; name="bulletin[bulletin_files][][deliver]"

true
--0dLT852O3qW0hFO_0x_1jI9oeT8Y3q_a---

If you're using XML without an attachment, your input should look like: 

<bulletin>
   <header>ENTER HEADER</header>
   <from_address_id>####</from_address_id>
   <subject>ENTER SUBJECT</subject>
   <body><![CDATA[<p>ENTER BODY in <b>cdata tag</b></p>]]></body>
   <footer>ENTER FOOTER</footer>
   <sms_body nil='true'></sms_body>
   <publish_rss type='boolean'>false</publish_rss>
   <open_tracking type='boolean'>true</open_tracking>
   <click_tracking type='boolean'>true</click_tracking>
   <share_content_enabled type='boolean'>true</share_content_enabled>
   <topics type='array'>
     <topic>
       <code>####</code>
     </topic>
     <topic>
       <code>####</code>
     </topic>
   </topics>
   <categories type='array' />
 </bulletin>
Delivery

When using the multipart input form, attachments are included as links to files hosted on our servers by default. If you'd like actually include the attachment as a file with the bulletin, you can use the following attributes.

Elements
ClosedClick to view
<header> This is text or a linked image displayed at the top of the email bulletin that is created. Note: If you are using an image (via href link) please ensure that the image is no wider than 700px. If the header value is left blank or the node is omitted from the XML payload then the system will use the header specified in the bulletin template that has been set via the administrative interface.
<from_address_id> This is an optional field that is utilized only when there are multiple from addresses specified for the client account. If you do not know your from address id, you can contact the GovDelivery help desk at support@granicus.com or call 800-314-0147 (UK residents: 0800-032-7764) to get it. The account used for authentication must have the Modify Bulletin From Address permission or otherwise this element will be ignored.
<subject> This is the subject of the email bulletin. Note: When creating a subject line please refrain from entering special characters such as "!" or "quotes" as this may increase chances of the email being flagged as spam. The <subject> has a 400 character limit and is a required node but can be left blank.
<body> This is the body of the email bulletin. You can use CDATA blocks to specify HTML formatting or use plain text. If this node is omitted from the XML payload, then this element will come from whatever bulletin template has been set up in the administrative interface.
<footer> This is text or a linked image that is displayed on the bottom of the email bulletin. The account used for authentication must have the Modify Bulletin Footer permission or otherwise this element will be ignored.
<sms_body> This field allows you to specify a SMS message via this API operation. This field will only have effect if SMS messaging is turned on for the client's account. There is a 140-character limit on this field. If you do not want to include an SMS body, include the nil="true" attribute.
<publish_rss> This field requires the type='boolean' attribute. Set it to true to publish the bulletin to the account send-activity RSS feed, if the feature is turned on for the account.
<open_tracking> This field requires the type='boolean' attribute. Set it to true to track whether the recipients open this email bulletin. The report created when this field is used is available via the administrative interface.
<click_tracking> This field requires the type='boolean' attribute. Set it to true to track if each recipient clicks any links within this email bulletin. The report created when this field is used is available via the administrative interface.
<send_time> Include this element if you plan to schedule the bulletin for sending.
<urgent> This optional field requires the type='boolean' attribute. Set it to true to override a subscriber's digest (email frequency) settings and send the bulletin immediately. If this field is used in tandem with <send_time>, the bulletin will be sent when scheduled, ignoring the subscriber's digest settings.
<share_content_enabled> If social sharing is enabled for the account, then this field allows you to share the bulletin to Facebook or Twitter.
<topics>

Topics are used to organize your bulletins. The public can subscribe to updates about a topic. When they do so, they are added to the topic's mailing list. When a bulletin is tagged with a topic, all recipients for the topic receive the bulletin. If you enter multiple topics in this element and a recipient has signed up for more than one topic listed here, they will receive only one copy of the email bulletin.

This field must include the type="array" attribute. This field contains nested <topic> elements.

<topic> Include this element for every topic you want to assign the bulletin. This element contains a nested <code> element.
<code> This is the code for the topic or topics that the email bulletin will be sent to.
<categories> Categories are used to organize your topics and bulletins. You can configure a category to allow the public to subscribe to updates for the category. When a bulletin is tagged with a category, all subscribers for that category receive the bulletin. Enter an array of categories (or simply choose one) that you will send this bulletin for. If you enter multiple categories in this element and a recipient has signed up for more than one category listed here, they will receive only one copy of the email bulletin. Enter their category codes here in the same format as topic codes (see input example above).
Example Output
<?xml version="1.0" encoding="UTF-8"?>
  <bulletin>
    <to-param>BULLETIN_ID</to-param>
    <bulletin-uri>/api/account/ACCOUNT_CODE/bulletins/BULLETIN_ID.xml</bulletin-uri>
    <link rel="self" href="/api/account/ACCOUNT_CODE/bulletins/BULLETIN_ID" />
    <total-subscribers>##</total-subscribers>
  </bulletin>
Troubleshooting
ClosedReference bulletin error codes
ClosedGD-12002
Error message Bulletin not found.
HTTP Code 402
Cause The bulletin specified is either deleted or invalid.
ClosedGD-12004
Error message Invalid bulletin.
HTTP Code 422
Cause The input contained invalid data for creating or updating a bulletin. Some possible causes are not specifying a subject, body, or topic/categories.
ClosedGD-12005
Error message Invalid Email
HTTP Code 422
Cause The administrator is trying to send a bulletin with an invalid email address.
ClosedGD-12007
Error message Invalid send time.
HTTP Code 422
Cause The scheduled bulletin has an invalid Send time (for example, the Sent time is before the current time).
ClosedGD-12008
Error message Bulletin is at invalid state 'sent'; expected state is 'draft'.
HTTP Code 422
Cause The bulletin cannot be scheduled when in sent mode.
ClosedGD-12009
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to create a bulletin does not have the Create Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12010
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to update a bulletin does not have the Update Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12011
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to send a bulletin does not have the Send Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12012
Error message Bulletin file attachment settings are not enabled for the account.
HTTP Code 422
Cause The administrator is trying to create, create and send, or update bulletin with attachments, but the account's attachments settings conflict. Both the links and attachment settings might be disabled for the account. Contact support@granicus.com for assistance with account settings.
ClosedGD-12013
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to read a bulletin does not have the Read Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12014
Error message Invalid bulletin file.
HTTP Code 422
Cause Trying to modify or create a bulletin attachment with invalid parameters. Check the returned error messages to determine what was invalid.
ClosedGD-12015
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to list bulletins does not have the List Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12016
Error message Invalid input parameter, start_at will only accept numbers
HTTP Code 400
Cause The administrator trying to list bulletins with invalid start_at parameter.
ClosedTo hold in draft form

Send a POST to /api/account/ACCOUNT_CODE/bulletins.xml

Example Input
<bulletin>
    <header>ENTER HEADER</header>
    <from_address_id>####</from_address_id>
    <subject>ENTER SUBJECT</subject>
    <body><![CDATA[<p>ENTER BODY in <b>cdata tag</b></p>]]></body>
    <footer>ENTER FOOTER</footer>
    <sms_body nil='true'></sms_body>
    <publish_rss type='boolean'>false</publish_rss>
    <open_tracking type='boolean'>true</open_tracking>
    <click_tracking type='boolean'>true</click_tracking>
    <share_content_enabled type='boolean'>true</share_content_enabled>
    <topics type='array'>
      <topic>
        <code>####</code>
      </topic>
      <topic>
        <code>####</code>
      </topic>
    </topics>
    <categories type='array' />
  </bulletin>
Elements
ClosedClick to view

All fields are optional, except where marked as required. Do not leave any fields blank. If the field is not required, then you may omit the node from your input.

<header> This is text or a linked image displayed at the top of the email bulletin that is created. Note: If you are using an image (via href link) please ensure that the image is no wider than 700px. If the header value is left blank or the node is omitted from the XML payload then the system will use the header specified in the bulletin template that has been set via the administrative interface.
<from_address_id> This is an optional field that is utilized only when there are multiple from addresses specified for the client account. If you do not know your from address id, you can contact the GovDelivery help desk at support@granicus.com or call 800-314-0147 (UK residents: 0800-032-7764) to get it. The account used for authentication must have the Modify Bulletin From Address permission or otherwise this element will be ignored.
<subject> This is the subject of the email bulletin. Note: When creating a subject line please refrain from entering special characters such as "!" or "quotes" as this may increase chances of the email being flagged as spam. The <subject> has a 400 character limit and is a required node but can be left blank.
<body> This is the body of the email bulletin. You can use CDATA blocks to specify HTML formatting or use plain text. If this node is omitted from the XML payload, then this element will come from whatever bulletin template has been set up in the administrative interface.
<footer> This is text or a linked image that is displayed on the bottom of the email bulletin. The account used for authentication must have the Modify Bulletin Footer permission or otherwise this element will be ignored.
<sms_body> This field allows you to specify a SMS message via this API operation. This field will only have effect if SMS messaging is turned on for the client's account. There is a 140-character limit on this field. If you do not want to include an SMS body, include the nil="true" attribute.
<publish_rss> This field requires the type='boolean' attribute. Set it to true to publish the bulletin to the account send-activity RSS feed, if the feature is turned on for the account.
<open_tracking> This field requires the type='boolean' attribute. Set it to true to track whether the recipients open this email bulletin. The report created when this field is used is available via the administrative interface.
<click_tracking> This field requires the type='boolean' attribute. Set it to true to track if each recipient clicks any links within this email bulletin. The report created when this field is used is available via the administrative interface.
<send_time> Include this element if you plan to schedule the bulletin for sending.
<urgent> This optional field requires the type='boolean' attribute. Set it to true to override a subscriber's digest (email frequency) settings and send the bulletin immediately. If this field is used in tandem with <send_time>, the bulletin will be sent when scheduled, ignoring the subscriber's digest settings.
<share_content_enabled> If social sharing is enabled for the account, then this field allows you to share the bulletin to Facebook or Twitter.
<topics>

Topics are used to organize your bulletins. The public can subscribe to updates about a topic. When they do so, they are added to the topic's mailing list. When a bulletin is tagged with a topic, all recipients for the topic receive the bulletin. If you enter multiple topics in this element and a recipient has signed up for more than one topic listed here, they will receive only one copy of the email bulletin.

This field must include the type="array" attribute. This field contains nested <topic> elements.

<topic> Include this element for every topic you want to assign the bulletin. This element contains a nested <code> element.
<code> This is the code for the topic or topics that the email bulletin will be sent to.
<categories> Categories are used to organize your topics and bulletins. You can configure a category to allow the public to subscribe to updates for the category. When a bulletin is tagged with a category, all subscribers for that category receive the bulletin. Enter an array of categories (or simply choose one) that you will send this bulletin for. If you enter multiple categories in this element and a recipient has signed up for more than one category listed here, they will receive only one copy of the email bulletin. Enter their category codes here in the same format as topic codes (see input example above).
Example Output
<?xml version="1.0" encoding="UTF-8"?>
  <bulletin>
    <to-param>BULLETIN_ID</to-param>
    <link rel="self" href="/api/account/ACCOUNT_CODE/bulletins/BULLETIN_ID" />
    <link rel="send_now" href="/api/account/ACCOUNT_CODE/bulletins/BULLETIN_ID/send_now" />
  </bulletin>
Troubleshooting
ClosedReference bulletin error codes
ClosedGD-12002
Error message Bulletin not found.
HTTP Code 402
Cause The bulletin specified is either deleted or invalid.
ClosedGD-12004
Error message Invalid bulletin.
HTTP Code 422
Cause The input contained invalid data for creating or updating a bulletin. Some possible causes are not specifying a subject, body, or topic/categories.
ClosedGD-12005
Error message Invalid Email
HTTP Code 422
Cause The administrator is trying to send a bulletin with an invalid email address.
ClosedGD-12007
Error message Invalid send time.
HTTP Code 422
Cause The scheduled bulletin has an invalid Send time (for example, the Sent time is before the current time).
ClosedGD-12008
Error message Bulletin is at invalid state 'sent'; expected state is 'draft'.
HTTP Code 422
Cause The bulletin cannot be scheduled when in sent mode.
ClosedGD-12009
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to create a bulletin does not have the Create Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12010
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to update a bulletin does not have the Update Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12011
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to send a bulletin does not have the Send Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12012
Error message Bulletin file attachment settings are not enabled for the account.
HTTP Code 422
Cause The administrator is trying to create, create and send, or update bulletin with attachments, but the account's attachments settings conflict. Both the links and attachment settings might be disabled for the account. Contact support@granicus.com for assistance with account settings.
ClosedGD-12013
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to read a bulletin does not have the Read Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12014
Error message Invalid bulletin file.
HTTP Code 422
Cause Trying to modify or create a bulletin attachment with invalid parameters. Check the returned error messages to determine what was invalid.
ClosedGD-12015
Error message Resource not available.
HTTP Code 403
Cause The administrator trying to list bulletins does not have the List Bulletin permission. Contact support@granicus.com for assistance with permissions.
ClosedGD-12016
Error message Invalid input parameter, start_at will only accept numbers
HTTP Code 400
Cause The administrator trying to list bulletins with invalid start_at parameter.
Related Topics IconRelated Topics

 

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

Open topic with navigation