govDelivery

App · 25 actions

Keep residents informed through govDelivery: manage topics and subscribers, draft, test, schedule and send bulletins, send targeted emails and texts and follow their delivery.

Actions

ActionWhat it does
Create draft bulletinSave a bulletin as a draft for staff to review and send in govDelivery.
Create topicCreate a topic people can subscribe to, such as a new project or board.
Delete draft bulletinDelete a draft bulletin.
Delete subscriberDelete a subscriber and all their subscriptions, such as when someone asks to be removed.
Delete topicDelete a topic.
Find subscriberLook a subscriber up by email address or phone number: whether they exist, and how often they get bulletins.
Get bulletinGet a draft or sent bulletin: its content, topics, who it goes to and how many subscribers, when it was or will be sent, and who made it.
Get targeted messageGet a targeted email or text message: its status and how many recipients it reached, failed or is still sending to.
Get targeted message statisticsCount the recipients of targeted emails or text messages over a period by delivery status: delivered, failed, blocked and so on.
Get topicGet one topic with how many people subscribe to it.
List categoriesList the categories that group the account's topics.
List draft bulletinsList bulletins waiting as drafts (scheduled ones too), newest first, 25 at a time.
List message recipientsList a targeted message's recipients with each one's delivery status and any error, 50 at a time.
List sent bulletinsList bulletins the account has sent, newest first, 25 at a time.
List subscriber's topicsList the topics a subscriber gets, by their email address or phone number.
List topicsList the account's topics people can subscribe to, with each one's code, name and visibility.
Schedule bulletinSchedule a draft bulletin to go out at its send time (set with 'Send at' when it was created).
Send bulletinCreate a bulletin and send it now to everyone subscribed to the topics or categories chosen.
Send draft bulletinSend a draft bulletin now to everyone subscribed to its topics.
Send targeted emailSend an email to the people named, such as a permit applicant (needs govDelivery Targeted Messaging).
Send targeted text messageSend a text message to the phone numbers given (needs govDelivery Targeted Messaging).
Send test of bulletinEmail a test of a draft bulletin to the addresses given (and to the connected administrator), not to subscribers.
Subscribe to topicsSubscribe someone to topics by email address or phone number.
Unschedule bulletinStop a scheduled bulletin from going out.
Unsubscribe from topicsRemove someone from some topics.

Create draft bulletin

Save a bulletin as a draft for staff to review and send in govDelivery. Nothing is sent.

Inputs

SubjectsubjecttextRequired
The email's subject, up to 400 characters.
BodybodytextRequired
The bulletin's content. HTML is kept as formatting.
Topicstopicslist
Who gets it: everyone subscribed to these topics. Give topics, categories or both.
Categoriescategorieslist
Everyone subscribed to these categories gets it too.
Headerheadertext
Text or HTML at the top. Leave empty to use your template's.
Footerfootertext
Text or HTML at the bottom. Leave empty to use your template's.
Text messagesms_bodytext
A text message sent with it to text subscribers, up to 140 characters.
Send atsend_timedate and time
When it should go out if it is scheduled with 'Schedule bulletin'.
Urgenturgenttrue/false
Send at once even to people who chose a daily or weekly digest. No by default.
Track opensopen_trackingtrue/false
Whether to record who opens it. Yes by default.
Track clicksclick_trackingtrue/false
Whether to record who clicks its links. Yes by default.

Outputs

bulletinobject
The draft
bulletin_idtext
The draft's number
Example output
{
  "bulletin": {
    "account_code": "CAPHILA",
    "body": "<p>The agenda for Monday's meeting is posted.</p>",
    "created_at": "2026-11-02T10:17:02-06:00",
    "creator_email": "pat.clerk@example.gov",
    "creator_name": "Pat Clerk",
    "footer": null,
    "from_address_id": "16461",
    "from_email": "cityclerk@public.govdelivery.com",
    "from_name": null,
    "header": null,
    "id": "8274957",
    "public_enabled": true,
    "send_time": null,
    "sent_at": null,
    "sms_body": null,
    "status": "draft",
    "subject": "Council agenda for November 10",
    "to_text": "Subscribers of Council agendas",
    "topic_codes": [
      "CAPHILA_12"
    ],
    "total_subscribers": 1843,
    "urgent": false
  },
  "bulletin_id": "8274957"
}

Create topic

Create a topic people can subscribe to, such as a new project or board.

Inputs

NamenametextRequired
The topic's name, for staff.
Name subscribers seeshort_nametext
The name on the sign-up page and in emails. Defaults to the name.
Codecodetext
A code of your choosing, such as MAIN_ST. Leave empty for govDelivery to make one.
Descriptiondescriptiontext
What subscribers will get, shown on the sign-up page.
Visibilityvisibilitytext
Who can find it on your sign-up page. Listed by default.One of: Listed (Listed: shown on the sign-up page), Unlisted (Unlisted: hidden, but people can sign up from a direct link), Restricted (Restricted: hidden; only staff can add subscribers). Default: Listed.
Text alertswireless_enabledtrue/false
Whether people can get this topic by text message. No by default.

Outputs

topicobject
The new topic
topic_codetext
The new topic's code
Example output
{
  "topic": {
    "code": "CAPHILA_12",
    "description": "Agendas and minutes of City Council meetings",
    "name": "City Council agendas",
    "pagewatch_enabled": false,
    "rss_feed_url": null,
    "short_name": "Council agendas",
    "subscribers_count": 1843,
    "uri": "/api/account/CAPHILA/topics/CAPHILA_12",
    "visibility": "Listed",
    "watched_pages": [],
    "wireless_enabled": true
  },
  "topic_code": "CAPHILA_12"
}

Delete draft bulletin

Delete a draft bulletin. A scheduled one must be unscheduled first; a sent one can't be deleted.

Inputs

Bulletin numberbulletin_idtextRequired
The bulletin's number, from 'List draft bulletins' or an earlier step.

Outputs

bulletin_idtext
The bulletin's number
deletedtrue/false
True once deleted
Example output
{
  "bulletin_id": "8274957",
  "deleted": true
}

Delete subscriber

Delete a subscriber and all their subscriptions, such as when someone asks to be removed. There is no undo.

Inputs

Email addressemailtext
The subscriber's email address. Give this or a phone number.
Phone numberphonetext
The subscriber's mobile number, for text alerts. Give this or an email address.
Country codecountry_codetext
The phone's country code, such as 1 for the US. Defaults to 1.
Tell the subscribernotifytrue/false
Whether govDelivery emails the subscriber about the change. No by default.

Outputs

deletedtrue/false
True once deleted
subscribertext
Their email address or phone
subscriber_idtext
govDelivery's id for them
Example output
{
  "deleted": true,
  "subscriber": "resident@example.com",
  "subscriber_id": "cmVzaWRlbnRAZXhhbXBsZS5jb20="
}

Delete topic

Delete a topic. Its subscribers stop getting it. There is no undo.

Inputs

Topictopic_codetextRequired
The topic. Pick one, or give its code from an earlier step.

Outputs

deletedtrue/false
True once deleted
topic_codetext
The deleted topic's code
Example output
{
  "deleted": true,
  "topic_code": "CAPHILA_12"
}

Find subscriber

Look a subscriber up by email address or phone number: whether they exist, and how often they get bulletins.

Inputs

Email addressemailtext
The subscriber's email address. Give this or a phone number.
Phone numberphonetext
The subscriber's mobile number, for text alerts. Give this or an email address.
Country codecountry_codetext
The phone's country code, such as 1 for the US. Defaults to 1.

Outputs

foundtrue/false
Whether they are a subscriber
subscriberobject
The subscriber, or null
subscriber_idtext
govDelivery's id for them
Example output
{
  "found": true,
  "subscriber": {
    "country_code": null,
    "created_at": null,
    "digest_for": 0,
    "email": "resident@example.com",
    "frequency": "Immediately",
    "id": 10020,
    "phone": null,
    "subscriber_id": "cmVzaWRlbnRAZXhhbXBsZS5jb20="
  },
  "subscriber_id": "cmVzaWRlbnRAZXhhbXBsZS5jb20="
}

Get bulletin

Get a draft or sent bulletin: its content, topics, who it goes to and how many subscribers, when it was or will be sent, and who made it.

Inputs

Bulletin numberbulletin_idtextRequired
The bulletin's number, from 'List draft bulletins' or an earlier step.

Outputs

bulletinobject
The bulletin
Example output
{
  "bulletin": {
    "account_code": "CAPHILA",
    "body": "<p>The agenda for Monday's meeting is posted.</p>",
    "created_at": "2026-11-02T10:17:02-06:00",
    "creator_email": "pat.clerk@example.gov",
    "creator_name": "Pat Clerk",
    "footer": null,
    "from_address_id": "16461",
    "from_email": "cityclerk@public.govdelivery.com",
    "from_name": null,
    "header": null,
    "id": "8274957",
    "public_enabled": true,
    "send_time": null,
    "sent_at": null,
    "sms_body": null,
    "status": "draft",
    "subject": "Council agenda for November 10",
    "to_text": "Subscribers of Council agendas",
    "topic_codes": [
      "CAPHILA_12"
    ],
    "total_subscribers": 1843,
    "urgent": false
  }
}

Get targeted message

Get a targeted email or text message: its status and how many recipients it reached, failed or is still sending to.

Inputs

Message numbermessage_idtextRequired
The message's number, from 'Send targeted email' or 'Send targeted text message'.
Kind of messagechanneltext
Email or text message. Email by default.One of: email, sms (Text message (SMS)). Default: email.

Outputs

messageobject
The message
Example output
{
  "message": {
    "body": "Your permit BP-2026-0142 is ready to collect.",
    "channel": "email",
    "completed_at": "2026-11-02T12:54:51Z",
    "created_at": "2026-11-02T12:54:46Z",
    "from_email": "permits@messages.example.gov",
    "from_name": "Permit desk",
    "id": "10040",
    "message_type_code": null,
    "recipient_counts": {
      "blacklisted": 0,
      "canceled": 0,
      "failed": 0,
      "inconclusive": null,
      "new": 0,
      "sending": 0,
      "sent": 2,
      "total": 2
    },
    "reply_to": "permits@messages.example.gov",
    "status": "completed",
    "subject": "Your permit is ready",
    "template": null
  }
}

Get targeted message statistics

Count the recipients of targeted emails or text messages over a period by delivery status: delivered, failed, blocked and so on.

Inputs

Fromstartdate and timeRequired
The start of the period (counted from the hour).
Untilenddate and timeRequired
The end of the period (counted to the hour).
Kind of messagechanneltext
Email or text message. Email by default.One of: email, sms (Text message (SMS)). Default: email.

Outputs

channeltext
email or sms
endtext
The period's end (UTC)
recipientsobject
Recipients in each state
starttext
The period's start (UTC)
totalnumber
How many
Example output
{
  "channel": "email",
  "end": "2026-11-02T00:00:00Z",
  "recipients": {
    "blacklisted": 0,
    "canceled": 0,
    "failed": 1,
    "inconclusive": 0,
    "new": 0,
    "sending": 0,
    "sent": 50,
    "total": 2
  },
  "start": "2026-11-01T00:00:00Z",
  "total": 51
}

Get topic

Get one topic with how many people subscribe to it.

Inputs

Topictopic_codetextRequired
The topic. Pick one, or give its code from an earlier step.

Outputs

topicobject
The topic
Example output
{
  "topic": {
    "code": "CAPHILA_12",
    "description": "Agendas and minutes of City Council meetings",
    "name": "City Council agendas",
    "pagewatch_enabled": false,
    "rss_feed_url": null,
    "short_name": "Council agendas",
    "subscribers_count": 1843,
    "uri": "/api/account/CAPHILA/topics/CAPHILA_12",
    "visibility": "Listed",
    "watched_pages": [],
    "wireless_enabled": true
  }
}

List categories

List the categories that group the account's topics.

Inputs

None.

Outputs

categorieslist
The categories
countnumber
How many
Example output
{
  "categories": [
    {
      "allow_subscriptions": true,
      "code": "CAPHILA_C3",
      "default_open": true,
      "description": "Council, boards and commissions",
      "name": "City government",
      "page_code": "A",
      "short_name": "City government"
    }
  ],
  "count": 1
}

List draft bulletins

List bulletins waiting as drafts (scheduled ones too), newest first, 25 at a time.

Inputs

Start afterstart_attext
The 'next_start_at' from an earlier page, to get the 25 after it.

Outputs

bulletinslist
The bulletins, newest first
countnumber
How many
next_start_attext
Give this as Start after for the next 25, or empty
Example output
{
  "bulletins": [
    {
      "created_at": "2026-11-02T10:17:02-06:00",
      "creator_email": "pat.clerk@example.gov",
      "creator_name": "Pat Clerk",
      "id": "8274957",
      "landing_page_link": "https://content.govdelivery.com/accounts/CAPHILA/bulletins/7e4a2d",
      "sent_at": null,
      "subject": "Council agenda for November 10",
      "uri": "/api/account/CAPHILA/bulletins/8274957.xml"
    }
  ],
  "count": 1,
  "next_start_at": null
}

List message recipients

List a targeted message's recipients with each one's delivery status and any error, 50 at a time.

Inputs

Message numbermessage_idtextRequired
The message's number, from 'Send targeted email' or 'Send targeted text message'.
Kind of messagechanneltext
Email or text message. Email by default.One of: email, sms (Text message (SMS)). Default: email.
Which recipientsstatustext
Everyone, or only those it was delivered to or failed for. Everyone by default.One of: all (Everyone), sent (Delivered), failed. Default: all.
Pagepagenumber
The 'next_page' from an earlier run, for the next 50.At least 1.

Outputs

countnumber
How many
message_idtext
The message's number
next_pagenumber
The next page, or null
readytrue/false
False while govDelivery is still building the list
recipientslist
The recipients
Example output
{
  "count": 1,
  "message_id": "10040",
  "next_page": null,
  "ready": true,
  "recipients": [
    {
      "channel": "email",
      "completed_at": "2026-11-02T12:55:02Z",
      "created_at": "2026-11-02T12:54:46Z",
      "email": "resident@example.com",
      "error_message": null,
      "formatted_phone": null,
      "id": "364897",
      "message_id": "10040",
      "phone": null,
      "sent_at": null,
      "status": "sent"
    }
  ]
}

List sent bulletins

List bulletins the account has sent, newest first, 25 at a time.

Inputs

Start afterstart_attext
The 'next_start_at' from an earlier page, to get the 25 after it.

Outputs

bulletinslist
The bulletins, newest first
countnumber
How many
next_start_attext
Give this as Start after for the next 25, or empty
Example output
{
  "bulletins": [
    {
      "created_at": null,
      "creator_email": null,
      "creator_name": null,
      "id": "8274957",
      "landing_page_link": "https://content.govdelivery.com/accounts/CAPHILA/bulletins/7e4a2d",
      "sent_at": "2026-11-02",
      "subject": "Council agenda for November 10",
      "uri": "/api/account/CAPHILA/bulletins/8274957.xml"
    }
  ],
  "count": 1,
  "next_start_at": null
}

List subscriber's topics

List the topics a subscriber gets, by their email address or phone number.

Inputs

Email addressemailtext
The subscriber's email address. Give this or a phone number.
Phone numberphonetext
The subscriber's mobile number, for text alerts. Give this or an email address.
Country codecountry_codetext
The phone's country code, such as 1 for the US. Defaults to 1.

Outputs

countnumber
How many
subscribertext
Their email address or phone
topic_codeslist
Their topics' codes
topicslist
Their topics
Example output
{
  "count": 1,
  "subscriber": "resident@example.com",
  "topic_codes": [
    "CAPHILA_12"
  ],
  "topics": [
    {
      "code": "CAPHILA_12",
      "name": "City Council agendas",
      "short_name": "Council agendas",
      "uri": "/api/account/CAPHILA/topics/CAPHILA_12"
    }
  ]
}

List topics

List the account's topics people can subscribe to, with each one's code, name and visibility.

Inputs

None.

Outputs

countnumber
How many
topicslist
The topics
Example output
{
  "count": 1,
  "topics": [
    {
      "code": "CAPHILA_12",
      "description": "Agendas and minutes of City Council meetings",
      "name": "City Council agendas",
      "short_name": "Council agendas",
      "uri": "/api/account/CAPHILA/topics/CAPHILA_12",
      "visibility": "Listed",
      "wireless_enabled": true
    }
  ]
}

Schedule bulletin

Schedule a draft bulletin to go out at its send time (set with 'Send at' when it was created).

Inputs

Bulletin numberbulletin_idtextRequired
The bulletin's number, from 'List draft bulletins' or an earlier step.

Outputs

bulletin_idtext
The bulletin's number
scheduledtrue/false
True once scheduled
send_timetext
When it will go out
Example output
{
  "bulletin_id": "8274957",
  "scheduled": true,
  "send_time": "2026-11-10T08:00:00-06:00"
}

Send bulletin

Create a bulletin and send it now to everyone subscribed to the topics or categories chosen. It can't be recalled.

Inputs

SubjectsubjecttextRequired
The email's subject, up to 400 characters.
BodybodytextRequired
The bulletin's content. HTML is kept as formatting.
Topicstopicslist
Who gets it: everyone subscribed to these topics. Give topics, categories or both.
Categoriescategorieslist
Everyone subscribed to these categories gets it too.
Headerheadertext
Text or HTML at the top. Leave empty to use your template's.
Footerfootertext
Text or HTML at the bottom. Leave empty to use your template's.
Text messagesms_bodytext
A text message sent with it to text subscribers, up to 140 characters.
Urgenturgenttrue/false
Send at once even to people who chose a daily or weekly digest. No by default.
Track opensopen_trackingtrue/false
Whether to record who opens it. Yes by default.
Track clicksclick_trackingtrue/false
Whether to record who clicks its links. Yes by default.

Outputs

bulletin_idtext
The bulletin's number
total_subscribersnumber
How many subscribers it went to
uritext
The bulletin's address in the API
Example output
{
  "bulletin_id": "8274958",
  "total_subscribers": 1843,
  "uri": "/api/account/CAPHILA/bulletins/8274958.xml"
}

Send draft bulletin

Send a draft bulletin now to everyone subscribed to its topics. It can't be recalled.

Inputs

Bulletin numberbulletin_idtextRequired
The bulletin's number, from 'List draft bulletins' or an earlier step.

Outputs

bulletin_idtext
The bulletin's number
total_subscribersnumber
How many subscribers it went to
uritext
The bulletin's address in the API
Example output
{
  "bulletin_id": "8274957",
  "total_subscribers": 1843,
  "uri": "/api/account/CAPHILA/bulletins/8274957.xml"
}

Send targeted email

Send an email to the people named, such as a permit applicant (needs govDelivery Targeted Messaging).

Inputs

TorecipientslistRequired
The email addresses to send it to; each gets their own copy.
Subjectsubjecttext
The subject. Needed unless a template gives one.
Bodybodytext
The email. HTML is kept as formatting. Needed unless a template gives one; [[name]] fills in a value from Fill-ins.
Templatetemplatetext
A TMS email template to start from.
From addressfrom_emailtext
Who it comes from. Leave empty for the account's default.
From namefrom_nametext
The sender's name people see.
Fill-insmacrosobject
Values for [[name]] placeholders in the subject and body, such as permit_number.
Track opensopen_trackingtrue/false
Whether to record who opens it. Yes unless the template says otherwise.
Track clicksclick_trackingtrue/false
Whether to record who clicks its links. Yes unless the template says otherwise.

Outputs

messageobject
The message
message_idtext
The message's number
recipientslist
Who it was sent to
Example output
{
  "message": {
    "body": "Your permit BP-2026-0142 is ready to collect.",
    "channel": "email",
    "completed_at": "2026-11-02T12:54:51Z",
    "created_at": "2026-11-02T12:54:46Z",
    "from_email": "permits@messages.example.gov",
    "from_name": "Permit desk",
    "id": "10040",
    "message_type_code": null,
    "recipient_counts": {
      "blacklisted": 0,
      "canceled": 0,
      "failed": 0,
      "inconclusive": null,
      "new": 0,
      "sending": 0,
      "sent": 2,
      "total": 2
    },
    "reply_to": "permits@messages.example.gov",
    "status": "completed",
    "subject": "Your permit is ready",
    "template": null
  },
  "message_id": "10040",
  "recipients": [
    "resident@example.com"
  ]
}

Send targeted text message

Send a text message to the phone numbers given (needs govDelivery Targeted Messaging).

Inputs

TorecipientslistRequired
The mobile numbers to send it to, such as 651 555 1000.
Messagebodytext
The text, up to 160 characters. Needed unless a template gives it.
Templatetemplatetext
A TMS text message template to use.

Outputs

messageobject
The message
message_idtext
The message's number
recipientslist
Who it was sent to
Example output
{
  "message": {
    "body": "Your permit is ready to collect.",
    "channel": "sms",
    "completed_at": "2026-11-02T12:54:51Z",
    "created_at": "2026-11-02T12:54:46Z",
    "from_email": null,
    "from_name": null,
    "id": "165532",
    "message_type_code": null,
    "recipient_counts": {
      "blacklisted": 0,
      "canceled": 0,
      "failed": 0,
      "inconclusive": null,
      "new": 0,
      "sending": 0,
      "sent": 2,
      "total": 2
    },
    "reply_to": null,
    "status": "completed",
    "subject": null,
    "template": null
  },
  "message_id": "165532",
  "recipients": [
    "6515551000"
  ]
}

Send test of bulletin

Email a test of a draft bulletin to the addresses given (and to the connected administrator), not to subscribers.

Inputs

Bulletin numberbulletin_idtextRequired
The bulletin's number, from 'List draft bulletins' or an earlier step.
Send the test toemail_addresseslistRequired
Email addresses to get the test.

Outputs

bulletin_idtext
The bulletin's number
sent_tolist
Who the test went to
Example output
{
  "bulletin_id": "8274957",
  "sent_to": [
    "pat.clerk@example.gov"
  ]
}

Subscribe to topics

Subscribe someone to topics by email address or phone number. They are added as a subscriber if they aren't one.

Inputs

TopicstopicslistRequired
The topics. Pick them, or give their codes from an earlier step.
Email addressemailtext
The subscriber's email address. Give this or a phone number.
Phone numberphonetext
The subscriber's mobile number, for text alerts. Give this or an email address.
Country codecountry_codetext
The phone's country code, such as 1 for the US. Defaults to 1.
Tell the subscribernotifytrue/false
Whether govDelivery emails the subscriber about the change. No by default.

Outputs

subscribertext
Their email address or phone
subscriber_idtext
govDelivery's id for the subscriber
topics_addedlist
The topics' codes
Example output
{
  "subscriber": "resident@example.com",
  "subscriber_id": "cmVzaWRlbnRAZXhhbXBsZS5jb20=",
  "topics_added": [
    "CAPHILA_12"
  ]
}

Unschedule bulletin

Stop a scheduled bulletin from going out. It becomes a draft again.

Inputs

Bulletin numberbulletin_idtextRequired
The bulletin's number, from 'List draft bulletins' or an earlier step.

Outputs

bulletin_idtext
The bulletin's number
scheduledtrue/false
False once unscheduled
Example output
{
  "bulletin_id": "8274957",
  "scheduled": false
}

Unsubscribe from topics

Remove someone from some topics. Their other topics stay as they are.

Inputs

TopicstopicslistRequired
The topics. Pick them, or give their codes from an earlier step.
Email addressemailtext
The subscriber's email address. Give this or a phone number.
Phone numberphonetext
The subscriber's mobile number, for text alerts. Give this or an email address.
Country codecountry_codetext
The phone's country code, such as 1 for the US. Defaults to 1.
Tell the subscribernotifytrue/false
Whether govDelivery emails the subscriber about the change. No by default.

Outputs

subscribertext
Their email address or phone
subscriber_idtext
govDelivery's id for the subscriber
topics_removedlist
The topics' codes
Example output
{
  "subscriber": "resident@example.com",
  "subscriber_id": "cmVzaWRlbnRAZXhhbXBsZS5jb20=",
  "topics_removed": [
    "CAPHILA_12"
  ]
}

On this page