# Political Comms

> Documentation for the Political Comms P2P texting platform - help center, onboarding, compliance, and API reference.

- [Welcome to Political Comms](https://docs.politicalcomms.com/introduction.md): Enterprise-grade P2P texting for political campaigns, PACs, parties, and nonprofits. Documentation, compliance guidance, and API reference.
- [Onboarding Guide](https://docs.politicalcomms.com/onboarding/overview.md): Get up and running in 2-3 business days. Five sequential steps from account setup to sending your first message.
- [Step 1: Account Setup & Organization Profile](https://docs.politicalcomms.com/onboarding/account-setup.md): Confirm your organization profile, add funding, and turn on auto-recharge from the /onboarding page - typically 5-10 minutes.
- [Step 2: 10DLC Brand & Campaign Registration](https://docs.politicalcomms.com/onboarding/10dlc-registration.md): Register each brand with The Campaign Registry, vet with Campaign Verify, create campaigns, and provision phone numbers.
- [Step 3: Upload & Organize Contacts](https://docs.politicalcomms.com/onboarding/contacts.md): Import voter lists via CSV, validate with carrier lookup, segment for targeting, and manage opt-out lists.
- [Step 4: Create Your First Messaging Project](https://docs.politicalcomms.com/onboarding/first-project.md): Build a project, compose your message with personalization, add media, set up quick replies, send tests, and queue for sending.
- [Step 5: Monitor, Engage, and Optimize](https://docs.politicalcomms.com/onboarding/monitoring.md): Track delivery, respond to replies, manage opt-outs, analyze performance, and iterate on what works.
- [AI Agent Integration](https://docs.politicalcomms.com/agent-readiness.md): How AI agents discover, search, and reason about Political Comms. MCP server, OpenAPI, llms.txt, and the rest of the discovery surface.
- [Getting Started](https://docs.politicalcomms.com/help/getting-started.md): What the platform does, how 10DLC works, what you need to register, and how fast you can launch your first campaign.
- [Platform Features](https://docs.politicalcomms.com/help/platform-features.md): Throughput, MMS, personalization, two-way conversations, team permissions, and reporting.
- [Sending speed and carrier limits](https://docs.politicalcomms.com/help/sending-speed.md): How fast you can send, the limits each carrier sets, what happens at the AT&T limit, and how to finish a large send sooner.
- [Data exports to your S3 bucket](https://docs.politicalcomms.com/help/data-exports.md): Scheduled Parquet exports of message, project, opt-out and click data into a bucket you own. Setup, file layout, the four datasets and every column.
- [Organizations and memberships](https://docs.politicalcomms.com/help/organizations-and-memberships.md): Belong to more than one organization, switch between them, invite existing accounts, and manage ownership.
- [Sharing phone numbers with sub-organizations](https://docs.politicalcomms.com/help/shared-phone-numbers.md): Let an organization under yours send from a number you registered, under a nickname, without re-registering, without seeing your registration, and without paying the monthly fees.
- [Messaging Best Practices](https://docs.politicalcomms.com/help/best-practices.md): How to write effective opening messages, when to send, opt-out handling, response rate optimization, and what to avoid.
- [Compliance Basics](https://docs.politicalcomms.com/help/compliance.md): TCPA, consent, CTIA principles, and how to handle opt-out requests.
- [Billing & Account Balance](https://docs.politicalcomms.com/help/billing.md): How balance-based billing works, auto-recharge, organization hierarchy, 10DLC costs, and refund policy.
- [Bring Your Own Stripe](https://docs.politicalcomms.com/help/bring-your-own-stripe.md): How resellers connect their own Stripe account to collect payments from their sub-organizations directly.
- [Technical Support](https://docs.politicalcomms.com/help/technical-support.md): Supported devices, delivery troubleshooting, API integration, contact imports, error handling, and where to learn more.
- [Email Overview](https://docs.politicalcomms.com/help/email/overview.md): What the Political Comms email product does, what it deliberately does not do, and how sending gets set up.
- [Sending Domains and DNS](https://docs.politicalcomms.com/help/email/sending-domains-and-dns.md): Adding a domain, the DNS records to publish for email sending, how each one is confirmed, drift detection, and why we never write DNS for you.
- [Lists and address screening](https://docs.politicalcomms.com/help/email/lists-and-validation.md): Importing email contacts, recording consent, what is removed at import, send-time address screening, acquired lists, segments, and the sunset policy for unengaged contacts.
- [Campaigns and Deliverability](https://docs.politicalcomms.com/help/email/campaigns-and-deliverability.md): Sender identities, the campaign builder, test sends, the warm-up ramp, deliverability breakers, frequency caps, DMARC progression, tracking, and reporting.
- [Bounces, complaints, and suppressions](https://docs.politicalcomms.com/help/email/bounces-complaints-and-suppressions.md): What happens when a message bounces or is marked as spam, how unsubscribes are recorded, and how suppression keeps an address from being mailed again.
- [Compliance and link tagging](https://docs.politicalcomms.com/help/email/compliance-and-link-tagging.md): CAN-SPAM footers, paid-for-by disclaimers, one-click unsubscribe, forget this address, and how donation links are tagged for WinRed and Anedot.
- [Google Postmaster Tools](https://docs.politicalcomms.com/help/email/google-postmaster-tools.md): How Gmail's own view of your sending reaches your dashboard, what the one TXT record does, and why a new sender sees no data at first.
- [Gmail Verified Sender Program](https://docs.politicalcomms.com/help/email/gmail-verified-sender-program.md): What Google's Verified Sender Program does, who is eligible, what we check before you submit, and the Campaign Verify steps.
- [Compliance & Regulatory Guide](https://docs.politicalcomms.com/compliance/overview.md): Stay compliant with federal regulations and industry best practices for political text messaging - TCPA, FCC, CTIA, 10DLC, and Campaign Verify.
- [Telephone Consumer Protection Act (TCPA)](https://docs.politicalcomms.com/compliance/tcpa.md): Federal law protecting consumers from unwanted automated calls and text messages. Key requirements, political exemptions, and penalties up to $1,500 per message.
- [FCC Political Text Messaging Rules](https://docs.politicalcomms.com/compliance/fcc-political.md): How the FCC applies TCPA specifically to political text messaging campaigns, including the Facebook v. Duguid autodialer ruling.
- [CTIA Messaging Principles & Best Practices](https://docs.politicalcomms.com/compliance/ctia.md): Wireless industry standards for protecting consumers and maintaining message deliverability - opt-in consent, informed consent, opt-out handling.
- [The Campaign Registry (10DLC)](https://docs.politicalcomms.com/compliance/campaign-registry.md): Centralized registration system for verified business text messaging in the United States. Brand setup, campaign creation, costs, and timelines.
- [Campaign Verify](https://docs.politicalcomms.com/compliance/campaign-verify.md): Nonpartisan verification service for U.S. political campaigns, PACs, and committees. Eligibility, process, costs, and validity.
- [Compliance Checklist](https://docs.politicalcomms.com/compliance/checklist.md): Run through this 10-item checklist for every campaign to make sure you stay compliant with all regulations.
- [Compliance Glossary](https://docs.politicalcomms.com/compliance/glossary.md): Definitions for 10DLC, A2P, ATDS, CSP, TCPA, TCR, 527 organizations, and other terms you'll encounter in political-text compliance.
- [Terms of Use](https://docs.politicalcomms.com/legal/terms.md): Terms of Use governing access to and use of the Political Comms platform.
- [Privacy Policy](https://docs.politicalcomms.com/legal/privacy.md): Political Comms' privacy practices for the data we collect, how we use it, and your choices.
- [Changelog](https://docs.politicalcomms.com/changelog.md): Recent updates, improvements, and fixes to the Political Comms platform.
- [Introduction](https://docs.politicalcomms.com/api-reference/introduction.md): Public REST API for integrating messaging data, project statistics, and billing into your stack.
- [Authentication](https://docs.politicalcomms.com/api-reference/authentication.md): API keys, the X-API-Key header, scoping to your organization hierarchy, and how to keep secrets safe.
- [Rate Limits](https://docs.politicalcomms.com/api-reference/rate-limits.md): 600 requests per minute per API key (bursts up to 600, refilling 10 per second), with X-RateLimit-* response headers and 429 backoff guidance.
- [Error Handling](https://docs.politicalcomms.com/api-reference/errors.md): Conventional HTTP response codes with a structured error object containing code, message, and additional context.
- [Versioning & Deprecation](https://docs.politicalcomms.com/api-reference/versioning.md): How the API is versioned, how deprecations are announced, and the sunset guarantees you can build against
- [Best Practices](https://docs.politicalcomms.com/api-reference/best-practices.md): API key security, caching recommendations, rate limit strategies, carrier throughput limits, and date range optimization.
- [Two-Way Conversations](https://docs.politicalcomms.com/api-reference/two-way-conversations.md): Answer inbound texts programmatically: receive message.replied, reply inside the same conversation from the same number, and recover missed inbounds with the conversations list.
- [Overview](https://docs.politicalcomms.com/api-reference/webhooks/overview.md): Real-time webhook notifications for messages, replies, and link clicks. Use cases, payload format, and architecture.
- [Setup & Configuration](https://docs.politicalcomms.com/api-reference/webhooks/setup.md): Add a webhook endpoint, subscribe to events, copy the signing secret, and send a test webhook.
- [Signature Validation](https://docs.politicalcomms.com/api-reference/webhooks/signature-validation.md): Every webhook request is signed with HMAC-SHA256 using your endpoint secret. Validate before trusting the payload.
- [Event Types](https://docs.politicalcomms.com/api-reference/webhooks/events.md): Full JSON payload samples for message.sent, message.delivered, message.failed, message.replied, link.clicked, the email events, and contact_list.analyzed.
- [Delivery Error Codes](https://docs.politicalcomms.com/api-reference/webhooks/error-codes.md): Every error_code the message.failed webhook can deliver, with its error_message and what to do about it.
- [Retry Policy](https://docs.politicalcomms.com/api-reference/webhooks/retry-policy.md): Four attempts with exponential backoff. Best practices for making handlers idempotent.
- [List Projects](https://docs.politicalcomms.com/api-reference/projects/list-projects.md): List all projects (broadcast and survey). Filter by organization, brand, campaign, or project type.
- [Create Project](https://docs.politicalcomms.com/api-reference/projects/create-project.md): Create a new project. `type` selects the payload shape: `broadcast` (the default) sends one message to the audience; `survey` runs a multi-question flow with branching.
- [Get Project Stats (all)](https://docs.politicalcomms.com/api-reference/projects/get-project-stats-all.md): Aggregate per-project statistics for a date range (max 31 days, no older than 90 days). Results are paginated via limit/offset.
- [Get Project](https://docs.politicalcomms.com/api-reference/projects/get-project.md): Fetch a single project. Survey projects additionally include the ordered `questions` array; their `message_text`, `protocol`, and `media_urls` mirror the intro question.
- [Update Project](https://docs.politicalcomms.com/api-reference/projects/update-project.md): Update a project while in `draft`, `awaiting_test`, or `ready`. `organization_id` / `brand_id` / `campaign_id` / `channel` / `toll_free_verification_id` / `type` are immutable after creation; including them in the body returns a 400. All other fields are partial: send only the keys you want to chang…
- [Get Project Stats (single)](https://docs.politicalcomms.com/api-reference/projects/get-project-stats-single.md): Delivery and engagement metrics for a single project. Cached for up to 5 minutes (15 seconds while the project is actively sending).
- [Get Project Throughput](https://docs.politicalcomms.com/api-reference/projects/get-project-throughput.md): Pre-flight estimate of how carrier limits will affect this project: recipients expected on T-Mobile and AT&T, whether the project will pause at the T-Mobile daily cap, and how many days or minutes the send needs. `t_mobile` is null when the brand has no T-Mobile daily limit on file (political brands…
- [Get Survey Results](https://docs.politicalcomms.com/api-reference/projects/get-survey-results.md): Topline results for a survey project: per-question option counts and percentages, the unmatched/open-ended "other" bucket, and overall completion/dropoff rates. The numbers match the survey results page in the dashboard.
- [Test Project](https://docs.politicalcomms.com/api-reference/projects/test-project.md): Send test message(s). Pass `test_contacts` as an array of 1-50 objects. By default, merge fields in the message template are rendered from a sample contact in the project's contact list, not from the request; for a survey, every question renders from that same contact. With no list, tags resolve as…
- [Schedule Project](https://docs.politicalcomms.com/api-reference/projects/schedule-project.md): Transition a project to `scheduled` status. The project must be in `ready` or `paused` status; scheduling a `paused` project resumes it. When a project pauses with `pause_reason` `brand_daily_cap` (the brand's T-Mobile daily cap; it resets at midnight Pacific), do not resume at midnight. Schedule it…
- [Unschedule Project](https://docs.politicalcomms.com/api-reference/projects/unschedule-project.md): Transition a scheduled project back to `ready`.
- [Copy Project](https://docs.politicalcomms.com/api-reference/projects/copy-project.md): Duplicate a project. The copy carries the message content, media, phone numbers, link tracking settings, and survey questions, and gets a versioned name (`Fall GOTV` becomes `Fall GOTV_v2`). Contact lists, suppression lists, the schedule, and all delivery stats are not carried over: the copy starts…
- [List Phone Numbers](https://docs.politicalcomms.com/api-reference/phone-numbers/list-phone-numbers.md): List all phone numbers across both channels: 10DLC numbers (owned via a campaign) and toll-free numbers (owned via a toll-free verification). Each row carries a `channel` and an `owner_type` indicating what it belongs to. The `campaign_id`/`campaign_name`/`brand_id`/`brand_name` fields are populated…
- [List Toll-Free Verifications](https://docs.politicalcomms.com/api-reference/toll-free-verifications/list-toll-free-verifications.md): List toll-free verifications (the carrier registrations behind your toll-free numbers) across your organization hierarchy. Filter by organization or by submission status.
- [Get Toll-Free Verification](https://docs.politicalcomms.com/api-reference/toll-free-verifications/get-toll-free-verification.md): Fetch a single toll-free verification, including the phone numbers it covers and any rejection reason.
- [List Brands](https://docs.politicalcomms.com/api-reference/brands/list-brands.md): List all brands. Optionally filter by organization.
- [List Campaigns](https://docs.politicalcomms.com/api-reference/10dlc-campaigns/list-campaigns.md): List all campaigns. Filter by organization or brand.
- [Get Campaign Throughput](https://docs.politicalcomms.com/api-reference/10dlc-campaigns/get-campaign-throughput.md): Carrier sending limits for a campaign's brand and how much of today's T-Mobile daily cap is used. The two carrier lanes are independent: `t_mobile` is present only once a T-Mobile daily cap has synced for the campaign, and `att` whenever the campaign has an AT&T rate on file, whatever the brand type…
- [List Campaigns](https://docs.politicalcomms.com/api-reference/email-campaigns/list-campaigns.md): List email campaigns.
- [Create Campaign](https://docs.politicalcomms.com/api-reference/email-campaigns/create-campaign.md): Create a draft campaign.
- [Get Campaign](https://docs.politicalcomms.com/api-reference/email-campaigns/get-campaign.md): Fetch one campaign. This read additionally returns `blocked`: the machine-readable list of reasons the campaign will not schedule yet. Check it before calling schedule.
- [Schedule Campaign](https://docs.politicalcomms.com/api-reference/email-campaigns/schedule-campaign.md): Schedule the campaign, or omit `scheduled_at` to send now. A date in the past returns `400 VALIDATION_ERROR`. Scheduling runs the full checklist; if it refuses, read `blocked` on the campaign to see why.
- [Unschedule Campaign](https://docs.politicalcomms.com/api-reference/email-campaigns/unschedule-campaign.md): Return a scheduled campaign to a draft state.
- [Get Campaign Stats](https://docs.politicalcomms.com/api-reference/email-campaigns/get-campaign-stats.md): Report tiles, fundraising totals, and per-link click stats for a campaign. Cached for 60 seconds. Test and seed sends are excluded from every figure.
- [List Email Templates](https://docs.politicalcomms.com/api-reference/email-templates/list-email-templates.md): List the organization's email templates, newest first.
- [Create Email Template](https://docs.politicalcomms.com/api-reference/email-templates/create-email-template.md): Create a template from raw HTML. The response carries a `lint` object beside the template: a template with lint errors saves, but a campaign using it will not schedule.
- [Get Email Template](https://docs.politicalcomms.com/api-reference/email-templates/get-email-template.md): Get one template, including its HTML.
- [List Sender Identities](https://docs.politicalcomms.com/api-reference/email-senders/list-sender-identities.md): List every sender identity in the organization. This endpoint is not paginated: `has_more` is always `false`.
- [Get Sender Identity](https://docs.politicalcomms.com/api-reference/email-senders/get-sender-identity.md): Fetch one sender identity.
- [List Suppressions](https://docs.politicalcomms.com/api-reference/email-suppressions/list-suppressions.md): List suppressed addresses.
- [Add Suppressions](https://docs.politicalcomms.com/api-reference/email-suppressions/add-suppressions.md): Suppress up to 5,000 addresses in one call. Malformed addresses are reported in `invalid` rather than failing the batch.
- [Remove Suppressions](https://docs.politicalcomms.com/api-reference/email-suppressions/remove-suppressions.md): Lift suppressions on up to 5,000 addresses. Removing an address that was not suppressed is not an error.
- [List Contact Lists](https://docs.politicalcomms.com/api-reference/contact-lists/list-contact-lists.md): List all contact lists. Filter by organization or brand.
- [Get Contact List](https://docs.politicalcomms.com/api-reference/contact-lists/get-contact-list.md): Fetch a single contact list including import progress and phone-type analysis results. `downloads` links the CSV files: `original_url` always, `analyzed_url` once analysis is complete (null before). Both are API URLs, so request them with your `X-API-Key`; they do not expire.
- [Delete Contact List](https://docs.politicalcomms.com/api-reference/contact-lists/delete-contact-list.md): Permanently remove a contact list from your account. The list is detached from any draft projects that reference it and no longer appears in list or read endpoints. Deletion is blocked with a 409 while a scheduled, sending, or active project depends on the list; unschedule the project or wait for th…
- [Import Contact List](https://docs.politicalcomms.com/api-reference/contact-lists/import-contact-list.md): Asynchronous job: import a CSV from a client-supplied presigned S3 or public HTTPS URL. Returns immediately with the created resource; poll `GET /contact-lists/{id}` until `status` is `ready`. Columns other than the phone column become merge tags automatically unless you send `merge_tags` (see that…
- [Analyze Contact List](https://docs.politicalcomms.com/api-reference/contact-lists/analyze-contact-list.md): Asynchronous, billable job: trigger LRN mobile/landline/VoIP/invalid analysis for an imported list. Charged per lookup to the list's organization for the numbers not yet analyzed; the wallet is checked first, and `402` `INSUFFICIENT_BALANCE` queues nothing. Send an `Idempotency-Key` so a retried cal…
- [List Email Lists](https://docs.politicalcomms.com/api-reference/email-lists/list-email-lists.md): List the organization's email lists.
- [Create Email List](https://docs.politicalcomms.com/api-reference/email-lists/create-email-list.md): Create an email list. `consent_attestation` is required: you are recording how the people on this list agreed to hear from you.
- [Get Email List](https://docs.politicalcomms.com/api-reference/email-lists/get-email-list.md): Fetch one email list with its contact counts.
- [List Contacts](https://docs.politicalcomms.com/api-reference/email-lists/list-contacts.md): List the contacts on an email list.
- [Add Contacts](https://docs.politicalcomms.com/api-reference/email-lists/add-contacts.md): Upsert up to 1,000 contacts in one call. Invalid rows do not fail the request: every row comes back with its own outcome so you can fix just the rejected ones.
- [Import Contacts From A URL](https://docs.politicalcomms.com/api-reference/email-lists/import-contacts-from-a-url.md): Import contacts into a list from a CSV you host.
- [List Media Files](https://docs.politicalcomms.com/api-reference/media-files/list-media-files.md): List all media files. Filter by organization or brand.
- [Import Media](https://docs.politicalcomms.com/api-reference/media-files/import-media.md): Asynchronous job: provide an HTTPS URL to the file and the server retrieves and stores it. Returns immediately; poll `GET /media/{id}` until `status` is `ready`.
- [Get Media File](https://docs.politicalcomms.com/api-reference/media-files/get-media-file.md): Fetch a single media file including optimization status and metadata.
- [Delete Media File](https://docs.politicalcomms.com/api-reference/media-files/delete-media-file.md): Permanently remove a media file from your account. The file is detached from any draft projects or survey questions that reference it and no longer appears in list or read endpoints. Already-sent MMS messages keep rendering their media. Deletion is blocked with a 409 while a scheduled, sending, or a…
- [Get Usage](https://docs.politicalcomms.com/api-reference/billing/get-usage.md): Ledger usage aggregated per organization for a date range. The range must be 31 days or less and may not start more than 180 days in the past or end in the future. Charge amounts are signed: usage charges are negative.
- [Get Usage by Initiator](https://docs.politicalcomms.com/api-reference/billing/get-usage-by-initiator.md): Ledger usage grouped by the organization that initiated each charge, for a date range (max 31 days, no older than 180 days). Amounts are signed: charges are negative. Initiators are sorted by totalAmount descending.
- [Get Message Stats](https://docs.politicalcomms.com/api-reference/analytics/get-message-stats.md): Message delivery statistics for a date range. The range must be 31 days or less and may not start more than 180 days in the past or end in the future.
- [List Sending Domains](https://docs.politicalcomms.com/api-reference/sending-domains/list-sending-domains.md): List the organization's email sending domains, newest first.
- [Get Sending Domain](https://docs.politicalcomms.com/api-reference/sending-domains/get-sending-domain.md): Fetch one sending domain, including the DNS records to publish and the per-signal verification state.
- [List Tracking Domains](https://docs.politicalcomms.com/api-reference/tracking-domains/list-tracking-domains.md): List active tracking domains available to your organizations. Domains owned by one of your accessible organizations return source "own" with full metadata; domains shared down from a parent organization return source "inherited" with only id, domain, and source. Optional filter by organization.
- [List Organizations](https://docs.politicalcomms.com/api-reference/organizations/list-organizations.md): List all descendant organizations accessible to your API key.
- [Get Hierarchy](https://docs.politicalcomms.com/api-reference/organizations/get-hierarchy.md): Get the full organization hierarchy with brands and campaigns, rooted at the requested organization (defaults to the API key's organization). Responses use camelCase field names and are cached for up to 5 minutes.
- [AGENTS](https://docs.politicalcomms.com/AGENTS.md)
- [CLAUDE](https://docs.politicalcomms.com/CLAUDE.md)

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)

## Optional

- [Dashboard](https://app.politicalcomms.com)
- [Status](https://status.politicalcomms.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.