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
| Action | What it does |
|---|---|
| Create draft bulletin | Save a bulletin as a draft for staff to review and send in govDelivery. |
| Create topic | Create a topic people can subscribe to, such as a new project or board. |
| Delete draft bulletin | Delete a draft bulletin. |
| Delete subscriber | Delete a subscriber and all their subscriptions, such as when someone asks to be removed. |
| Delete topic | Delete a topic. |
| Find subscriber | Look a subscriber up by email address or phone number: whether they exist, and how often they get bulletins. |
| 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. |
| Get targeted message | Get a targeted email or text message: its status and how many recipients it reached, failed or is still sending to. |
| 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. |
| Get topic | Get one topic with how many people subscribe to it. |
| List categories | List the categories that group the account's topics. |
| List draft bulletins | List bulletins waiting as drafts (scheduled ones too), newest first, 25 at a time. |
| List message recipients | List a targeted message's recipients with each one's delivery status and any error, 50 at a time. |
| List sent bulletins | List bulletins the account has sent, newest first, 25 at a time. |
| List subscriber's topics | List the topics a subscriber gets, by their email address or phone number. |
| List topics | List the account's topics people can subscribe to, with each one's code, name and visibility. |
| Schedule bulletin | Schedule a draft bulletin to go out at its send time (set with 'Send at' when it was created). |
| Send bulletin | Create a bulletin and send it now to everyone subscribed to the topics or categories chosen. |
| Send draft bulletin | Send a draft bulletin now to everyone subscribed to its topics. |
| Send targeted email | Send an email to the people named, such as a permit applicant (needs govDelivery Targeted Messaging). |
| Send targeted text message | Send a text message to the phone numbers given (needs govDelivery Targeted Messaging). |
| Send test of bulletin | Email a test of a draft bulletin to the addresses given (and to the connected administrator), not to subscribers. |
| Subscribe to topics | Subscribe someone to topics by email address or phone number. |
| Unschedule bulletin | Stop a scheduled bulletin from going out. |
| Unsubscribe from topics | Remove 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
- Subject
subjecttextRequired - The email's subject, up to 400 characters.
- Body
bodytextRequired - The bulletin's content. HTML is kept as formatting.
- Topics
topicslist - Who gets it: everyone subscribed to these topics. Give topics, categories or both.
- Categories
categorieslist - Everyone subscribed to these categories gets it too.
- Header
headertext - Text or HTML at the top. Leave empty to use your template's.
- Footer
footertext - Text or HTML at the bottom. Leave empty to use your template's.
- Text message
sms_bodytext - A text message sent with it to text subscribers, up to 140 characters.
- Send at
send_timedate and time - When it should go out if it is scheduled with 'Schedule bulletin'.
- Urgent
urgenttrue/false - Send at once even to people who chose a daily or weekly digest. No by default.
- Track opens
open_trackingtrue/false - Whether to record who opens it. Yes by default.
- Track clicks
click_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
- Name
nametextRequired - The topic's name, for staff.
- Name subscribers see
short_nametext - The name on the sign-up page and in emails. Defaults to the name.
- Code
codetext - A code of your choosing, such as MAIN_ST. Leave empty for govDelivery to make one.
- Description
descriptiontext - What subscribers will get, shown on the sign-up page.
- Visibility
visibilitytext - 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 alerts
wireless_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 number
bulletin_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 address
emailtext - The subscriber's email address. Give this or a phone number.
- Phone number
phonetext - The subscriber's mobile number, for text alerts. Give this or an email address.
- Country code
country_codetext - The phone's country code, such as 1 for the US. Defaults to 1.
- Tell the subscriber
notifytrue/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
- Topic
topic_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 address
emailtext - The subscriber's email address. Give this or a phone number.
- Phone number
phonetext - The subscriber's mobile number, for text alerts. Give this or an email address.
- Country code
country_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 number
bulletin_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 number
message_idtextRequired - The message's number, from 'Send targeted email' or 'Send targeted text message'.
- Kind of message
channeltext - 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
- From
startdate and timeRequired - The start of the period (counted from the hour).
- Until
enddate and timeRequired - The end of the period (counted to the hour).
- Kind of message
channeltext - 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
- Topic
topic_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 after
start_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 number
message_idtextRequired - The message's number, from 'Send targeted email' or 'Send targeted text message'.
- Kind of message
channeltext - Email or text message. Email by default.One of:
email,sms(Text message (SMS)). Default:email. - Which recipients
statustext - Everyone, or only those it was delivered to or failed for. Everyone by default.One of:
all(Everyone),sent(Delivered),failed. Default:all. - Page
pagenumber - 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 after
start_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 address
emailtext - The subscriber's email address. Give this or a phone number.
- Phone number
phonetext - The subscriber's mobile number, for text alerts. Give this or an email address.
- Country code
country_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 number
bulletin_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
- Subject
subjecttextRequired - The email's subject, up to 400 characters.
- Body
bodytextRequired - The bulletin's content. HTML is kept as formatting.
- Topics
topicslist - Who gets it: everyone subscribed to these topics. Give topics, categories or both.
- Categories
categorieslist - Everyone subscribed to these categories gets it too.
- Header
headertext - Text or HTML at the top. Leave empty to use your template's.
- Footer
footertext - Text or HTML at the bottom. Leave empty to use your template's.
- Text message
sms_bodytext - A text message sent with it to text subscribers, up to 140 characters.
- Urgent
urgenttrue/false - Send at once even to people who chose a daily or weekly digest. No by default.
- Track opens
open_trackingtrue/false - Whether to record who opens it. Yes by default.
- Track clicks
click_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 number
bulletin_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
- To
recipientslistRequired - The email addresses to send it to; each gets their own copy.
- Subject
subjecttext - The subject. Needed unless a template gives one.
- Body
bodytext - The email. HTML is kept as formatting. Needed unless a template gives one; [[name]] fills in a value from Fill-ins.
- Template
templatetext - A TMS email template to start from.
- From address
from_emailtext - Who it comes from. Leave empty for the account's default.
- From name
from_nametext - The sender's name people see.
- Fill-ins
macrosobject - Values for [[name]] placeholders in the subject and body, such as permit_number.
- Track opens
open_trackingtrue/false - Whether to record who opens it. Yes unless the template says otherwise.
- Track clicks
click_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
- To
recipientslistRequired - The mobile numbers to send it to, such as 651 555 1000.
- Message
bodytext - The text, up to 160 characters. Needed unless a template gives it.
- Template
templatetext - 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 number
bulletin_idtextRequired - The bulletin's number, from 'List draft bulletins' or an earlier step.
- Send the test to
email_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
- Topics
topicslistRequired - The topics. Pick them, or give their codes from an earlier step.
- Email address
emailtext - The subscriber's email address. Give this or a phone number.
- Phone number
phonetext - The subscriber's mobile number, for text alerts. Give this or an email address.
- Country code
country_codetext - The phone's country code, such as 1 for the US. Defaults to 1.
- Tell the subscriber
notifytrue/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 number
bulletin_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
- Topics
topicslistRequired - The topics. Pick them, or give their codes from an earlier step.
- Email address
emailtext - The subscriber's email address. Give this or a phone number.
- Phone number
phonetext - The subscriber's mobile number, for text alerts. Give this or an email address.
- Country code
country_codetext - The phone's country code, such as 1 for the US. Defaults to 1.
- Tell the subscriber
notifytrue/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"
]
}