Authentication
Authenticate with an API key passed in the
X-API-Key header.Webhooks
Stream real-time events into your CRM, warehouse, or alerting stack.
Rate limits
600 requests per minute per API key. Headers tell you where you stand.
Errors
Conventional HTTP status codes with structured error responses.
Base URL
Quickstart
1
Get an API key
From the dashboard, go to Admin → API → Create API Key. Copy the key (it’s only shown once) and store it in a secret manager - never in source control.
2
Make your first call
List your accessible organizations:
3
Subscribe to webhooks
Configure an HTTPS endpoint that receives real-time events for messages, replies, and link clicks. Always validate the HMAC signature before trusting any payload.
What you can do
Read your hierarchy
Read your hierarchy
List organizations, brands, campaigns, phone numbers, and tracking domains across your full org tree. Filter by org / brand / campaign at every level.
Manage contacts and media
Manage contacts and media
Import lists of phone numbers, emails, or both (or a do-not-contact file) from presigned storage or HTTPS URLs, trigger LRN analysis (mobile / landline / VoIP / invalid; billed per lookup), download the original or analyzed CSV, upload and reuse media files. Both contacts and media use async import + polling for “ready” status.
Create, edit, and schedule projects
Create, edit, and schedule projects
Build broadcast projects programmatically: select contact list and phone number, compose the message with merge fields, add media, enable link tracking (up to three tracked links per message with
link_tracking_links, each with its own destination and per-recipient parameters, used through the {tracking_url}, {tracking_url_2} and {tracking_url_3} tags), send tests, and schedule for a specific time + timezone. Triggered projects have no list: create one with a trigger (a donation, a click or reply, a contact being tagged, or your own call), choose when it sends (start), start it, and add recipients with POST /v1/projects/{id}/recipients or an inbound hook URL.Pull analytics and billing
Pull analytics and billing
Query message stats by date range with org/brand/campaign filters. Pull usage and billing data per organization or grouped by initiating org.
Stream events via webhooks
Stream events via webhooks
Real-time notifications for
message.sent, message.delivered, message.failed, message.replied, and link.clicked, the email events (email.sent, email.failed, email.delivered, email.opened and more), plus contact_list.analyzed when a list finishes analysis - with HMAC-signed payloads and automatic retry.Send email
Send email
Read sending domains and From addresses (both are set up in the dashboard), manage unsubscribes and bounces, and build, schedule, pause, resume, and report on email campaigns under
/v1/email. Lists hold phone numbers, emails, or both under /v1/contact-lists: create a list, add emails to it, and read its email side and members there. Nine email webhook events (email.sent, email.failed, email.delivered, email.opened, email.bounced, email.complained, email.unsubscribed, email.clicked, email.replied) subscribe alongside the message events; email.opened is approximate and opt-in. A campaign can also be triggered: created with a trigger instead of lists, it emails each person the trigger brings in, and POST /v1/email/campaigns/{id}/recipients or an inbound hook URL adds one.Write endpoints require the email entitlement on your organization and return 403 ENTITLEMENT_REQUIRED without it. Reads are open. There is no inbound or inbox surface.SDKs and tooling
Official SDKs are available for TypeScript (@political-comms/sdk, zero runtime dependencies) and Python (political-comms), alongside a CLI (@political-comms/cli) and an MCP server (@political-comms/mcp) for agent clients, all from Political-Comms/political-comms-sdk. The API is also small and stable enough that direct HTTP calls from your language of choice work just as well. The dashboard’s Export to Postman button generates a fully-configured Postman collection (Collection v2.1) you can import into Postman or Bruno for interactive testing.
Format your code samples in curl, Node, Python, Go, or any other language - the API is plain JSON over HTTPS.
Versioning and deprecation
The API is versioned in the URL path;v1 is the current and only version. Breaking changes ship as a new version path, never inside v1. When an endpoint or field is deprecated, it is marked deprecated in the OpenAPI specification, announced in the changelog, and kept working alongside its replacement before any removal. Additive changes (new endpoints, new optional fields) land in v1 without notice. The full policy, including the Deprecation/Sunset header commitment and the 90-day sunset window, lives at Versioning & Deprecation.
Idempotency and consistency
- All
GETendpoints are safe to retry - they have no side effects. - All
POSTandPATCHendpoints that mutate state are designed to be safe to retry; duplicate calls during a network blip will not create duplicate resources. If you need stronger guarantees, send a uniqueIdempotency-Keyheader on every write - repeated calls with the same key replay the original response. - Aurora Serverless v2 + RDS Proxy backs every read with p99 < 100ms at the database layer.
