@political-comms/sdk
v0.22.1
Published
TypeScript SDK for the Political Comms REST API. Zero dependencies, native fetch, built-in retries and rate limit handling.
Maintainers
Readme
@political-comms/sdk
TypeScript SDK for the Political Comms REST API. Direct-to-carrier political texting for campaigns, PACs, advocacy organizations, fundraisers, and elected officials.
Zero runtime dependencies. Uses native fetch. Node 20 or later.
The full API reference lives at docs.politicalcomms.com and the OpenAPI 3.1 specification at politicalcomms.com/openapi.json.
Install
npm install @political-comms/sdkAuthentication
Requests authenticate with an API key in the X-API-Key header. Keys are created in the dashboard under Admin > API and are prefixed pc_live_.
Set the key in the environment:
export POLITICAL_COMMS_API_KEY=pc_live_...import { PoliticalCommsClient } from '@political-comms/sdk';
const client = new PoliticalCommsClient();Or pass it to the constructor:
const client = new PoliticalCommsClient({ apiKey: 'pc_live_...' });Quickstart
Verify the credential, then run the standard send workflow: create a project, send yourself a test, and schedule it.
import { PoliticalCommsClient } from '@political-comms/sdk';
const client = new PoliticalCommsClient();
// 1. Verify the credential.
const orgs = await client.listOrganizations();
console.log(orgs.data.map((o) => o.display_name));
// 2. Create a project.
const created = await client.createProject({
organization_id: 'org_...',
brand_id: 'brand_...',
campaign_id: 'camp_...',
phone_number_ids: ['pn_...'],
name: 'GOTV reminder',
protocol: 'sms',
contact_list_ids: ['cl_...'],
message_text: 'Polls are open until 8pm. Find your polling place: {link}',
});
const projectId = created.data.id!;
// 3. Send a test to yourself.
await client.testProject(projectId, {
test_contacts: [{ phone: '+15555550100' }],
});
// 4. Schedule the send.
await client.scheduleProject(projectId, {
scheduled_at: '2026-11-03T09:00:00',
scheduled_timezone: 'America/New_York',
// Optional. Past a brand's T-Mobile daily limit, T-Mobile recipients send at
// a reduced rate; set this to skip the reduced rate and send them at full
// speed. A carrier rejection still pauses the project, and rejected messages
// are still billed. Defaults to false.
// daily_cap_bypass: true,
});A test, or any send, can also target a test phone number such as +12025550101 (any number ending 555-0100 through 555-0199) to get a fixed delivered or failed outcome without texting a real phone. See Test phone numbers.
One method exists per API operation, named after its operationId: listOrganizations, getHierarchy, listBrands, listCampaigns, getCampaignThroughput, listTrackingDomains, listPhoneNumbers, listWebhookEndpoints, getWebhookEndpoint, listTollFreeVerifications, getTollFreeVerification, listContactLists, getContactList, importContactList, analyzeContactList, downloadContactList, deleteContactList, listMedia, importMedia, getMedia, deleteMedia, listProjects, createProject, getAllProjectStats, getProject, updateProject, getProjectStats, getProjectSurveyResults, getProjectThroughput, testProject, scheduleProject, unscheduleProject, pauseProject, startProject, endProject, addProjectRecipient, createProjectHook, copyProject, listConversations, getConversation, listConversationMessages, replyToConversation, getMessageStats, getLedgerUsage, getLedgerUsageByInitiator.
Triggered projects and campaigns
A triggered text project or email campaign has no contact list. Recipients arrive one at a
time when its trigger fires, and each gets its one message, immediately or after
delay_minutes. It stays active until paused or ended. A trigger source is donation
(a connected WinRed or Anedot list), event (a text link click, text reply, email open,
email click, or email reply in another project or campaign), or api (you add the
recipient, or a tool POSTs to the inbound hook URL).
const { data: project } = await client.createProject({
type: 'triggered',
organization_id: 'org_1',
phone_number_ids: ['pn_1'],
name: 'Donor thank-you',
protocol: 'sms',
message_text: 'Thanks {first_name}, your ${amount} gift matters.',
trigger: {
source: 'donation',
donation: { integrations: [{ provider: 'winred', id: 'int_1' }], gift: 'one_time' },
delay_minutes: 10,
reentry: { mode: 'once' },
},
});
await client.testProject(project!.project_id!, { test_contacts: [{ phone: '+12025550141' }] });
await client.startProject(project!.project_id!);
// source: 'api' triggers: add one recipient. occurrence_id makes a retry of the same event a no-op.
const { data } = await client.addProjectRecipient(id, {
phone_number: '+12025550141',
fields: { first_name: 'Ada', amount: 25 },
occurrence_id: 'evt_123',
});
if (data.status === 'queued') console.log('sends at', data.send_at);
else console.log('skipped:', data.reason); // duplicate | already_entered | too_soon
const { data: hook } = await client.createProjectHook(id); // hook.hook_url (or hook.endpoint_url + hook.secret in X-Hook-Secret), shown only once
await client.endProject(id); // final: recipients still waiting are not sentEmail campaigns work the same way: createEmailCampaign({ ..., trigger }) with no list_ids,
scheduleEmailCampaign(id) with no scheduled_at to start, then addEmailCampaignRecipient,
createEmailCampaignHook, and endEmailCampaign. While paused, new recipients are refused
with a 409, not queued. Opted-out phone numbers and suppressed addresses are never sent to
(409 CONTACT_OPTED_OUT or a 422).
Webhook endpoints
listWebhookEndpoints and getWebhookEndpoint read the outbound webhook endpoints of your
organization. They are read-only: endpoints and their signing secret are created and edited
in the dashboard. Use them to check delivery health from a script. failing_since is the
start of the current run of failed deliveries (null while healthy), and disabled_reason
is consecutive_failures when the platform switched an endpoint off after 3 days with no
successful delivery. Re-enabling the endpoint clears both. The list is keyset paginated:
page until next_cursor is null. The API key needs the public:read permission.
const { data: page } = await client.listWebhookEndpoints({ limit: 100 });
for (const endpoint of page.data) {
if (!endpoint.enabled || endpoint.failing_since) console.log(endpoint.name, endpoint.disabled_reason);
}Conversations
A conversation is one thread between one of your sending numbers and one
contact, created by a project send. The API never creates a conversation; it
replies inside an existing one, from the same number, on the same project.
listConversations and listConversationMessages are keyset paginated like
the email endpoints.
// Reply to an inbound message.message.replied webhook.
await client.replyToConversation(conversationId, { text: 'Thanks for reaching out!' }, {
idempotencyKey: 'reply-' + messageId,
});
// Reply with an image or video from the media library (one flat-rate MMS).
await client.replyToConversation(conversationId, { text: 'Here is the flyer', media_ids: [mediaId] });
// Recover inbound messages missed while a webhook endpoint was down.
const { data: page } = await client.listConversations({ updated_since: lastSeenAt });
for (const conversation of page.data) console.log(conversation.conversation_id, conversation.status);The /v1/email surface is wrapped in full: sending domains, sender identities,
suppressions, templates, and campaigns. Paid
and human-driven workflows (AI drafting, result exports) run in the dashboard.
Write methods need the email entitlement on the organization and return
403 ENTITLEMENT_REQUIRED without it. Reads are open.
Email endpoints are keyset paginated: the payload is
{ data, has_more, next_cursor }. Page until next_cursor is null, and never
parse or construct a cursor.
There is no inbound email or inbox surface, and no A/B testing.
// Page through campaigns.
let cursor: string | undefined;
do {
const page = await client.listEmailCampaigns({ limit: 100, cursor });
for (const campaign of page.data!.data) console.log(campaign.name, campaign.status);
cursor = page.data!.next_cursor ?? undefined;
} while (cursor);
// Check what is blocking a campaign before scheduling it.
const { data: campaign } = await client.getEmailCampaign(id);
if (campaign?.blocked?.length) {
for (const reason of campaign.blocked) console.log(reason.code, reason.message);
} else {
await client.scheduleEmailCampaign(id, { scheduled_at: '2026-09-05T15:00:00Z' });
}Pause and resume
pauseEmailCampaign(id) pauses a scheduled, compiling, or sending campaign
with pause_reason: 'api'; the platform never resumes an api pause by itself.
resumeEmailCampaign(id, { resume_at }) resumes it now, or with a resume_at
more than a minute ahead keeps it paused and resumes it at that time (the
campaign's resume_at shows the plan; a later pause cancels it). Resume clears
any pause reason, but if the cause still holds the platform pauses it again.
Only api, manual, and provider_refused pauses wait for a person; the rest
resume on their own once the cause clears. Resume returns 409 SENDING_PAUSED
while sending is suspended, and 409 EMAIL_CAMPAIGN_TEST_REQUIRED when content
changed during the pause (send a test from the dashboard, then resume).
await client.pauseEmailCampaign(id);
await client.resumeEmailCampaign(id); // now
await client.resumeEmailCampaign(id, { resume_at: '2026-12-01T15:00:00Z' }); // plannedTemplates
Templates save the HTML a campaign sends. Create also returns lint: the save
succeeds either way, but a campaign will not schedule while lint.errors is
non-empty, so check it at save time rather than at send time. This endpoint
only accepts HTML content; content.editor is 'html' for a template
created here, or 'document' for one built in the dashboard's document
editor, readable over the API as rendered HTML only. Updating the content
of a 'document' template returns 409 CONFLICT with details.reason set
to 'TEMPLATE_IS_DOCUMENT'.
List imports
importContactList is the one list import, for phones, emails, or both. The
server fetches a CSV you host over https (50 MB cap) and returns 202. Name the
columns: phone_column, email_column, or both (there is no automatic email
column detection). consent is optional and allowed only for an audience list with emails; with merge_tags, phones map only the named columns while emails also map every remaining column.
purpose: 'do_not_contact' turns phones into an opt-out list and emails into
unsubscribes, and returns no list_id. For an audience import, poll getContactList(id): import is the
phone side and email.status is the email side.
const { data: started } = await client.importContactList({
source_url: 'https://example.com/donors.csv',
list_name: 'August donors',
phone_column: 'Phone',
email_column: 'Email',
merge_tags: { first_name: 'First Name' },
consent: { source: 'donation_form', note: 'ActBlue donors, 2026 cycle' },
});
if (started.purpose === 'audience') console.log(started.list_id, started.channels);listContactLists returns the lists that hold phone numbers by default; pass
channel: 'email' or channel: 'all' for the others. Each list reports its
channels and its email side (null when it has none). deleteContactList removes a list's phone numbers and its emails. The three delete methods (deleteContactList, deleteMedia, removeEmailSuppressions) need an API key with the public:delete permission, which is opt-in when the key is created and requires public:write; other keys get a 403.
Email addresses reach a list only through importContactList with email_column
(a CSV import creates the list, with the email side). Poll getContactList and
read email.status and email.counts; read unsubscribes and bounces with
listEmailSuppressions.
Error handling
Non-success responses throw PoliticalCommsError with the API's machine readable code, the HTTP statusCode, and the raw response body.
import { PoliticalCommsError } from '@political-comms/sdk';
try {
await client.getProject('proj_unknown');
} catch (err) {
if (err instanceof PoliticalCommsError) {
console.error(err.code, err.statusCode, err.message);
}
}Network failures throw PoliticalCommsError with code: 'NETWORK_ERROR' and statusCode: 0.
Retries
The client retries automatically with these rules:
400,401,403,404are never retried.429is retried after waiting until theX-RateLimit-Resettimestamp.500,502,503,504are retried with exponential backoff and jitter: 1 second base, 60 second cap, at most 5 attempts total.
Configure the retry budget with maxRetries (retries after the first attempt, default 4):
const client = new PoliticalCommsClient({ maxRetries: 2 });Every POST and PATCH request carries an Idempotency-Key header (a random UUID) so retries are safe; the API returns the cached first response when a key is replayed. DELETE requests send the header only when you supply a key. Supply your own key per call when you need cross-process deduplication:
await client.createProject(body, { idempotencyKey: 'send-2026-11-03-wave-1' });Each call also accepts an AbortSignal:
await client.listProjects({}, { signal: AbortSignal.timeout(10_000) });Rate limits
The API allows 600 requests per minute per key: bursts of up to 600 at once, refilling at 10 per second, the same for every scope. The client exposes the most recent rate limit headers:
await client.listOrganizations();
console.log(client.lastRateLimit);
// { limit: 100, remaining: 97, reset: 1767225600 } (reset is Unix seconds)License
MIT. Questions: [email protected]
