Create a Draft Bulletin

You are here: Communications Cloud API v1 > Resources > Bulletins > Create a Draft Bulletin

Create a Draft Bulletin

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

Your ACCOUNT_CODE can be found via the administrative interface.

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>

Bulletin Content

Specify the content for your bulletin in the <header>, <footer>, and <body> elements. You can specify HTML formatting by using CDATA blocks. Text inside a CDATA section is not parsed, and this allows you to include characters necessary for HTML, like "<" and ">" without generating an XML error.

If you do not include these elements in the payload, the content will come from whatever template is used. For bulletins sent for one topic, that's the topic bulletin template. For bulletins sent for more than one topic or for a category, it's the general bulletin template. Both templates are configured in the administrative interface. Learn more about Bulletin Templates.

Attachments

If you want to attach a file to the bulletin, your input must be a multipart form. If you use XML for your input, you must create the bulletin using this method first, and then add an attachment to it using a multipart form with the Add a Bulletin Attachment method. See the first input example for Create and Send a Bulletin to get an idea of how to use a multipart form for this call.

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.

Set the [deliver] attribute to true. This attribute is optional and defaults to false (meaning the attachments are included as links to hosted files).
Set the global [bulletin_file_deliver] attribute to true. This attribute is optional and when set, it overrides any [deliver] attribute on individual attachments.

Elements

Click 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

If you enter any invalid topic or category codes, these are discarded. If you have multiple topics or categories entered for this bulletin, only the valid ones will be applied. If no valid codes are provided in the payload, then the API will return an error.

Reference bulletin error codes

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

Open topic with navigation