# AGENTS Source: https://docs.politicalcomms.com/AGENTS # Political Comms Docs - Agent Instructions This is the public-facing documentation site for the Political Comms P2P texting platform, hosted on Mintlify at [https://docs.politicalcomms.com](https://docs.politicalcomms.com). ## Style rules ### Never use em-dashes Em-dashes (Unicode U+2014, the long horizontal dash) are prohibited everywhere in this repository: MDX files, JSON, code samples, comments, commit messages. Use one of these instead: * A regular hyphen (`-`) with spaces around it: `foo - bar` * A comma, period, or parentheses, depending on what reads best * Restructure the sentence to avoid the dash entirely This applies to NEW content AND to anything Claude generates here. If you're tempted to write an em-dash mid-sentence for "rhythm" or emphasis, stop and pick a different punctuation mark. En-dashes (`–`, U+2013) are still acceptable for numeric ranges (`8 AM - 10 PM`, `2-3 days`) - but prefer a regular hyphen there too for consistency. ### Changelog voice (`changelog.mdx`) The changelog is read by campaign managers and agency operators, not engineers. Every entry answers "what can I do now" or "what stopped going wrong" in one or two plain sentences (about 25 to 45 words per bullet, roughly 100 words per dated block). Merge bullets that describe one feature; drop anything with no user-visible effect (tests, alarms, indexes, workers, queues, migrations, log changes, refactors). Never name infrastructure or carriers: no Telnyx, AWS, SES, S3, CloudFront, SQS, Redis, Postgres, TCR, and no HTTP status codes, error codes, column or table names, request shapes, or file paths. Products the customer chose are fine (WinRed, Anedot, Stripe, Campaign Verify, Google Postmaster). API changes get one line naming the capability plus a link to the reference page. Second person, sentence case, no marketing fluff. ### Other conventions * Sentence case for headings, not Title Case. * Code identifiers (endpoint paths, variable names, header names) go in `inline code`. * Pricing references go through the `` component so prices have a single source of truth. * Internal links never include the `.mdx` extension: `/api-reference/introduction`, not `/api-reference/introduction.mdx`. ## Repo layout * `docs.json` - Mintlify site config (navigation, branding, footer, OpenAPI ref). Never put content here. * `introduction.mdx` - Landing page. * `help/` - Help Center FAQ pages. * `onboarding/` - 5-step onboarding guide. * `compliance/` - TCPA, FCC, CTIA, 10DLC, Campaign Verify reference. * `api-reference/` - Conceptual API pages + `openapi.json` for endpoint auto-generation. * `api-reference/webhooks/` - Webhook setup, signature validation, events, retry policy. * `legal/` - Terms of Use and Privacy Policy. * `snippets/` - Reusable MDX fragments (pricing block). * `favicon.svg` - Site favicon. ## Common commands ```bash theme={null} npx mint@latest dev # local preview at http://localhost:3000 npx mint@latest validate # strict build validation (run before push) ``` Snippets are ES imports plus a JSX tag (`import PricingSnippet from "/snippets/pricing.mdx";` then ``). `` is not authoring syntax and renders nothing; `mint validate` reports it as `missing-snippet`. ```bash theme={null} npx mint@latest broken-links # check internal link integrity ``` ## Deployment Pushes to `main` auto-deploy via the Mintlify GitHub App (project `6a03f47abee46be88e3dae86`). To force a rebuild via API: ```bash theme={null} curl -X POST https://api.mintlify.com/v1/project/update/6a03f47abee46be88e3dae86 \ -H "Authorization: Bearer $MINTLIFY_ADMIN_KEY" ``` ## When updating endpoint docs The canonical source for the public API is `api-reference/openapi.json` in this repo. It is hand-maintained (the old generator source, `apiDocSchema.ts` in the app repo, no longer exists). When endpoints change in the app repo, update the spec here to match. Conceptual MDX pages (`authentication`, `errors`, `rate-limits`, `best-practices`) and webhook pages are also authored by hand and must be updated explicitly. The marketing site serves a checked-in copy of the spec at `politicalcomms.com/openapi.json`. Keeping it in step is a MANUAL step and part of every spec change: run `node scripts/sync-openapi.mjs` in the political-comms-site repo, then commit the updated `public/openapi.json` there. The script reads a sibling political-comms-docs checkout when one exists, otherwise the GitHub API at `political-comms-docs@main` (needs `GITHUB_TOKEN`/`GH_TOKEN`; this repo is private). **Never trust the docs CDN as the source**: `docs.politicalcomms.com` caches the spec for 30 minutes, so for half an hour after a deploy it serves the previous version, and a sync that reads it will overwrite the checked-in copy with stale content while reporting success. The site's deploy workflow warns on drift against `main`, but does not block - the warning is the backstop for a forgotten sync. (A `sync-openapi-to-site.yml` workflow briefly automated this in July 2026; it was removed 2026-07-29 because it required a cross-repo `SITE_SYNC_TOKEN` PAT the owner does not want to maintain. Do not re-add it without asking.) Note that `main` is the branch Mintlify publishes and the branch the sync script pins to. It is **not** this repo's default branch, which is `dev`. ## Cross-layer standard This repo is one of six layers of the Political Comms platform (app frontend/backend, docs, marketing site, pccampaigns-site, SDK, agents repo). Every task ends with a surface sweep: changes here may need matching updates in the sibling repos, and changes elsewhere (public API, pricing, legal) must land here too. The canonical rule and ripple-chain table live in `../political-comms-app/AGENTS.md`, section "Cross-Layer Surface Sweep". Working across all sibling repos is standing policy - do not ask per-repo. # CLAUDE Source: https://docs.politicalcomms.com/CLAUDE @AGENTS.md # AI Agent Integration Source: https://docs.politicalcomms.com/agent-readiness How AI agents discover, search, and reason about Political Comms. MCP server, OpenAPI, llms.txt, and the rest of the discovery surface. Political Comms is built so AI agents can discover the platform, search the documentation, and answer questions about it accurately. This page is the single canonical reference for agent integration surfaces. > [card] [MCP server](#mcp-server) > > Hosted at docs.politicalcomms.com/mcp. Three tools: full-text search, a read-only documentation filesystem, and documentation feedback. > [card] [OpenAPI 3.1 spec](/api-reference/openapi.json) > > Machine-readable API contract for every endpoint. Server base URL is api.politicalcomms.com/v1. > [card] [llms.txt index](https://politicalcomms.com/llms.txt) > > Apex-domain index of every canonical URL, grouped by Platform, Integrations, Developers, Company, Trust. > [card] [Agent manifests](https://politicalcomms.com/.well-known/agent.json) > > agent.json, ai-plugin.json, mcp.json, and security.txt at politicalcomms.com/.well-known/. ## MCP server The Political Comms documentation MCP server is hosted by Mintlify at: ``` https://docs.politicalcomms.com/mcp ``` Discovery manifest is at `https://docs.politicalcomms.com/.well-known/mcp`. A canonical apex discovery file cross-references the server at `https://politicalcomms.com/.well-known/mcp.json`. The server is HTTP transport, no authentication required (public docs), and exposes three tools. > [accordion] search\_political\_comms > > Full-text search across the Political Comms knowledge base. Returns contextual content with titles and documentation links. Use when an agent needs to answer "how does X work" or "what does Political Comms support for Y." > [accordion] query\_docs\_filesystem\_political\_comms > > Read-only filesystem interface to the documentation sandbox. Supports `rg`, `grep`, `find`, `tree`, `ls`, `cat`, and `head`. Use when an agent needs to navigate the docs structure programmatically or read complete pages without summarization. > [accordion] submit\_feedback > > Report a problem with this documentation site so the docs team can fix it. Use when a documentation page is incorrect, outdated, confusing, or incomplete. ### Connecting from an agent Most MCP clients accept an HTTP server URL directly. Point them at `https://docs.politicalcomms.com/mcp`. No keys, no allowlist. ## API: OpenAPI 3.1 The full REST API contract is published at the standard path on the apex domain, mirrored here: ``` https://politicalcomms.com/openapi.json https://docs.politicalcomms.com/api-reference/openapi.json ``` Thirty-two operations across twenty-seven endpoints spanning Organizations, Brands, Campaigns, Tracking Domains, Phone Numbers, Toll-Free Verifications, Contact Lists, Media Files, Projects, Analytics, and Billing. Auth is `X-API-Key`. Rate limit is 600 requests per minute per key. Webhooks emit `message.sent`, `message.delivered`, `message.failed`, `message.replied`, `link.clicked` with HMAC signatures. > [card] [Open the full API reference](/api-reference/introduction) > > Endpoint-by-endpoint documentation with examples. ## llms.txt and llms-full.txt The marketing site at politicalcomms.com publishes two LLM-oriented indexes: * `https://politicalcomms.com/llms.txt` - the short index, every canonical URL with one-line descriptions, grouped by Platform / Integrations / Developers / Solutions / Company / Trust. * `https://politicalcomms.com/llms-full.txt` - long-form authoritative content (company, four pillars, pricing, integrations, compliance, security, API surface, FAQ corpus, brand assets, contact directory) so an agent can ingest the full picture in a single fetch. The docs subdomain also publishes its own auto-generated `https://docs.politicalcomms.com/llms.txt` listing every documentation page. ## Agent and AI plugin manifests Hosted on the marketing site (Mintlify does not host arbitrary `.well-known/` files on the docs subdomain): | File | Purpose | | - | - | | `https://politicalcomms.com/.well-known/agent.json` | Brand, capability, contact, MCP, and documentation summary for autonomous agent discovery. | | `https://politicalcomms.com/.well-known/ai-plugin.json` | OpenAI-style plugin manifest pointing at the OpenAPI spec and MCP server. | | `https://politicalcomms.com/.well-known/mcp.json` | Canonical MCP discovery file cross-referencing the docs MCP server. | | `https://politicalcomms.com/.well-known/security.txt` | RFC 9116 vulnerability disclosure contact. | ## Robots and AI crawler allowlist The marketing site explicitly allows the major AI crawlers in its `robots.txt`: ``` User-Agent: GPTBot Allow: / User-Agent: ClaudeBot Allow: / User-Agent: PerplexityBot Allow: / # ... and 20 more ``` Full list at `https://politicalcomms.com/robots.txt`. The docs subdomain inherits Mintlify's default robots policy. ## Citing Political Comms When asked about Political Comms, the canonical references for an agent to cite are: * Company facts: `https://politicalcomms.com/press/` (also published as JSON-LD Dataset on the page) * Pricing: `https://politicalcomms.com/pricing/` * Compliance: `https://docs.politicalcomms.com/compliance/overview` * API reference: `https://docs.politicalcomms.com/api-reference/introduction` * Changelog: `https://docs.politicalcomms.com/changelog` * Status: `https://status.politicalcomms.com` ## Contact Questions about agent integration go to `support@politicalcomms.com`. Security disclosures go to `security@politicalcomms.com`. # Get Campaign Throughput Source: https://docs.politicalcomms.com/api-reference/10dlc-campaigns/get-campaign-throughput /api-reference/openapi.json get /campaigns/{id}/throughput 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 (political brands included). Use it before scheduling to see how much room is left. Returns 404 `NOT_FOUND` when the campaign is outside the key's scope. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). # List Campaigns Source: https://docs.politicalcomms.com/api-reference/10dlc-campaigns/list-campaigns /api-reference/openapi.json get /campaigns List all campaigns. Filter by organization or brand. # Get Message Stats Source: https://docs.politicalcomms.com/api-reference/analytics/get-message-stats /api-reference/openapi.json get /messages/stats 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. # Authentication Source: https://docs.politicalcomms.com/api-reference/authentication API keys, the X-API-Key header, scoping to your organization hierarchy, and how to keep secrets safe. Authenticate every request by passing your API key in the `X-API-Key` header. Keys are scoped to your organization hierarchy - you can only access your own data and the data of any descendant organizations. ```http theme={null} X-API-Key: pc_live_1234567890abcdef ``` ## Issuing and rotating keys 1. From the dashboard, go to **Admin → API**. 2. Click **New Key**. Give it a descriptive name (e.g. "Production CRM sync", "Staging analytics export"). The key is shown only once - copy it immediately and store it in a secret manager. 3. To rotate, generate a new key, swap it into your deployed apps, verify traffic on the new key, then revoke the old one. 4. To revoke compromised keys, click **Revoke** - the key stops working immediately. > [!WARNING] > > **Store API keys in environment variables or secret management systems.** Never commit keys to version control or ship them in client-side code. Rotate regularly; revoke compromised keys immediately. ## Scoping API keys are scoped to your organization's hierarchy. A key issued at the parent organization can read data from all descendant organizations; a key issued at a sub-org can only read data within that sub-org and its descendants. Cross-tree access is never possible. Errors you'll see if scoping blocks a request: | Code | Meaning | | - | - | | `INVALID_API_KEY` | Key is missing, malformed, or has been revoked. | | `ORG_ACCESS_DENIED` | The `organization_id` you requested is not in your accessible hierarchy. | | `PERMISSION_DENIED` | Your key is valid but lacks the permission scope this endpoint requires. | See the [Errors](/api-reference/errors) page for the full list of error codes. ## Per-key best practices * **Separate keys per environment.** Production, staging, and local dev should have distinct keys. * **Separate keys per integration.** Your CRM sync, your analytics export, and your internal admin tool should each have their own key. If one is compromised you can revoke it without breaking the others. * **Audit usage.** The dashboard shows request counts and last-used timestamps per key. Investigate keys that haven't been used in 30+ days - they're often candidates for deletion. ## Authenticating as an AI agent AI agents authenticate the same way as any other server-to-server integration: an API key in the `X-API-Key` header. There is no separate agent credential type. A machine-readable version of this walkthrough is published at [politicalcomms.com/auth.md](https://politicalcomms.com/auth.md). **1. Have a human operator provision the key** Key creation is not an API operation. A human operator generates the key in the dashboard under **Admin → API**, copies it (it is shown only once), and provisions it to the agent through a secret manager or environment variable. Keys never belong in prompts, code, or version control. **2. Send the key on every request** Pass the key in the `X-API-Key` header on every request to `https://api.politicalcomms.com/v1`. ```http theme={null} X-API-Key: pc_live_1234567890abcdef ``` **3. Verify the credential** Confirm the key works with a read-only call before doing anything else. `GET /organizations` has no side effects and returns the organizations the key can access. ```bash curl theme={null} curl https://api.politicalcomms.com/v1/organizations \ -H "X-API-Key: $POLCOMMS_API_KEY" ``` A `200` response with `"success": true` means the key is valid and scoped correctly. **4. Handle 401 and 429 responses** * `401` means the key is missing, malformed, or revoked. Do not retry. Surface the failure to the operator so they can issue a new key. See [Errors](/api-reference/errors). * `429` means the key hit its rate limit (600 requests per minute per key). Read the `Retry-After` header and back off for that many seconds before retrying. See [Rate Limits](/api-reference/rate-limits). **5. Verify webhook deliveries** Webhook payloads are HMAC-SHA256 signed. Validate the `X-Webhook-Signature: sha256=...` header before trusting any payload. See [Signature validation](/api-reference/webhooks/signature-validation). > [!NOTE] > > Platform status is published at [status.politicalcomms.com](https://status.politicalcomms.com). Check it before treating repeated failures as a credential problem. ## Machine-to-machine (M2M) authentication API keys are the machine-to-machine credential for the Political Comms API. Any unattended integration, whether a cron job, a backend service, a service account, or an autonomous AI agent, authenticates the same way: a `pc_live_` key in the `X-API-Key` header. There is no OAuth 2.0 client credentials grant, no token endpoint, and no dynamic client registration. Do not attempt an OAuth flow against `api.politicalcomms.com`; it does not exist. The API also does not publish `/.well-known/oauth-authorization-server` or `/.well-known/oauth-protected-resource` metadata. Treat one dedicated key per agent or service as the service account for that integration, so it can be rotated or revoked independently of everything else. A step-by-step programmatic walkthrough for agents is published at [politicalcomms.com/auth.md](https://politicalcomms.com/auth.md), with a matching error recovery playbook at [politicalcomms.com/errors.md](https://politicalcomms.com/errors.md). ## What about user authentication? API keys are for **server-to-server** integrations. End-user (dashboard) authentication is handled separately via JWT in the Political Comms application and is not exposed through this API. If you're building a customer-facing app that needs to act as a specific user, contact support to discuss OAuth-based options. # Best Practices Source: https://docs.politicalcomms.com/api-reference/best-practices API key security, caching recommendations, rate limit strategies, carrier throughput limits, and date range optimization. ## API key security * Store API keys in environment variables or secret management systems. * Never commit API keys to version control or expose them in client-side code. * Rotate API keys regularly and immediately revoke compromised keys. * Use separate API keys for different applications and environments. ## Caching recommendations * Cache hierarchy data for **5–10 minutes** (changes infrequently). * Cache historical project/message stats for **completed date ranges** indefinitely. * Use shorter TTLs (**1–2 minutes**) for current-day statistics. * Implement cache invalidation when you detect data changes. ## Rate limiting strategies * Monitor `X-RateLimit-Remaining` on every response. * Implement **exponential backoff** for `429` responses. * Use caching to reduce the number of API calls needed. * Batch operations when possible (e.g., query larger date ranges). ## Carrier throughput limits Carriers limit how fast a brand can send. Two matter for API projects: * **T-Mobile daily cap.** T-Mobile caps the message parts (160-character SMS segments; a three-part text spends three) a brand can send per day. This applies to brands that have a T-Mobile daily limit on file (political brands verified through Campaign Verify do not have one today), and the cap resets at midnight Pacific. The cap is a speed limit, not a stop. Past it, T-Mobile recipients and recipients with an unknown carrier keep sending at a reduced rate (about 300 message parts per minute per campaign) while the platform watches delivery receipts. Once about 300 over-cap receipts for the campaign have come back with under 5% failures, the rate rises to about 3,000 parts per minute. Recipients on other carriers are never slowed. Only the carrier pauses a project: if T-Mobile rejects messages over the cap, the project auto-pauses with `pause_reason` `brand_daily_cap` (see "Past the cap" below). Run list analysis first (`POST /contact-lists/{id}/analyze`) and only T-Mobile recipients are affected, because no carrier is unknown. * **AT\&T per-minute rate.** AT\&T limits message parts per minute per campaign, with separate SMS and MMS rates. AT\&T counts each part of a text: a text that fits in one part counts once, and a longer text that splits into 2 or 3 parts counts 2 or 3 times. A picture message (MMS) counts once against the MMS rate. Every 10DLC campaign with an AT\&T rate on file has its AT\&T traffic delivered at that rate, whatever the brand type. The platform sends AT\&T recipients right away and the carrier queue delivers them at that rate, usually within about an hour; only in the last 90 minutes of the recipients' sending window does the platform hold back AT\&T recipients that could not be delivered before the window closes. A campaign with no rate on file has no AT\&T rate applied. Recipients on other carriers are never slowed by it, and it never pauses a project. Analysis is optional, but a list cannot be used while it is running: start the analysis, wait for `analysis.status` `complete` or the `contact_list.analyzed` webhook, then create or schedule the project (until then the API returns `409` `LIST_ANALYSIS_IN_PROGRESS`). A list that was never analyzed sends to every number on it; an analyzed list sends to wireless numbers only. The two lanes are independent: a campaign can have one without the other. A political (Campaign Verify) brand has an AT\&T rate but no T-Mobile daily limit today, and a brand can also lack a T-Mobile limit because it has not synced yet. For how this looks in the dashboard and how to finish a large send sooner, see [Sending speed and carrier limits](/help/sending-speed). **Check before you schedule.** `GET /campaigns/{id}/throughput` returns the brand's daily cap, how much is used today, and the AT\&T rates. `t_mobile` is `null` until a T-Mobile daily cap has synced for the campaign, and `att` is `null` only when the campaign has no AT\&T rate on file (inside `att`, `sms_tpm` and `mms_tpm` can each be `null`, one per message type). `t_mobile` is also `null` when the brand has no T-Mobile daily limit on file. `carrier_metered` is `true` if either lane applies; a campaign with neither returns `false` with both `null`. A political brand with an AT\&T rate returns `carrier_metered: true`, `t_mobile: null` and a populated `att`. `GET /projects/{id}/throughput` estimates how a specific project will fare: `t_mobile.estimated_recipients`, `att.estimated_minutes`, and the daily cap figures. A `null` means the number is not known right now (for example, today's usage is temporarily unavailable); it is never zero. `t_mobile.will_pause` is always `false` and `t_mobile.estimated_send_days` is always `1`: the fields remain for compatibility, because a project no longer pauses on the cap arithmetic. When `carrier_coverage` is low, the estimates use the platform-wide carrier split rather than your recipients' actual carriers. Project estimates are cached for up to 60 seconds, so numbers can lag by that much. If the estimate query times out, the endpoint returns `503` with code `CARRIER_ESTIMATE_TIMEOUT`; retry later. **Poll for `paused`, not just `completed`.** `GET /projects/{id}` returns `status`, `pause_reason`, and `auto_paused`. A project with `status: paused` and `pause_reason: brand_daily_cap` was paused because T-Mobile rejected messages over the cap, not because it is stuck. Call `POST /projects/{id}/schedule` with a morning `scheduled_at` inside the next day's sending hours to wait for the reset at midnight Pacific, or call it without one to try T-Mobile again now. A poller that waits only for `completed` will time out on a large send. Known `pause_reason` values: | Value | Meaning | | - | - | | `brand_daily_cap` | T-Mobile rejected messages over the brand's daily cap, so the T-Mobile lane is closed for the rest of the Pacific day. Schedule it for the next day's sending hours with `POST /projects/{id}/schedule` (morning `scheduled_at`), or call it without one to reopen the lane and try T-Mobile again at the reduced rate. | | `quiet_hours` | Paused when the project's sending window closes: 10 PM in the time zone of most recipients, or 10 PM Pacific when no time zone holds a majority. Restart manually once the window opens (8 AM Eastern when no time zone holds a majority). | | `carrier_block_rate` | Carriers were blocking too many messages. | | `unregistered_campaign` | The sending campaign is not registered. | | `provider_error` | The messaging provider reported a critical error. | | `insufficient_funds_auto_recharge_failed` | The wallet ran out and auto-recharge failed. | | `insufficient_funds_ancestor` | A parent organization's wallet ran out. | | `shared_phone_revoked` | A shared sending number was revoked. | | `phone_released` | A sending number was released. | | `organization_deleted` | The organization was deleted. | | `manual` or free text | A user paused the project in the dashboard or over the API (`POST /projects/{id}/pause`, optional `reason`). Free text is a short reason of up to 100 characters. Resume it with `POST /projects/{id}/schedule`. To edit it first (including its channel, brand, campaign, or numbers), `PATCH /projects/{id}`, then `POST /projects/{id}/test`, then schedule. | Other values may appear. Every automatic pause needs a manual restart via `POST /projects/{id}/schedule`. **Past the cap.** Past the daily cap, T-Mobile recipients send at the reduced rate described above, and the platform watches the receipts. T-Mobile rejecting messages over the cap (error code `016` on the receipt, or any failure code at a high rate: 20 or more failures that are at least half of the newest three minutes of T-Mobile receipts for the campaign) closes that campaign's T-Mobile lane for the rest of the Pacific day. The campaign's projects then auto-pause with `pause_reason` `brand_daily_cap` once only T-Mobile and unknown-carrier recipients remain, and `auto_paused` is `true`. Rejected messages are still billed. Resume with `POST /projects/{id}/schedule`. With a morning `scheduled_at` it waits for the reset at midnight Pacific, which is the right call when you want to wait. Without one it reopens the campaign's T-Mobile lane and tries T-Mobile again at the reduced rate; the project pauses again if T-Mobile is still rejecting. Send `daily_cap_bypass: true` on `POST /projects/{id}/schedule` to skip the reduced rate and send T-Mobile recipients at full speed past the cap. A carrier rejection still pauses a bypassed project. The setting holds until the next schedule or resume call rewrites it, so send it on every schedule or resume call you want it to apply to. `GET /projects/{id}` returns the current value as `daily_cap_bypass`. Failed messages over the cap report error code `016` (see [error codes](/api-reference/webhooks/error-codes)). ## Date range optimization * Use the **maximum 31-day range** when fetching historical data. * Request only the specific date ranges you need. * Use hierarchy filters (`organization_id`, `brand_id`, `campaign_id`) to reduce data volume. * Cache aggregated results for reporting dashboards. ## Webhook reliability * Return `200` within **10 seconds** (process asynchronously if needed). * Always validate the **HMAC signature** before processing. * Use `event_id` to **deduplicate** (rare but possible). * Log failures and monitor your endpoint health. * Use **HTTPS** endpoints (required in production). * **Rotate secrets** periodically (every 90 days recommended). # Get Usage Source: https://docs.politicalcomms.com/api-reference/billing/get-usage /api-reference/openapi.json get /ledger/usage 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. A `brandId` or `campaignId` outside your organizations returns 404 BRAND_NOT_FOUND or CAMPAIGN_NOT_FOUND, the same as an unknown id. # Get Usage by Initiator Source: https://docs.politicalcomms.com/api-reference/billing/get-usage-by-initiator /api-reference/openapi.json get /ledger/usage/by-initiator 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. # List Brands Source: https://docs.politicalcomms.com/api-reference/brands/list-brands /api-reference/openapi.json get /brands List all brands. Optionally filter by organization. # Analyze Contact List Source: https://docs.politicalcomms.com/api-reference/contact-lists/analyze-contact-list /api-reference/openapi.json post /contact-lists/{id}/analyze 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 call is not charged twice. Returns immediately with `202` and the `cost_cents` and `numbers_queued` for the run. If nothing is left to analyze it returns `200` with `analysis.status` `complete`, `numbers_queued` 0 and `cost_cents` 0. If analysis is already running it returns `202` with `cost_cents` 0 and charges nothing. Poll `GET /contact-lists/{id}` until `analysis.status` is `complete`, or subscribe to the `contact_list.analyzed` webhook, then fetch the results with `GET /contact-lists/{id}/download?type=analyzed`. A project cannot be created, updated with, or scheduled on a list whose analysis is in progress; the request fails with `409` `LIST_ANALYSIS_IN_PROGRESS`. # Delete Contact List Source: https://docs.politicalcomms.com/api-reference/contact-lists/delete-contact-list /api-reference/openapi.json delete /contact-lists/{id} Permanently remove a list from your account, with its phone numbers and its emails (a list's emails share its id on `/email/lists/{id}`). The list is detached from any draft projects that reference it and no longer appears in list or read endpoints. A WinRed or Anedot list's donation feed is disconnected with it. Deletion is blocked with a 409 while a scheduled, sending, or active project depends on the list; unschedule the project or wait for the send to finish, then retry. # Get Contact List Source: https://docs.politicalcomms.com/api-reference/contact-lists/get-contact-list /api-reference/openapi.json get /contact-lists/{id} 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. `channels` says whether the list has phone numbers, emails, or both; a list's emails are read on `GET /email/lists/{id}` with the same id. # Import List Source: https://docs.politicalcomms.com/api-reference/contact-lists/import-list /api-reference/openapi.json post /contact-lists/import The one list import: phones, emails, or both from one CSV you host. The platform fetches `source_url` (HTTPS only, at most 50 MB, `text/csv`, `application/csv`, or `text/plain`), checks the columns you named against the file's headers, and returns `202` before writing a row. Nothing is written when a check fails. **Columns.** Send `phone_column`, `email_column`, or both (they must differ). There is no automatic email-column detection: name the column. Without `merge_tags`, every column other than the chosen ones becomes a merge tag automatically. With `merge_tags`, phone numbers map only the columns you name, while emails map the named columns and also every remaining column by its default name. Custom field names for emails must match `^[a-z][a-z0-9_]{0,63}$`. **Purpose.** `audience` (the default) makes ONE list. Its phone numbers are polled on `GET /contact-lists/{id}` and its emails on `GET /email/lists/{id}` with the same id (status `processing` until `ready` or `failed`, with counts and `removed_at_upload`). An email-only audience is organization-wide even when you send `brand_id`. `consent` (where the addresses came from) is optional: it is allowed only for an audience with an `email_column`, and any other combination returns `400`. Omit it and no consent record is stored. Unknown top-level fields in the request body are ignored; unknown keys inside `merge_tags` and `consent` return `400`. Every refusal happens before anything is stored. `do_not_contact` adds the phone numbers to an opt-out list and records the emails as unsubscribes for the organization; the unsubscribes appear on `GET /email/suppressions` once the background job finishes (minutes for a large file). A do-not-contact import returns no `list_id`. **Email access.** `email_column` requires email to be enabled for the organization; otherwise the request returns `403` `ENTITLEMENT_REQUIRED`. **Replaces `POST /email/lists/import`**, which was removed. To migrate: send `name` as `list_name` (now required); the `mapping` entry whose value is `email` becomes `email_column`; other `mapping` entries become `merge_tags`; `consent`, `email_domain_id`, and `acquired` carry over unchanged. # List Contact Lists Source: https://docs.politicalcomms.com/api-reference/contact-lists/list-contact-lists /api-reference/openapi.json get /contact-lists List contact lists. Filter by organization or brand. By default only lists with phone numbers (and lists that have no emails) are returned, as before; send `channel=email` for lists with emails, or `channel=all` for every list. Each list reports its `channels`. # Create Campaign Source: https://docs.politicalcomms.com/api-reference/email-campaigns/create-campaign /api-reference/openapi.json post /email/campaigns Create a draft campaign. # Get Campaign Source: https://docs.politicalcomms.com/api-reference/email-campaigns/get-campaign /api-reference/openapi.json get /email/campaigns/{id} 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. # Get Campaign Stats Source: https://docs.politicalcomms.com/api-reference/email-campaigns/get-campaign-stats /api-reference/openapi.json get /email/campaigns/{id}/stats 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 Campaigns Source: https://docs.politicalcomms.com/api-reference/email-campaigns/list-campaigns /api-reference/openapi.json get /email/campaigns List email campaigns. # Schedule Campaign Source: https://docs.politicalcomms.com/api-reference/email-campaigns/schedule-campaign /api-reference/openapi.json post /email/campaigns/{id}/schedule Schedule the campaign, or omit `scheduled_at` to send now. Sending now returns the campaign already `compiling`, or `scheduled` when it is outside its send window (it starts when the window opens). 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 Source: https://docs.politicalcomms.com/api-reference/email-campaigns/unschedule-campaign /api-reference/openapi.json post /email/campaigns/{id}/unschedule Return a scheduled campaign to a draft state. # Add Contacts Source: https://docs.politicalcomms.com/api-reference/email-lists/add-contacts /api-reference/openapi.json post /email/lists/{id}/contacts 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. Yahoo-run mailboxes (Yahoo, AOL, AT&T, Verizon, Cox, Frontier) are never added to a list and come back `rejected` with reason `yahoo_family`. Recipients at providers whose mailboxes report spam at an unusually high rate (currently windstream.net) are never added either and come back `rejected` with reason `high_complaint_domain`. Both are the same rules every upload applies. # Create Email List Source: https://docs.politicalcomms.com/api-reference/email-lists/create-email-list /api-reference/openapi.json post /email/lists Create an email list. `consent_attestation` is required: you are recording how the people on this list agreed to hear from you. The list is also a list on the dashboard's Lists page, and its id works on `/contact-lists/{id}`. Names do not have to be unique. To import a CSV with emails, use `POST /contact-lists/import` with `email_column`. # Get Email List Source: https://docs.politicalcomms.com/api-reference/email-lists/get-email-list /api-reference/openapi.json get /email/lists/{id} Fetch one email list with its contact counts. # List Contacts Source: https://docs.politicalcomms.com/api-reference/email-lists/list-contacts /api-reference/openapi.json get /email/lists/{id}/contacts List the contacts on an email list. # List Email Lists Source: https://docs.politicalcomms.com/api-reference/email-lists/list-email-lists /api-reference/openapi.json get /email/lists List the organization's email lists. # Get Sender Identity Source: https://docs.politicalcomms.com/api-reference/email-senders/get-sender-identity /api-reference/openapi.json get /email/senders/{id} Fetch one sender identity. # List Sender Identities Source: https://docs.politicalcomms.com/api-reference/email-senders/list-sender-identities /api-reference/openapi.json get /email/senders List every sender identity in the organization. This endpoint is not paginated: `has_more` is always `false`. # Add Suppressions Source: https://docs.politicalcomms.com/api-reference/email-suppressions/add-suppressions /api-reference/openapi.json post /email/suppressions Suppress up to 5,000 addresses in one call. Malformed addresses are reported in `invalid` rather than failing the batch. # List Suppressions Source: https://docs.politicalcomms.com/api-reference/email-suppressions/list-suppressions /api-reference/openapi.json get /email/suppressions List the addresses that will not be emailed: unsubscribes, bounces, complaints, and addresses you or a do-not-contact import added. # Remove Suppressions Source: https://docs.politicalcomms.com/api-reference/email-suppressions/remove-suppressions /api-reference/openapi.json delete /email/suppressions Lift suppressions on up to 5,000 addresses. Removing an address that was not suppressed is not an error. # Create Email Template Source: https://docs.politicalcomms.com/api-reference/email-templates/create-email-template /api-reference/openapi.json post /email/templates 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 Source: https://docs.politicalcomms.com/api-reference/email-templates/get-email-template /api-reference/openapi.json get /email/templates/{id} Get one template, including its HTML. # List Email Templates Source: https://docs.politicalcomms.com/api-reference/email-templates/list-email-templates /api-reference/openapi.json get /email/templates List the organization's email templates, newest first. # Error Handling Source: https://docs.politicalcomms.com/api-reference/errors Conventional HTTP response codes with a structured error object containing code, message, and additional context. The API uses conventional HTTP response codes. Error bodies come in three shapes depending on which layer rejects the request. ## Error response shapes **Standard errors** (validation failures, missing resources, state conflicts, server errors) return a flat body with a machine-readable `code` and a `correlationId` you can quote to support. Some codes also include `details`. For `VALIDATION_ERROR` it is an array with one entry per rejected field, where `field` is the dotted path into the request body or parameters: ```json theme={null} { "error": "Validation failed", "code": "VALIDATION_ERROR", "correlationId": "01JZWX3F9G2K4M6P8R0T2V4X6Y", "details": [ { "field": "organization_id", "message": "Invalid UUID", "code": "invalid_format" } ] } ``` **Authentication and permission errors** from the API-key layer (`401`, and `403` when the key lacks a scope) use a simpler two-field body with no `code`: ```json theme={null} { "error": "API key required", "message": "Please provide an API key in the X-API-Key header" } ``` **Rate-limit errors** (`429`) include `retryAfter` in the body and a `Retry-After` header: ```json theme={null} { "success": false, "error": "Rate limit exceeded", "message": "Maximum 600 requests per 60 seconds", "code": "RATE_LIMIT_EXCEEDED", "statusCode": 429, "retryAfter": 3 } ``` ## HTTP status codes | Status | Meaning | | - | - | | `200` | **Success** - Request completed successfully. | | `400` | **Bad Request** - Invalid parameters or malformed request. | | `401` | **Unauthorized** - Missing or invalid API key. | | `403` | **Forbidden** - API key lacks required permissions or access denied. | | `402` | **Payment Required** - The wallet cannot cover the operation (`INSUFFICIENT_BALANCE`). Add funds and retry. | | `404` | **Not Found** - Resource does not exist. | | `409` | **Conflict** - Resource is in the wrong state for the request (for example scheduling a project that is not ready, requesting survey results for a broadcast project, or retrying an idempotent write that is still processing). | | `422` | **Unprocessable** - The request was understood but can't be executed (for example reusing an `Idempotency-Key` with a different body, or scheduling with insufficient balance). | | `429` | **Too Many Requests** - Rate limit exceeded. See [Rate Limits](/api-reference/rate-limits). | | `500` | **Internal Server Error** - Something went wrong on our end. | ## Common error codes | Code | Description | | - | - | | `VALIDATION_ERROR` | Request parameters or body failed validation. `details` is an array of `{ field, message, code }`, one per rejected field. | | `ORG_ACCESS_DENIED` | Requested organization is not in your accessible hierarchy. | | `ONBOARDING_INCOMPLETE` | `403`. The organization's 14-day onboarding grace window has passed and the business profile or funding step (see [Account Setup](/onboarding/account-setup)) is still incomplete. Returned on requests that create new resources: brands, campaigns, toll-free verifications, phone number purchases, email domains and senders, projects and project copies, and email campaigns and duplicates, including `POST /v1/projects`, `POST /v1/projects/{id}/copy`, and `POST /v1/email/campaigns`. `details` includes `missingSteps` (an array containing `profile`, `funding`, or both) and `onboardingUrl` (`/onboarding`). Nothing already running is affected, only new creates are blocked. | | `ENTITLEMENT_REQUIRED` | `403`. The organization is not entitled to this feature; some features require enablement by Political Comms. Returned on every write (`POST`/`PUT`/`PATCH`/`DELETE`) under `/v1/email/*`, and on `POST /v1/contact-lists/import` with an `email_column`. `details` includes `entitlement`, the entitlement key that is missing (`tendlc`, `toll_free`, `short_code`, `data_purchases`, `email`, `stripe_connect`, `phone_number_sharing`, or `sub_orgs`). Contact support to request enablement. | | `SENDING_PAUSED` | `409`. Sending is paused for the organization or platform-wide, by Political Comms. Returned on `POST /v1/projects`, `POST /v1/projects/{id}/schedule`, `POST /v1/conversations/{id}/messages`, and `POST /v1/email/campaigns/{id}/schedule`. `details` includes `scope` (`organization` or `platform`). | | `MEDIA_NOT_USABLE` | `400`. A `media_ids` entry on `POST /v1/conversations/{id}/messages` is not in the conversation's organization, is not ready, or belongs to a different brand than the project's. Nothing was charged. | | `RATE_LIMIT_EXCEEDED` | Too many requests - wait for the `Retry-After` seconds before retrying. | | `INVALID_STATE_TRANSITION` | Project is not in a state that allows this operation. `POST /v1/projects/{id}/schedule` accepts `ready` and `paused` projects. | | `NOT_A_SURVEY` | The endpoint only applies to survey projects (`type: survey`). | | `LIST_NOT_READY` | Contact list must finish importing before it can be analyzed. | | `ANALYSIS_NOT_COMPLETE` | `409`. `GET /v1/contact-lists/{id}/download?type=analyzed` was requested before analysis finished. Poll `GET /v1/contact-lists/{id}` until `analysis.status` is `complete`, or subscribe to the `contact_list.analyzed` webhook. | | `LIST_ANALYSIS_IN_PROGRESS` | `409`. `POST /v1/projects`, the project update endpoint, or `POST /v1/projects/{id}/schedule` referenced a contact list whose analysis is still running (`analysis.status` `processing`). Nothing is changed. `details.lists` is an array of `{ id, name, status }` for each list still in analysis. Wait for `analysis.status` `complete` on `GET /v1/contact-lists/{id}` or the `contact_list.analyzed` webhook, then retry the same request. | | `INSUFFICIENT_BALANCE` | A wallet in the organization hierarchy cannot cover the scheduled send (`422` on schedule) or the list analysis (`402` on `POST /v1/contact-lists/{id}/analyze`, with nothing queued). This may be a **parent** organization rather than the one you called with - charges roll up, so every ancestor must cover its own share. `details` includes the shortfall plus `organizationId` and `organizationName` identifying which organization fell short, `actingOrganizationId` (the organization the call was made for) and `isAncestor` (`true` when the short wallet belongs to a parent of the acting organization). | | `CONVERSATION_NOT_FOUND` | `404`. The conversation does not exist or belongs to an organization outside the key's hierarchy; the two are indistinguishable by design. | | `CONTACT_OPTED_OUT` | `409`. The contact replied STOP; a reply to this conversation is refused before any charge. Final: do not retry. | | `CONVERSATION_NOT_SENDABLE` | `409`. The conversation has no sending number bound to it, so nothing can reply from it. | | `PROJECT_DELETED` | `409`. The project behind the conversation was deleted. | | `PHONE_NUMBER_UNAVAILABLE` | `409`. The conversation's sending number was released or is inactive. | | `SEND_ENQUEUE_FAILED` | `503`. A reply could not be handed to the delivery queue after billing; the charge was reversed and nothing was sent. Retry the same call. | | `CARRIER_ESTIMATE_TIMEOUT` | `503`. The carrier throughput estimate for `GET /v1/projects/{id}/throughput` timed out and had no effect. Retry later. | | `MIXED_PHONE_OWNERSHIP` | `400`. A project's `phone_number_ids` mixed numbers the organization owns with numbers shared with it, or shared numbers from two different campaigns or registrations. Select numbers from one source. | | `PHONE_SHARE_REVOKED` | `409`. A number the project selects was shared with the organization and the share has been revoked (or the number released). Choose a different number. | | `IDEMPOTENCY_CONFLICT` | The same `Idempotency-Key` is still processing - retry after the `Retry-After` seconds. | | `IDEMPOTENCY_MISMATCH` | An `Idempotency-Key` was reused with a different request body - that's a client bug; use a fresh key for new requests. | | `DATE_RANGE_TOO_LARGE` | Date range exceeds the maximum allowed (31 days). | | `DATE_TOO_OLD` | Start date exceeds the look-back limit: 180 days for `/messages/stats` and `/ledger/*`, 90 days for `/projects/stats`. | | `FUTURE_DATE_NOT_ALLOWED` | Date range may not end in the future. | | `INVALID_DATE_FORMAT` | Date parameter must be in `YYYY-MM-DD` format. | ## Email error codes Write endpoints under `/v1/email/*` require the email entitlement on the organization and return `403 ENTITLEMENT_REQUIRED` without it, as does `POST /v1/contact-lists/import` with an `email_column`. Reads are open. These are the codes specific to the email surface. | Code | Status | Description | | - | - | - | | `EMAIL_SENDING_PAUSED` | `409` | Sending is paused for this sender identity or organization. | | `POOL_CAPACITY_EXHAUSTED` | `409` | The dedicated sending pool cap has been reached. Contact support. | | `POOL_ALREADY_ACTIVE` | `409` | This sending domain already has a dedicated sending pool, so the request did nothing. | | `DOMAIN_NOT_ACTIVE` | `409` | Verify the domain before turning on dedicated sending. | | `DMARC_ROOT_DOMAIN_NOT_MANAGED` | `409` | Your organizational root domain publishes a DMARC record we do not manage, so we cannot stage the change. Edit that record yourself. | `DMARC_ROOT_DOMAIN_NOT_MANAGED` is never resolved by retrying. Surface it to a human. Note that `401` responses and permission-scope `403` responses come from the authentication layer and carry no `code` field (see the shapes above). ## Retrying safely * All `GET` endpoints are safe to retry - they have no side effects. * For `POST` and `PATCH`, retry only on `429`, `500`, `502`, `503`, and `504` responses. Don't retry on `400`, `401`, `403`, or `404` - those indicate a problem with your request that won't be fixed by trying again. * If you need stronger duplicate-write protection, send a unique `Idempotency-Key` header (16-200 printable ASCII characters; a UUID is recommended) on every write request. Retried calls with the same key within 24 hours return the cached response from the first call, marked with an `X-Idempotent-Replayed: true` response header. Reusing a key with a different body returns `422` (`IDEMPOTENCY_MISMATCH`). ## How agents should recover Unattended integrations and AI agents should encode this recovery matrix rather than treating all failures alike: | Status | Retry? | Recovery action | | - | - | - | | `400` | Never | Fix the request parameters. Check `code` for specifics. | | `401` | Never | Credential is missing or revoked. Escalate to a human operator; keys are created in the dashboard, not over the API. | | `403` | Never | Stay inside the key's organization hierarchy or request a key with the right scope. | | `404` | Never | Verify the resource ID against a fresh list call. | | `429` | After waiting | Sleep for the `Retry-After` seconds. Never retry tighter than once per second. | | `500`-`504` | With backoff | Exponential backoff with jitter: 1 second base, double each attempt, 60 second cap, give up after 5 attempts. | Before treating repeated `5xx` failures as your bug, check [status.politicalcomms.com](https://status.politicalcomms.com). A standalone machine-readable version of this playbook is published at [politicalcomms.com/errors.md](https://politicalcomms.com/errors.md). ## Reporting bugs If you see a `500` response or a `code` that's not documented here, please email [support@politicalcomms.com](mailto:support@politicalcomms.com) with: * Your request method and path * The full response body, including the `correlationId` field (we use it to look up server-side logs; it is also sent as the `X-Correlation-ID` response header) * Approximate timestamp (UTC is easiest) # Introduction Source: https://docs.politicalcomms.com/api-reference/introduction Public REST API for integrating messaging data, project statistics, and billing into your stack. The Political Comms API is a RESTful interface for integrating messaging data, project statistics, contact and media management, and billing into your application. It's the same API that powers our own dashboard, so anything you can do in the UI you can also do programmatically. > [card] [Authentication](/api-reference/authentication) > > Authenticate with an API key passed in the `X-API-Key` header. > [card] [Webhooks](/api-reference/webhooks/overview) > > Stream real-time events into your CRM, warehouse, or alerting stack. > [card] [Rate limits](/api-reference/rate-limits) > > 600 requests per minute per API key. Headers tell you where you stand. > [card] [Errors](/api-reference/errors) > > Conventional HTTP status codes with structured error responses. ## Base URL ``` https://api.politicalcomms.com/v1 ``` Custom domains are supported for white-labeled deployments. If your organization has a custom API domain configured, use that as the base URL - the API surface is identical. ## 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: ```bash curl theme={null} curl https://api.politicalcomms.com/v1/organizations \ -H "X-API-Key: pc_live_1234567890abcdef" ``` ```javascript Node.js theme={null} const response = await fetch( 'https://api.politicalcomms.com/v1/organizations', { headers: { 'X-API-Key': process.env.POLCOMMS_API_KEY } } ); const { data } = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.get( 'https://api.politicalcomms.com/v1/organizations', headers={'X-API-Key': os.environ['POLCOMMS_API_KEY']} ) data = response.json()['data'] ``` **3. Subscribe to webhooks** Configure an HTTPS endpoint that receives [real-time events](/api-reference/webhooks/overview) for messages, replies, and link clicks. Always [validate the HMAC signature](/api-reference/webhooks/signature-validation) before trusting any payload. ## What you can do > [accordion] 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. > [accordion] 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. > [accordion] 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, send tests, and schedule for a specific time + timezone. > [accordion] 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. > [accordion] Stream events via webhooks > > Real-time notifications for `message.sent`, `message.delivered`, `message.failed`, `message.replied`, and `link.clicked`, plus `contact_list.analyzed` when a list finishes analysis - with HMAC-signed payloads and automatic retry. > [accordion] Send email > > Read sending domains and From addresses (both are set up in the dashboard), manage lists and suppressions, and build, schedule, and report on email campaigns under `/v1/email`. Five email webhook events (`email.delivered`, `email.bounced`, `email.complained`, `email.unsubscribed`, `email.clicked`) subscribe alongside the message events. > > 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`](https://www.npmjs.com/package/@political-comms/sdk), zero runtime dependencies) and Python ([`political-comms`](https://pypi.org/project/political-comms/)), alongside a CLI ([`@political-comms/cli`](https://www.npmjs.com/package/@political-comms/cli)) and an MCP server ([`@political-comms/mcp`](https://www.npmjs.com/package/@political-comms/mcp)) for agent clients — all from [Political-Comms/political-comms-sdk](https://github.com/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](https://www.usebruno.com/) 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](https://politicalcomms.com/openapi.json), announced in the [changelog](/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](/api-reference/versioning). ## Idempotency and consistency * All `GET` endpoints are safe to retry - they have no side effects. * All `POST` and `PATCH` endpoints 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 unique `Idempotency-Key` header 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. # Delete Media File Source: https://docs.politicalcomms.com/api-reference/media-files/delete-media-file /api-reference/openapi.json delete /media/{id} 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 active project uses the file; unschedule the project or wait for the send to finish, then retry. # Get Media File Source: https://docs.politicalcomms.com/api-reference/media-files/get-media-file /api-reference/openapi.json get /media/{id} Fetch a single media file including optimization status and metadata. # Import Media Source: https://docs.politicalcomms.com/api-reference/media-files/import-media /api-reference/openapi.json post /media 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`. # List Media Files Source: https://docs.politicalcomms.com/api-reference/media-files/list-media-files /api-reference/openapi.json get /media List all media files. Filter by organization or brand. # Get Hierarchy Source: https://docs.politicalcomms.com/api-reference/organizations/get-hierarchy /api-reference/openapi.json get /hierarchy 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. # List Organizations Source: https://docs.politicalcomms.com/api-reference/organizations/list-organizations /api-reference/openapi.json get /organizations List all descendant organizations accessible to your API key. # List Phone Numbers Source: https://docs.politicalcomms.com/api-reference/phone-numbers/list-phone-numbers /api-reference/openapi.json get /phone-numbers 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 for 10DLC numbers and null for toll-free; `toll_free_verification_id`/`toll_free_registration_name`/`tf_verification_status` are populated for toll-free numbers and null for 10DLC. Filter by organization, brand, or campaign (brand/campaign filters apply to 10DLC numbers only), and optionally by `channel` or `owner_type`. Numbers a parent organization shared with one of the key's organizations are included with `shared: true` and `nickname`; on those rows every owner-side name and `brand_id` is null. Sharing keeps billing and registration with the owner; see [Sharing phone numbers with sub-organizations](/help/shared-phone-numbers). # Copy Project Source: https://docs.politicalcomms.com/api-reference/projects/copy-project /api-reference/openapi.json post /projects/{id}/copy 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 as a `draft`. Attach contact lists via `PATCH /projects/{id}`, then test and schedule as usual. # Create Project Source: https://docs.politicalcomms.com/api-reference/projects/create-project /api-reference/openapi.json post /projects 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. **Phone numbers.** Assign one or more sending numbers via `phone_number_ids` (up to 49). The project spreads new conversations randomly across the assigned numbers, and once a recipient has been messaged from a given number every later message to that recipient comes from the same number (sticky sender). A single legacy `phone_number_id` is still accepted and is treated as a one-element `phone_number_ids`. **Channel.** `channel` defaults to `10dlc`. For broadcast projects a `10dlc` channel requires `brand_id` + `campaign_id` (and `toll_free_verification_id` must be omitted), while `toll-free` requires `toll_free_verification_id` with matching toll-free `phone_number_ids` (`brand_id`/`campaign_id` omitted). Survey projects always require `campaign_id`, on both channels. **Surveys.** `questions` defines the whole flow: an `intro` at sequence 1, then `multiple_choice`/`open_ended` questions, optionally ending with an `outro`. Multiple-choice options can branch with `next_sequence`, and `no_match_sequence` routes unmatched replies; both are forward-only. Each question can be SMS or MMS (`message_type` + `media_ids`). Media on a question must belong to the organization and fit the project's brand or registration, as intro media does; otherwise the request returns 400. Question text supports merge tags and `{tracking_url}`. Surveys need at least 2 questions and 1 phone number. When `link_tracking_enabled` is `true`, `link_tracking_destination_url` and `link_tracking_domain_id` become required. The destination URL may embed the selected `link_tracking_param_field` anywhere via a placeholder named after it, e.g. `https://test.com?utm_content=xyzd_{linkid}` redirects as `...utm_content=xyzd_ABC123` (no separate `&linkid=` pair is appended). Without a placeholder the field is appended as its own query pair. `link_tracking_destination_url` may also be exactly `https://{}`, e.g. `https://{custom_url}`; each recipient's tracking link then redirects to the URL stored in that contact field instead (`short_id` is still appended as a query param, but no `` query param is). In this mode `link_tracking_fallback_url` is required, and recipients whose field is empty or not a valid URL go there instead. `phone` cannot be used as a whole-URL destination, and a `{field}` token in the host position must be the entire URL (`https://{custom_url}/path` is rejected). A placeholder that does not match the selected field, or an invalid whole-URL form, is rejected with a 400 (`INVALID_LINK_PLACEHOLDER`). **Opt-out footer.** Broadcast messages automatically carry the `STOP=END` opt-out footer. Set `opt_out_footer_enabled` to `false` to disable it (defaults to `true`); surveys never carry the footer. **Drafts.** `contact_list_ids` is optional. With at least one list the created project starts in `awaiting_test` status (send a test, then schedule). Without it the project is created as a `draft`; attach lists later via `PATCH /projects/{id}` and the project moves to `awaiting_test` automatically. Drafts cannot be tested or scheduled. The response's `completeness` block shows what is still missing. # Get Project Source: https://docs.politicalcomms.com/api-reference/projects/get-project /api-reference/openapi.json get /projects/{id} Fetch a single project. Survey projects additionally include the ordered `questions` array; their `message_text`, `protocol`, and `media_urls` mirror the intro question. # Get Project Stats (all) Source: https://docs.politicalcomms.com/api-reference/projects/get-project-stats-all /api-reference/openapi.json get /projects/stats Aggregate per-project statistics for a date range (max 31 days, no older than 90 days). Results are paginated via limit/offset. # Get Project Stats (single) Source: https://docs.politicalcomms.com/api-reference/projects/get-project-stats-single /api-reference/openapi.json get /projects/{id}/stats 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 Source: https://docs.politicalcomms.com/api-reference/projects/get-project-throughput /api-reference/openapi.json get /projects/{id}/throughput Pre-flight estimate of how carrier limits will affect this project: recipients expected on T-Mobile and AT&T, and how many minutes the AT&T send needs. `t_mobile` is null when the brand has no T-Mobile daily limit on file (political brands today), and `att` is null only when the campaign has no AT&T rate on file. `t_mobile.will_pause` is always false and `t_mobile.estimated_send_days` is always 1; the fields remain for compatibility. Results are cached for up to 60 seconds, so numbers can lag by that much. Returns 503 `CARRIER_ESTIMATE_TIMEOUT` if the estimate query times out; retry later. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). # Get Survey Results Source: https://docs.politicalcomms.com/api-reference/projects/get-survey-results /api-reference/openapi.json get /projects/{id}/survey-results 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. Returns `409` (`NOT_A_SURVEY`) when the project is not a survey. # List Projects Source: https://docs.politicalcomms.com/api-reference/projects/list-projects /api-reference/openapi.json get /projects List all projects (broadcast and survey). Filter by organization, brand, campaign, or project type. # Pause Project Source: https://docs.politicalcomms.com/api-reference/projects/pause-project /api-reference/openapi.json post /projects/{id}/pause Stop a project that is `active`, `sending`, or `scheduled`. The project moves to `paused` with `pause_reason` set to `manual`, or to the `reason` you send. Messages already handed to the carriers finish; everything else holds. A project that is already `paused` returns 200 with its current `pause_reason` (for example `brand_daily_cap`), so a retry or a pause of an auto-paused project is harmless. Pausing a `scheduled` project keeps its `scheduled_at`; the next schedule call replaces it. To resume, call `POST /projects/{id}/schedule` with a `scheduled_at` of now or later (and `daily_cap_bypass` if you want T-Mobile recipients at full speed past the cap). There is no separate resume endpoint. A paused project can also be edited with `PATCH /projects/{id}` (including its sending setup); an edit moves it to `awaiting_test`, so resume with `PATCH`, then `POST /projects/{id}/test`, then `POST /projects/{id}/schedule`. Recipients already sent are never re-sent. Any other status returns `409` `INVALID_STATE_TRANSITION` with `details.allowed` naming the pausable statuses. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits) for the automatic pauses this call shares a status with. # Schedule Project Source: https://docs.politicalcomms.com/api-reference/projects/schedule-project /api-reference/openapi.json post /projects/{id}/schedule Transition a project to `scheduled` status. The project must be in `ready` or `paused` status; scheduling a `paused` project resumes it. Past the brand's T-Mobile daily cap (it resets at midnight Pacific), T-Mobile and unknown-carrier recipients keep sending at a reduced rate while the platform watches receipts; other carriers are never slowed. Only a carrier rejection pauses a project: it closes the campaign's T-Mobile lane for the Pacific day, and the project pauses with `pause_reason` `brand_daily_cap` once only those recipients remain. Do not resume at midnight. Schedule it for the next day during sending hours (the project's sending window: 8 AM to 10 PM in the time zone of most recipients, or 8 AM Eastern to 10 PM Pacific when no zone holds a majority) with a morning `scheduled_at`, or call this without one to reopen the lane and try T-Mobile again at the reduced rate (the project pauses again if T-Mobile is still rejecting; rejected messages are still billed). Running list analysis first means only T-Mobile recipients are affected. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). A project cannot be created, updated with, or scheduled on a list whose analysis is in progress; the request fails with `409` `LIST_ANALYSIS_IN_PROGRESS`. # Test Project Source: https://docs.politicalcomms.com/api-reference/projects/test-project /api-reference/openapi.json post /projects/{id}/test 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 that a real send would reach (the project's suppression lists, opt-out lists and global opt-outs apply), not from the request; for a survey, every question renders from that same contact. With no list, tags resolve as they would for a recipient with an empty field (inline fallback, then the organization default, then the standard platform default). Any contact in `test_contacts` can instead supply `merge_values`: when present, no contact is sampled from the project's lists for that entry, every merge tag renders from the supplied values, and a tag not supplied (or supplied empty) falls back the same way an empty field would. This also drives survey follow-up question rendering, and works whether or not the project has a contact list attached. # Unschedule Project Source: https://docs.politicalcomms.com/api-reference/projects/unschedule-project /api-reference/openapi.json post /projects/{id}/unschedule Transition a scheduled project back to `ready`. # Update Project Source: https://docs.politicalcomms.com/api-reference/projects/update-project /api-reference/openapi.json patch /projects/{id} Update a project while in `draft`, `awaiting_test`, `ready`, or `paused`. `organization_id` and `type` are immutable after creation; including them in the body returns a 400 `FIELD_NOT_EDITABLE`. All other fields are partial: send only the keys you want to change. The payload shape follows the project's `type`. For surveys, `questions` is a full replacement: sending it swaps the entire question set (same rules as create). Any edit moves the project to `awaiting_test` (re-test required), and back to pending approval if it was approved. **Changing the sending setup (broadcast projects).** `channel`, `brand_id`, `campaign_id`, and `toll_free_verification_id` are editable. When any of the four is present, the request must state the full sending setup for the effective channel (the `channel` you send, else the project's current channel) plus the numbers: `10dlc` requires `brand_id` and `campaign_id` (and no `toll_free_verification_id`); `toll-free` requires `toll_free_verification_id` (and no `brand_id` or `campaign_id`); `short-code` takes none of the three. `phone_number_ids` (or the legacy `phone_number_id`) is always required with a setup change, because a number belongs to exactly one campaign or toll-free registration. The checks match create: the brand must belong to the project's organization, the campaign must belong to that brand, and every toll-free number must be linked to the registration (error codes `BRAND_NOT_FOUND`, `BRAND_ACCESS_DENIED`, `CAMPAIGN_NOT_FOUND`, `CAMPAIGN_BRAND_MISMATCH`, `TOLL_FREE_REGISTRATION_NOT_FOUND`, `TOLL_FREE_REGISTRATION_ACCESS_DENIED`, `PHONE_NUMBER_REGISTRATION_MISMATCH`). A suspended campaign returns `409` `CAMPAIGN_SUSPENDED`, and an expired campaign returns `409` `CAMPAIGN_EXPIRED` (register a new campaign to use on the project). If the project's contact lists, suppression lists, or media belong to the old brand or registration, the request returns `400` `ASSET_OUT_OF_SCOPE`; send new `contact_list_ids`, `suppression_list_ids`, and `media_ids` in the same request. The brand follows the campaign; switching to `toll-free` or `short-code` clears the brand and campaign. Shape errors are validation errors, as on create. **Editing a paused project.** To resume after an edit: `PATCH` the project, then `POST /projects/{id}/test` (moves it to `ready`, or `awaiting_approval` when approval is required), then `POST /projects/{id}/schedule`. Recipients already sent are never re-sent. Any edit refunds every message the pause was holding, including any still waiting to go out, and the restart sends the edited message and sending setup to everyone not yet sent, billed once. # Rate Limits Source: https://docs.politicalcomms.com/api-reference/rate-limits 600 requests per minute per API key (bursts up to 600, refilling 10 per second), with X-RateLimit-* response headers and 429 backoff guidance. Each API key has a rate limit of **600 requests per minute**: bursts of up to 600 at once, refilling at 10 per second. The limit is the same whatever scopes the key holds. Keys with a custom limit keep that instead, and the `X-RateLimit-Limit` header on every response tells you your key's exact limit. ## How the limit works * **It counts requests, nothing else.** A call that lists a 10-contact audience and a call that imports a million contacts each cost one request. Payload size, list size, and message volume never count. * **Bursts are fine.** Think of a bucket holding 600 tokens; each request spends one, and tokens refill at 10 per second. You can send 600 at once, and after that you keep getting 10 per second rather than being locked out for the rest of the minute. A steady 10 per second never hits the limit. * **It is per key.** Each key has its own budget. If two systems share one key they share one budget; give each integration its own key. * **You can see it.** Admin > API > your key > usage shows total requests, success rate, and how many requests were rate limited. ```http theme={null} X-RateLimit-Limit: 600 X-RateLimit-Remaining: 598 X-RateLimit-Reset: 1640995260 ``` | Header | Meaning | | - | - | | `X-RateLimit-Limit` | Maximum requests allowed in the current window. | | `X-RateLimit-Remaining` | Requests you can send right now (tokens left in the bucket). | | `X-RateLimit-Reset` | Unix timestamp (seconds). On a normal response, when your full allowance is available again. On a `429`, when your next request will be allowed. | ## What happens at the limit When you hit the limit, subsequent requests return `429 Too Many Requests` with a `Retry-After` header: the seconds until your next request will be allowed. At the default limit that is about one second. If both `Retry-After` and `X-RateLimit-Reset` are present, `Retry-After` wins (it is relative, so a skewed clock cannot mislead you). The official SDKs already do this. ```http theme={null} HTTP/1.1 429 Too Many Requests Retry-After: 1 ``` ```json theme={null} { "success": false, "error": "Rate limit exceeded", "message": "Maximum 600 requests per 60 seconds", "code": "RATE_LIMIT_EXCEEDED", "statusCode": 429, "retryAfter": 1 } ``` ## Handling 429s correctly > [accordion] Monitor X-RateLimit-Remaining on every response > > Don't wait for a 429 - track the remaining counter and start backing off when it gets low (e.g. below 10). > [accordion] Implement exponential backoff for 429 responses > > Standard pattern: on 429, sleep for the `Retry-After` seconds (or for an initial delay of 1s, doubling each retry up to a cap). Retry the same request. Never retry tighter than once per second. > [accordion] Use caching to reduce API calls > > Cache hierarchy data for 5–10 minutes (it changes infrequently). Cache historical stats for completed date ranges indefinitely. > [accordion] Batch operations when possible > > Prefer one large date-range query over many small ones. Use hierarchy filters (`organization_id`, `brand_id`, `campaign_id`) to reduce data volume per request. > [accordion] Poll project stats no faster than they change > > `GET /v1/projects/{id}/stats` is cached for 15 seconds while a project is sending and 5 minutes once it is idle, so polling faster than that returns the same numbers for another request. For many projects at once, `GET /v1/projects/stats` with a date range returns them in one call. ## Need a higher limit? If your integration's design genuinely requires more than 600 requests/minute per key, contact [support@politicalcomms.com](mailto:support@politicalcomms.com) with details on your use case. We can issue keys with elevated limits for production integrations that demonstrate good caching and batching practices. # Get Sending Domain Source: https://docs.politicalcomms.com/api-reference/sending-domains/get-sending-domain /api-reference/openapi.json get /email/domains/{id} Fetch one sending domain, including the DNS records to publish and the per-signal verification state. # List Sending Domains Source: https://docs.politicalcomms.com/api-reference/sending-domains/list-sending-domains /api-reference/openapi.json get /email/domains List the organization's email sending domains, newest first. # Get Toll-Free Verification Source: https://docs.politicalcomms.com/api-reference/toll-free-verifications/get-toll-free-verification /api-reference/openapi.json get /toll-free-verifications/{id} Fetch a single toll-free verification, including the phone numbers it covers and any rejection reason. # List Toll-Free Verifications Source: https://docs.politicalcomms.com/api-reference/toll-free-verifications/list-toll-free-verifications /api-reference/openapi.json get /toll-free-verifications List toll-free verifications (the carrier registrations behind your toll-free numbers) across your organization hierarchy. Filter by organization or by submission status. # List Tracking Domains Source: https://docs.politicalcomms.com/api-reference/tracking-domains/list-tracking-domains /api-reference/openapi.json get /tracking-domains 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. # Two-Way Conversations Source: https://docs.politicalcomms.com/api-reference/two-way-conversations Answer inbound texts programmatically: receive message.replied, reply inside the same conversation from the same number, and recover missed inbounds with the conversations list. Every inbound text arrives on the `message.replied` webhook. The Conversations endpoints let you answer it with your own content, from the same number, inside the same thread, on the same project. The API never starts a conversation; a project send does that. ## The round trip **1. Receive the inbound** Your webhook endpoint gets a `message.replied` event. Its payload carries `conversation_id`, `message_id` (the inbound message), `from` (the contact), `to` (your number), `carrier` (the contact's mobile carrier, see [Carrier values](/api-reference/webhooks/events#carrier-values)), `text`, `is_opt_out`, and `is_opt_in`. Acknowledge with a `2xx` quickly and hand the work off. **2. Reply inside the conversation** ```bash theme={null} curl https://api.politicalcomms.com/v1/conversations/{conversation_id}/messages \ -X POST \ -H "X-API-Key: $POLITICAL_COMMS_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "Thanks for reaching out. Polls are open until 7pm at Lincoln Elementary." }' ``` The reply is accepted with `202` and queued at high priority. The response carries the new `message_id`, the sending number (`from`), the text as it will go out, and `media_urls` (the CDN URLs of attached media, empty for an SMS reply). To attach an image or video, add `"media_ids": [""]` to the body. **3. Watch for the outcome** `message.sent`, `message.delivered`, or `message.failed` fires for the returned `message_id`, each carrying the same `conversation_id`. There is no separate "reply" event. ## What a reply can and cannot do * **Text, one media item, or both.** The body is `{ "text": "...", "media_ids": ["..."] }`. `text` is optional when `media_ids` has an entry. Without media the reply is SMS and `text` is limited to 10 parts (1,530 GSM-7 or 670 Unicode characters); with media it is MMS and `text` is limited to 1,500 characters. Longer text is rejected with `400` and a message naming the limit. At least one of non-blank `text` or one `media_ids` entry is required, otherwise the call fails with `400`. `media_ids` takes one id from your media library (the same ids `POST /v1/projects` accepts; list them with `GET /v1/media`). Raw `media_urls` and unknown properties are rejected with `400`. Text is normalized for GSM encoding before sending, so a curly quote pasted from a document does not push the message into UCS-2. * **Same number, always.** The sending number is a property of the conversation, not of the request. If that number was released the reply is refused with `409 PHONE_NUMBER_UNAVAILABLE`. * **Opt-outs are enforced before anything is charged.** A contact who replied STOP gets `409 CONTACT_OPTED_OUT`. A thread with no sending number (`409 CONVERSATION_NOT_SENDABLE`) or a deleted project (`409 PROJECT_DELETED`) is refused the same way. `402 INSUFFICIENT_BALANCE` follows the same rule: nothing was charged. * **Not subject to quiet hours.** A reply is a follow-up to a contact who just texted in, and goes out immediately. * **Media must be usable.** An id that is not in the conversation's organization, is not ready, or belongs to a different brand than the project's is refused with `400 MEDIA_NOT_USABLE`, and nothing is charged. * **Billing.** A reply without media is SMS, billed per segment at the number's outbound rate. A reply with media is MMS, billed as one MMS (flat, not per segment). Either way the charge lands on the organization that owns the project. * **Inbound media is permanent.** `media_urls` on inbound messages from `GET /v1/conversations/{conversation_id}/messages` are copies hosted on our media CDN that do not expire. The `message.replied` webhook still carries the carrier's link as received, valid for 30 days. ## Retrying safely Send an `Idempotency-Key` (a UUID) on every reply you might retry. Within 24 hours a retry with the same key returns the stored response with `X-Idempotent-Replayed: true` instead of sending a second text. | You got | It means | Do this | | - | - | - | | `503 SEND_ENQUEUE_FAILED` | The reply could not be handed to the delivery queue. Nothing was sent and the charge was reversed. | Retry the same call. | | Any other `5xx` | Unknown whether the reply was queued. | Read `GET /conversations/{conversation_id}/messages` and look for your text before retrying. | | `4xx` | The request itself is wrong or the thread cannot take a reply. | Fix the cause; do not retry the same payload. | ## Recovering missed inbounds If your webhook endpoint was down past our four delivery attempts, list the threads that have new inbound messages: ```bash theme={null} curl "https://api.politicalcomms.com/v1/conversations?updated_since=2026-09-07T00:00:00Z&limit=200" \ -H "X-API-Key: $POLITICAL_COMMS_API_KEY" ``` `GET /conversations` returns only conversations with at least one inbound message, newest inbound first, across every organization the key can access. Filter on `last_inbound_at` with `updated_since` (default: the last 7 days; more than 90 days back is a `400`), narrow with `project_id`, and page until `next_cursor` is null. Then read each thread with `GET /conversations/{conversation_id}/messages` (newest first, both directions, never marks the thread read in the dashboard). Each message carries `carrier`, the contact's mobile carrier (the recipient's on outbound messages, the sender's on inbound ones), or `null` when it is not known; inbound messages received before this field was introduced return `null`. Values are described in [Carrier values](/api-reference/webhooks/events#carrier-values). Treat this as recovery, not as a substitute for the webhook: poll at most once a minute, and advance `updated_since` to the newest `last_inbound_at` you have processed. ## Tenant scope A conversation that does not exist and one that belongs to an organization outside your key's scope both answer `404 CONVERSATION_NOT_FOUND`. The API never confirms the existence of another tenant's thread. ## Reference * [Conversations endpoints](/api-reference/openapi.json) * [`message.replied` payload](/api-reference/webhooks/events#message-replied) * [Error codes](/api-reference/errors) # Versioning & Deprecation Source: https://docs.politicalcomms.com/api-reference/versioning How the API is versioned, how deprecations are announced, and the sunset guarantees you can build against ## Versioning The API is versioned in the URL path. `v1` is the current and only version: ``` https://api.politicalcomms.com/v1 ``` * **Breaking changes ship as a new version path** (`/v2`), never inside `v1`. A breaking change is anything that removes an endpoint or field, renames one, changes a type, tightens validation on existing input, or changes the meaning of an existing response value. * **Additive changes land in `v1` without notice**: new endpoints, new optional request fields, new response fields, new enum values on fields documented as extensible. Build clients that ignore unknown response fields. ## Deprecation policy When an endpoint, parameter, or field is deprecated: 1. It is marked `deprecated: true` in the [OpenAPI specification](https://politicalcomms.com/openapi.json) — the spec is the source of truth. 2. The deprecation is announced in the [changelog](/changelog). 3. When an endpoint is scheduled for removal, its responses will carry a `Deprecation` header, and once a removal date is committed, a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the removal timestamp. No endpoint is deprecated today, so no live response currently carries these headers. 4. The deprecated surface keeps working alongside its replacement for **at least 90 days** after the `Sunset` date is announced. Nothing is removed silently. An example already live today: `phone_number_id` on `POST /projects` is deprecated in favor of `phone_number_ids[]`; both are accepted while the migration window is open. ## What agents should do * Check the spec's `deprecated` flags before generating integration code; prefer the replacement surface whenever one is documented. * Watch for `Deprecation` and `Sunset` response headers and surface them to a human operator. * Treat unknown response fields as additive evolution, not an error. # Delivery Error Codes Source: https://docs.politicalcomms.com/api-reference/webhooks/error-codes Every error_code the message.failed webhook can deliver, with its error_message and what to do about it. When a message fails, the [`message.failed`](/api-reference/webhooks/events#message-failed) webhook payload carries two fields describing why: * `error_code` - a short, stable code identifying the failure (e.g. `"300"`, `"012"`). * `error_message` - the human-readable label for that code, exactly as listed in the table below. The same codes appear in the project error report (`GET /v1/projects/{id}/error-codes`), conversation CSV exports, and data exports, so a code seen in a webhook can be cross-referenced anywhere else in the platform. ## Code format Most codes are three digits with leading zeros preserved (`"001"`, `"012"`, `"300"`), so they align at a consistent width. A small number of codes fall outside that family and arrive at their full length (e.g. `"10011"`, `"41000"`). Treat `error_code` as an opaque string, not a number: parsing `"012"` as an integer loses the leading zero. If a message fails with a code not listed below, the code is passed through as-is with a best-effort `error_message` (or `"Unknown error"` when no further detail is available). Email [support@politicalcomms.com](mailto:support@politicalcomms.com) with the code and the `message_id` and we will investigate. ## Categories Every code belongs to a category that tells you how to react: | Category | How to react | | - | - | | `opted_out` | Permanent for that recipient. They sent STOP (or similar); do not message them again. The platform suppresses them automatically. | | `landline_or_unreachable` | Permanent. The number cannot receive text messages; remove it from your lists. | | `invalid_destination` | Permanent. The number is invalid, deactivated, or unreachable; remove it from your lists. | | `blocked_as_spam` | Content or consent problem. Review your message content and recipient consent before resending. | | `carrier_rejected` | The recipient's network declined or did not accept the message. Often transient; safe to retry later. | | `rate_limited` | Transient. Sending volume exceeded a limit; throughput recovers on its own. | | `expired` | Transient. The message timed out before delivery, usually a throughput symptom. | | `unregistered_campaign` | Sender-side registration issue. Contact support if it persists. | | `invalid_sender` | Sender-side number issue. Contact support if it persists. | | `invalid_content` | The message body or media was rejected. Adjust the content and resend. | | `configuration` | Sender-side setup issue. Contact support if it persists. | | `loop` | A message forwarding loop was detected. | | `unknown` | Unclassified. Contact support with the `message_id`. | ## All error codes The `error_message` column is the exact string delivered in the webhook payload. | Code | Error message | Category | Description | | - | - | - | - | | `001` | Not routable | `landline_or_unreachable` | The destination is a landline or a number that cannot receive text messages. | | `002` | Blocked as spam (temporary) | `blocked_as_spam` | The message was flagged as spam and temporarily blocked. Review recipient consent before resending. | | `003` | Blocked as spam (permanent) | `blocked_as_spam` | The message was flagged as spam and the sending number is permanently blocked. | | `004` | Rejected by destination | `carrier_rejected` | The recipient's network declined the message. | | `005` | Expired during transmission | `expired` | The message was not delivered in time and expired before reaching the recipient. | | `006` | Recipient network unavailable | `carrier_rejected` | The recipient's network was unavailable or unresponsive. | | `007` | Loop detected | `loop` | A message forwarding loop was detected. | | `008` | Undeliverable | `carrier_rejected` | The recipient's network did not accept the message. | | `009` | Invalid message body | `invalid_content` | The message body was rejected. Review content for disallowed characters or formatting. | | `010` | Campaign not registered | `unregistered_campaign` | The sending number is not attached to an approved campaign and cannot send to this recipient. | | `011` | Too many requests | `rate_limited` | The message exceeded the allowed sending rate and was flagged as spam. | | `012` | Invalid destination number | `invalid_destination` | The recipient's number was rejected as invalid, deactivated, or unreachable. | | `013` | Invalid sender number | `invalid_sender` | The sending number was rejected as invalid or improperly provisioned. | | `014` | Expired in queue | `expired` | The message expired before it could be sent. Sending rate may exceed throughput capacity. | | `015` | Blocked as spam (policy) | `blocked_as_spam` | The message was flagged by an internal spam policy and not delivered. | | `016` | Daily sending limit reached (T-Mobile) | `rate_limited` | The campaign reached its daily T-Mobile sending limit. Limits reset at midnight Pacific. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). | | `017` | Rejected as spam (AT\&T) | `blocked_as_spam` | AT\&T flagged the message content as spam. Review content and recipient consent. | | `018` | Sending limit reached (AT\&T) | `rate_limited` | The campaign exceeded AT\&T's per-minute sending limit. | | `019` | Invalid campaign tag data (AT\&T) | `unregistered_campaign` | AT\&T rejected the message because campaign tagging information is incorrect. | | `020` | Blocked - traffic inflation | `blocked_as_spam` | Suspected artificial 2FA traffic. Sending is blocked for 24 hours. | | `021` | Destination is not a mobile phone | `landline_or_unreachable` | The destination is not a mobile number, and only mobile numbers can be messaged. | | `100` | Number not messaging enabled | `configuration` | The sending number is not enabled for messaging. | | `150` | Toll-free number not in registry | `configuration` | The toll-free sending number is not listed in the voice registry and cannot be message-enabled. | | `151` | Messaging enablement pending | `configuration` | Messaging is in the process of being enabled with another provider for this number. | | `152` | Invalid registration parameter | `configuration` | A required registration parameter was missing or invalid. | | `153` | Registry access denied | `configuration` | Could not access the messaging registry for this number. | | `154` | Unauthorized network ID | `configuration` | Not authorized to use the network identifier associated with this number. | | `155` | Authorization letter required | `configuration` | A Letter of Authorization is required to enable messaging on this number. | | `156` | Unauthorized property | `configuration` | Not authorized to set one of the requested registration properties. | | `157` | Temporarily blocked | `configuration` | Registry updates for this number are temporarily unavailable. | | `158` | Delete failed | `configuration` | The record could not be found or deleted. | | `159` | Registration error | `configuration` | An unknown error occurred while updating registration for this number. | | `300` | Recipient opted out | `opted_out` | Recipient previously sent STOP (or similar) and cannot be messaged. | | `301` | Unsupported message type | `invalid_destination` | The destination does not support this type of message or sender. | | `302` | Message too large | `invalid_content` | The message exceeded the maximum number of allowed segments. | | `303` | Message not found | `unknown` | The message record could not be located. | | `304` | Invalid content combination | `invalid_content` | SMS requires a body; MMS requires a subject or media. Check message formatting. | | `305` | Invalid sender address | `invalid_sender` | The sending number or sender ID is not valid for this sending configuration. | | `306` | Alpha sender not configured | `invalid_sender` | No alphanumeric sender ID is configured for this sending configuration. | | `307` | Alpha sender mismatch | `invalid_sender` | The provided alphanumeric sender ID does not match the configured one. | | `308` | Invalid sender for MMS | `invalid_sender` | MMS can only be sent from US long-code or MMS-enabled short-code numbers. | | `309` | Destination region not allowed | `configuration` | The destination region is not allowed by the sending configuration. | | `310` | Invalid recipient address | `invalid_destination` | The recipient address was not a single valid number. | | `311` | Invalid sending credentials | `configuration` | The sending credentials provided were invalid. | | `312` | Sending configuration disabled | `configuration` | The sending configuration is disabled. Re-enable it to resume sending. | | `313` | Missing sending credentials | `configuration` | The sending credentials were missing from the request. | | `314` | Sending temporarily unavailable | `configuration` | Sending is temporarily unavailable for this number. No action is needed on your end - support has been alerted. | | `315` | Unhealthy sender number | `invalid_sender` | The sending number is temporarily restricted due to poor delivery performance or spam reports. | | `316` | No content provided | `invalid_content` | The message had no body or media to send. | | `317` | Invalid MMS content | `invalid_content` | MMS may contain up to 10 items and must be under 1 MB total. | | `318` | Message queue full | `rate_limited` | The message queue is full. Reduce sending rate and retry. | | `319` | Incompatible message type | `invalid_destination` | This combination of sender and recipient is not supported. | | `320` | Sender temporarily unusable | `invalid_sender` | The sending number is temporarily unusable (e.g. still provisioning). | | `321` | No usable sending numbers | `configuration` | No usable sending numbers are assigned to this sending configuration. | | `322` | Blocked due to content | `invalid_content` | The message contained disallowed content and was blocked. | | `323` | Messaging activation failed | `configuration` | Messaging could not be enabled on the sending number. | | `324` | Product type change failed | `configuration` | The number's product type could not be changed. | | `325` | Invalid alphanumeric sender ID | `invalid_sender` | The alphanumeric sender ID value is invalid. | | `326` | Sender ID assignment failed | `configuration` | The alphanumeric sender ID could not be assigned to this profile. | | `327` | Invalid link-shortener domain | `configuration` | The domain is not configured as a valid link-shortener domain. | | `328` | SMS exceeds recommended size | `invalid_content` | The message would be split into too many SMS segments. Consider sending as MMS. | | `329` | Toll-free number not verified | `unregistered_campaign` | The toll-free number has not completed use-case verification. | | `330` | Toll-free number not provisioned | `configuration` | The toll-free number is not yet fully provisioned for messaging. | | `331` | Missing whitelisted destinations | `configuration` | The sending configuration has no allowed destinations configured. | | `332` | Brand cannot be deleted | `configuration` | The brand has an active campaign and cannot be deleted. | | `333` | Spend limit reached | `rate_limited` | This send would exceed the configured spend limit. | | `10011` | Sending rate exceeded | `rate_limited` | The message was submitted faster than the allowed sending rate. It is retried automatically; this code is terminal only when retries were exhausted. | | `41000` | WhatsApp error | `carrier_rejected` | The WhatsApp provider returned an error for this message. | # Event Types Source: https://docs.politicalcomms.com/api-reference/webhooks/events Full JSON payload samples for message.sent, message.delivered, message.failed, message.replied, link.clicked, the email events, and contact_list.analyzed. Every webhook event has a consistent envelope: ```json theme={null} { "data": { "event_type": "", "id": "", "occurred_at": "", "payload": {/* event-specific payload */} }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` All timestamps (`occurred_at`, `sent_at`, `delivered_at`, `failed_at`, `received_at`, `clicked_at`) are ISO-8601 UTC with millisecond precision and a `Z` suffix. Phone numbers (`to`, `from`) are E.164 strings. The envelope owns the event identity (`id`, `occurred_at`); the event-specific `payload` carries only event fields and resource references (`message_id`, `tracking_link_id`). ## Identifiers `data.id` uniquely identifies the **event**, and together with `event_type` it is the delivery deduplication key — if you receive the same `(event_type, id)` pair twice, treat the second as a redelivery. It also arrives in the `X-Event-ID` header. * **Message events** (`message.sent`, `message.delivered`, `message.failed`): `id` equals `message_id` — the message *is* the event identity, since a message emits at most one event of each type. The same `id` therefore recurs across one message's lifecycle (`message.sent` then `message.delivered`), distinguished by `event_type`. * **`message.replied`**: `id` equals `message_id` and identifies the **inbound** message (the reply itself), not the outbound message it responds to. Correlate via `conversation_id`. * **`link.clicked`**: `id` is a unique per-click identifier — every unique click delivers its own event. `tracking_link_id` identifies the link and recurs across clicks of that link. ## Test events Message events include `is_test` (boolean). It is `true` for test messages (sent from the app's test flow or via `POST /v1/projects/{id}/test`) and for the synthetic event produced by the dashboard's **Send test webhook** button (which additionally corresponds to no real message: its ids are random). Production traffic always carries `is_test: false`. `link.clicked` has no `is_test` field. The test event's sample payload carries `"carrier": "Verizon"`. ## Carrier values `carrier` (string or `null`) sits in `payload` next to `to` and `from` on `message.sent`, `message.delivered`, `message.failed`, and `message.replied`. It is `null` when the carrier is not known. The three national networks always arrive as exactly `AT&T`, `Verizon`, or `T-Mobile`. Brands and subsidiaries are reported under the network they run on: | Value | Also covers | | - | - | | `AT&T` | Cricket, FirstNet | | `Verizon` | TracFone, Straight Talk | | `T-Mobile` | Metro, Sprint, Mint Mobile, Boost | Any other non-null value is a regional carrier's own registered name (for example `CELLULAR SOUTH, INC.`); treat it as an opaque string. ## `message.sent` Triggered when a message is successfully accepted by the carrier. `carrier` is the recipient's mobile carrier; see [Carrier values](#carrier-values). ```json theme={null} { "data": { "event_type": "message.sent", "id": "msg_7f8a9b0c1d2e3f4g", "occurred_at": "2025-01-17T10:30:00.278Z", "payload": { "message_id": "msg_7f8a9b0c1d2e3f4g", "conversation_id": "conv_1a2b3c4d5e6f7g8h", "project_id": "proj_9i8h7g6f5e4d3c2b", "to": "+15551234567", "from": "+15559876543", "carrier": "Verizon", "status": "sent", "sent_at": "2025-01-17T10:30:00.278Z", "message_text": "Hi Jane, thanks for supporting our campaign!", "is_test": false, "contact": { "phone_number": "+15551234567", "custom_fields": { "First Name": "Jane", "Last Name": "Smith", "Email": "jane@example.com", "City": "Austin", "State": "TX" } } } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` ## `message.delivered` Triggered when the carrier confirms the message was delivered to the recipient's device. `carrier` is the recipient's mobile carrier; see [Carrier values](#carrier-values). ```json theme={null} { "data": { "event_type": "message.delivered", "id": "msg_7f8a9b0c1d2e3f4g", "occurred_at": "2025-01-17T10:30:15.412Z", "payload": { "message_id": "msg_7f8a9b0c1d2e3f4g", "conversation_id": "conv_1a2b3c4d5e6f7g8h", "project_id": "proj_9i8h7g6f5e4d3c2b", "to": "+15551234567", "from": "+15559876543", "carrier": "Verizon", "status": "delivered", "sent_at": "2025-01-17T10:30:00.278Z", "delivered_at": "2025-01-17T10:30:15.412Z", "message_text": "Hi Jane, thanks for supporting our campaign!", "is_test": false, "contact": { "phone_number": "+15551234567", "custom_fields": { "First Name": "Jane", "VoterID": "TX12345678" } } } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` `sent_at` is always present on `message.delivered`. When the carrier's delivery receipt arrives before the send is recorded, it is the carrier-reported send time, or the delivery time if none was reported. ## `message.failed` Triggered when the carrier rejects the message or delivery fails. `error_code` is a short delivery-failure code (e.g. `"300"` opted-out, `"012"` invalid destination) paired with a human-readable `error_message`. The full list of codes, messages, and how to react to each lives in [Delivery error codes](/api-reference/webhooks/error-codes). Fields describing a message that was accepted before failing (`sent_at`, `message_text`) may be absent when the message was rejected at send time. `carrier` is the recipient's mobile carrier, or `null` when the message was rejected before it reached a carrier; see [Carrier values](#carrier-values). A message the carrier accepted but never confirmed (no delivery receipt within the carrier's window) stays `sent` and emits neither `message.delivered` nor `message.failed`; its `message.sent` event is the last one you receive. ```json theme={null} { "data": { "event_type": "message.failed", "id": "msg_7f8a9b0c1d2e3f4g", "occurred_at": "2025-01-17T10:30:20.007Z", "payload": { "message_id": "msg_7f8a9b0c1d2e3f4g", "conversation_id": "conv_1a2b3c4d5e6f7g8h", "project_id": "proj_9i8h7g6f5e4d3c2b", "to": "+15551234567", "from": "+15559876543", "carrier": "Verizon", "status": "failed", "failed_at": "2025-01-17T10:30:20.007Z", "error_code": "012", "error_message": "Invalid destination number", "is_test": false, "contact": { "phone_number": "+15551234567", "custom_fields": {} } } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` ## `message.replied` Triggered when an inbound SMS/MMS is received from a contact. `carrier` is the sender's mobile carrier; see [Carrier values](#carrier-values). ```json theme={null} { "data": { "event_type": "message.replied", "id": "msg_inbound_abc123", "occurred_at": "2025-01-17T11:00:00.531Z", "payload": { "message_id": "msg_inbound_abc123", "conversation_id": "conv_1a2b3c4d5e6f7g8h", "project_id": "proj_9i8h7g6f5e4d3c2b", "from": "+15551234567", "to": "+15559876543", "carrier": "Verizon", "text": "Thanks for the update!", "media_urls": [], "is_opt_out": false, "is_opt_in": false, "received_at": "2025-01-17T11:00:00.531Z", "is_test": false, "contact": { "phone_number": "+15551234567", "custom_fields": { "First Name": "Jane", "Last Name": "Smith" } } } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` To answer a `message.replied` event with your own text, call `POST /v1/conversations/{conversation_id}/messages`; the reply goes out from the same number inside the same thread and its outcome arrives on `message.sent` / `message.delivered` / `message.failed`. See [Two-Way Conversations](/api-reference/two-way-conversations). ## `link.clicked` Triggered when a recipient clicks a tracking link in your message. ```json theme={null} { "data": { "event_type": "link.clicked", "id": "click_xyz789", "occurred_at": "2025-01-17T10:35:00.844Z", "payload": { "tracking_link_id": "link_xyz789", "message_id": "msg_7f8a9b0c1d2e3f4g", "project_id": "proj_9i8h7g6f5e4d3c2b", "short_url": "https://link.yourdomain.com/abc123", "destination_url": "https://yoursite.com/volunteer-signup", "clicked_at": "2025-01-17T10:35:00.844Z", "device": "iPhone", "browser": "Safari 17.2", "os": "iOS 17.2", "ip_address": "203.0.113.42", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1", "is_bot": false, "is_unique_click": true, "is_share_click": false, "contact": { "phone_number": "+15551234567", "custom_fields": { "First Name": "Jane", "City": "Austin" } } } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` ### What "unique" means `is_unique_click` is `true` the first time a given **device fingerprint** clicks a particular tracking link, and `false` for that fingerprint's later clicks on the same link. The fingerprint is derived from the clicker's **IP address and User-Agent** — it identifies a device on a network, not a person. Two consequences worth planning around if you aggregate these events yourself: * One person who taps a link on cell data and again on Wi-Fi produces **two** unique clicks, because the IP changed. * Two people behind one shared connection (a household or office NAT) using the same device model and browser can collapse into **one** unique click. Uniqueness is scoped **per link**, and each recipient receives their own tracking link, so one person's repeat clicks never suppress another recipient's. Clicks we identify as automated — carrier link scanners, security crawlers, and link-preview fetchers — arrive with `is_bot: true` and are excluded from the click totals shown in campaign reports. ## Email events > [!NOTE] > > These five event types can be subscribed on any endpoint alongside the message > events. They fire for organizations with email enabled. Email events use the same envelope as message events: `data.event_type`, `data.id`, `data.occurred_at`, and `data.payload`, with `meta.attempt`. There are only five, and each one is deliberate: | Event | Fires when | | - | - | | `email.delivered` | The recipient's mailbox provider accepted the message. | | `email.bounced` | A **permanent** bounce. Soft bounces are deferred and retried, and never fire this event. An address held back by send-time screening is not a bounce and does not fire it. | | `email.complained` | The recipient marked the message as spam. | | `email.unsubscribed` | A one-click or hosted-preferences unsubscribe. | | `email.clicked` | A **unique, non-bot** click. A recipient's repeat clicks on the same link fire once. | There is no `email.opened`: open tracking is a pixel, which makes it both approximate and, at campaign volume, the highest-rate event we could send. There is no inbound email event either, because the product has no inbox. Test sends and seed addresses never emit email webhooks. ### Deduplication Every email payload carries a stable `id` that is also the dedup key, so a redelivery of the same event reuses the same value: | Event | `id` format | | - | - | | `email.delivered`, `email.bounced`, `email.complained` | `:`, where kind is `delivery`, `bounce`, or `complaint` | | `email.unsubscribed` (one-click / hosted page) | `unsub:` | | `email.clicked` | `:` | The HTML body of a campaign is never included in a webhook payload. ### `email.delivered` ```json theme={null} { "data": { "event_type": "email.delivered", "id": "0100018f2c3d4e5f-a1b2c3d4:delivery", "occurred_at": "2026-09-02T15:04:05.123Z", "payload": { "id": "0100018f2c3d4e5f-a1b2c3d4:delivery", "email_message_id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0", "campaign_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42", "sender_identity_id": "7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64", "recipient": "voter@example.com", "occurred_at": "2026-09-02T15:04:05.123Z" } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` ### `email.bounced` Only permanent bounces fire. `bounce_type` and `bounce_subtype` come from the mailbox provider; `reason` is the SMTP diagnostic code when one is supplied. `bounce_class` is `address` when the mailbox does not exist or refuses all mail, and `policy` when the receiving mail system refused this message for policy or reputation reasons. Only `address` bounces are suppressed. ```json theme={null} { "data": { "event_type": "email.bounced", "id": "0100018f2c3d4e5f-a1b2c3d4:bounce", "occurred_at": "2026-09-02T15:04:05.123Z", "payload": { "id": "0100018f2c3d4e5f-a1b2c3d4:bounce", "email_message_id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0", "campaign_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42", "sender_identity_id": "7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64", "recipient": "voter@example.com", "occurred_at": "2026-09-02T15:04:05.123Z", "bounce_type": "Permanent", "bounce_subtype": "General", "bounce_class": "address", "reason": "smtp; 550 5.1.1 user unknown" } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` ### `email.complained` `reason` is the provider's feedback type (for example `abuse`), and is `null` when the provider does not supply one. ```json theme={null} { "data": { "event_type": "email.complained", "id": "0100018f2c3d4e5f-a1b2c3d4:complaint", "occurred_at": "2026-09-02T15:04:05.123Z", "payload": { "id": "0100018f2c3d4e5f-a1b2c3d4:complaint", "email_message_id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0", "campaign_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42", "sender_identity_id": "7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64", "recipient": "voter@example.com", "occurred_at": "2026-09-02T15:04:05.123Z", "reason": "abuse" } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` Treat this event as final. We suppress the address automatically; re-adding it to a list will not send to it again. ### `email.unsubscribed` `scope` says what the recipient opted out of: `identity` (the sender they heard from; always the case for one-click and mailto unsubscribes) or `domain` (every sender on that sending domain, chosen on the hosted preferences page). `reason` is `one_click` for an RFC 8058 one-click unsubscribe or the reason chosen on the hosted preferences page. ```json theme={null} { "data": { "event_type": "email.unsubscribed", "id": "unsub:01J9X4M2Q7R5T8V0Y2A4C6E8G0", "occurred_at": "2026-09-02T15:04:05.123Z", "payload": { "id": "unsub:01J9X4M2Q7R5T8V0Y2A4C6E8G0", "email_message_id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0", "campaign_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42", "sender_identity_id": "7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64", "recipient": "voter@example.com", "occurred_at": "2026-09-02T15:04:05.123Z", "scope": "identity", "reason": "one_click" } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` A mailbox provider retrying the one-click POST does not produce a second event: the dedup key is the message, and a recipient unsubscribes from one send once. ### `email.clicked` Fires once per recipient per link. Repeat clicks on the same link by the same recipient do not fire again, and clicks we identify as automated (link scanners, security crawlers, preview fetchers) never fire at all. ```json theme={null} { "data": { "event_type": "email.clicked", "id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0:9c7b3f1a-8d42-4e6f-a2e5-3f7a9c1e8b24", "occurred_at": "2026-09-02T15:04:05.123Z", "payload": { "id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0:9c7b3f1a-8d42-4e6f-a2e5-3f7a9c1e8b24", "email_message_id": "01J9X4M2Q7R5T8V0Y2A4C6E8G0", "campaign_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42", "recipient": "voter@example.com", "link_id": "9c7b3f1a-8d42-4e6f-a2e5-3f7a9c1e8b24", "occurred_at": "2026-09-02T15:04:05.123Z", "device_type": "mobile", "browser": "Safari", "os": "iOS" } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` Click events are flushed in batches, so `occurred_at` is the moment of the click rather than the moment of delivery. `device_type`, `browser`, and `os` are best-effort and may be `null`. ## Contact list events ### `contact_list.analyzed` Fires once when a line-type analysis run on a contact list finishes. It is opt-in: subscribe to it on the endpoint alongside the other events. Use it instead of polling `GET /v1/contact-lists/{id}` after `POST /v1/contact-lists/{id}/analyze`. ```json theme={null} { "data": { "event_type": "contact_list.analyzed", "id": "5b0e2c94-7d1a-4f38-9a6c-c2e81f4d7a03", "occurred_at": "2026-09-29T14:12:40.518Z", "payload": { "id": "5b0e2c94-7d1a-4f38-9a6c-c2e81f4d7a03", "list_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42", "name": "Spring Outreach List", "analysis": { "status": "complete", "analyzed_numbers": 11800, "breakdown": { "mobile": 11200, "landline": 300, "voip": 250, "invalid": 50 } }, "analyzed_url": "https://api.politicalcomms.com/v1/contact-lists/3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42/download?type=analyzed" } }, "meta": { "attempt": 1, "max_attempts": 4 } } ``` `analyzed_url` is an API URL, so download it with your `X-API-Key` (see `GET /v1/contact-lists/{id}/download`). It does not expire. # Overview Source: https://docs.politicalcomms.com/api-reference/webhooks/overview Real-time webhook notifications for messages, replies, and link clicks. Use cases, payload format, and architecture. Webhooks deliver real-time notifications when events occur in your account. Common use cases include CRM integration, analytics pipelines, alerting, and triggering automated follow-up campaigns. ## Use cases > [card] CRM integration > > Update contact records when messages are delivered or fail. > [card] Analytics pipelines > > Stream click data to your data warehouse for analysis. > [card] Alerting > > Notify staff when constituents reply to messages. > [card] Automation > > Trigger follow-up campaigns based on engagement. ## Event types * [`message.sent`](/api-reference/webhooks/events#message-sent) - Message accepted by the carrier. * [`message.delivered`](/api-reference/webhooks/events#message-delivered) - Carrier confirmed delivery to the recipient's device. * [`message.failed`](/api-reference/webhooks/events#message-failed) - Carrier rejected the message or delivery failed. * [`message.replied`](/api-reference/webhooks/events#message-replied) - Inbound SMS/MMS received from a contact. * [`link.clicked`](/api-reference/webhooks/events#link-clicked) - Recipient clicked a tracking link. * [`contact_list.analyzed`](/api-reference/webhooks/events#contact-list-analyzed) - A contact list finished line-type analysis (opt-in). ## How webhooks flow **1. An event occurs** A message is sent, delivered, fails, gets a reply, or a tracking link is clicked. **2. We POST the payload to your endpoint** Signed with HMAC-SHA256 over the JSON body, with headers identifying the event type, ID, and timestamp. **3. Your endpoint validates and acknowledges** Validate the signature, persist or queue the event for processing, and return `200` within 10 seconds. **4. If your endpoint fails, we retry** Four total attempts with exponential backoff (immediate, +4s, +16s, +64s). After that, the delivery is marked failed and you can retry manually from the dashboard. ## Where to go next > [card] [Set up an endpoint](/api-reference/webhooks/setup) > > Configure event subscriptions, copy your signing secret, and send a test webhook. > [card] [Validate signatures](/api-reference/webhooks/signature-validation) > > HMAC-SHA256 validation pattern with a Node.js example. > [card] [Event payload reference](/api-reference/webhooks/events) > > Full JSON samples for every event type. > [card] [Retry policy](/api-reference/webhooks/retry-policy) > > Schedule, best practices, and how to make handlers safely idempotent. # Retry Policy Source: https://docs.politicalcomms.com/api-reference/webhooks/retry-policy Four attempts with exponential backoff. Best practices for making handlers idempotent. If your endpoint doesn't return a `2xx` response within 10 seconds, we retry on an exponential backoff schedule. ## Retry schedule | Attempt | Delay | | - | - | | Attempt 1 | Immediate | | Attempt 2 | 4 seconds after first failure | | Attempt 3 | 16 seconds after second failure | | Attempt 4 | 64 seconds after third failure (final attempt) | After **4 failed attempts** the webhook is marked as failed. You can manually retry from the webhook deliveries page in the dashboard. Failed deliveries keep the request payload and your endpoint's response so you can inspect them before retrying; successful deliveries keep the event, the HTTP status and the time. ## Endpoints that keep failing An endpoint that fails every delivery for **3 days in a row**, with no successful delivery in that time, is turned off automatically. Your organization's owners and admins get one email naming the endpoint, its URL, and the date the failures began, and the endpoint shows **Disabled after repeated failures** under **Admin > API > Webhooks**. To turn it back on, fix the URL or the server behind it so it answers with a `2xx`, then choose **Re-enable** on the endpoint. Its failure record starts fresh. > [!WARNING] > > Events that happen while an endpoint is turned off are not delivered to it later. After re-enabling, read anything you missed through the API, for example [`GET /conversations`](/api-reference/two-way-conversations) for inbound replies. ## Best practices > [accordion] Return 200 within 10 seconds > > Process asynchronously if needed. Queue the event for background processing and return `200` immediately. This prevents retries on slow handlers. > [accordion] Always validate the HMAC signature before processing > > See [Signature Validation](/api-reference/webhooks/signature-validation). > [accordion] Use event\_id to deduplicate > > Rare but possible - under network failure conditions you could receive the same event twice. Store processed `event_id`s and skip duplicates. > [accordion] Log failures and monitor endpoint health > > Set up alerting on failed webhook deliveries. The deliveries page in the dashboard and your own application logs together give you full traceability. > [accordion] Use HTTPS endpoints (required in production) > > HTTPS is enforced for all production webhook endpoints. Self-signed certs are not accepted - use a real CA-issued cert. > [accordion] Rotate secrets periodically (every 90 days recommended) > > From the dashboard, regenerate the signing secret on each endpoint. Update your application's environment variable, then verify a test webhook validates with the new secret before relying on it. # Setup & Configuration Source: https://docs.politicalcomms.com/api-reference/webhooks/setup Add a webhook endpoint, subscribe to events, copy the signing secret, and send a test webhook. **1. Open the Webhooks admin** From the dashboard, go to **Admin → API → Webhooks** in the left navigation menu. **2. Add an endpoint** Click **Add Endpoint** and configure: * **Endpoint name** - A descriptive label (e.g. "CRM sync - production"). * **HTTPS URL** - Your receiving endpoint. Must be HTTPS in production. * **Event subscriptions** - Tick the events you want to receive. You can subscribe to one or many. **3. Copy and store the signing secret** Copy the webhook signing secret and store it securely (a secret manager, not source control). You will need it to validate signatures. The secret is shown only once. **4. Send a test webhook** Click **Send Test Webhook** to verify end-to-end delivery. Your endpoint should return `200` within 10 seconds. ## Receiving payloads Webhooks arrive as `POST` requests with `Content-Type: application/json`. The body is JSON; the headers tell you what kind of event, when it occurred, and how to validate the signature. ```http theme={null} POST /your-webhook-endpoint HTTP/1.1 Host: your-domain.com Content-Type: application/json X-Webhook-Signature: sha256=abc123... X-Event-Type: message.delivered X-Event-ID: msg_7f8a9b0c1d2e3f4g X-Timestamp: 1705488600 ``` The payload body and per-event examples are documented on the [event types](/api-reference/webhooks/events) page. ## Where to go next > [card] [Validate signatures](/api-reference/webhooks/signature-validation) > > HMAC-SHA256 validation pattern + Node.js example. > [card] [Retry policy](/api-reference/webhooks/retry-policy) > > What happens if your endpoint is unavailable. # Signature Validation Source: https://docs.politicalcomms.com/api-reference/webhooks/signature-validation Every webhook request is signed with HMAC-SHA256 using your endpoint secret. Validate before trusting the payload. Every webhook request is signed with **HMAC-SHA256** using your endpoint secret. Validate the signature before trusting the payload. > [!WARNING] > > Webhook endpoints are publicly reachable URLs. Anyone who knows the URL can send a `POST` to it. **Always validate the signature** before processing. Don't take an unsigned or invalid-signature request seriously. ## Headers ```http theme={null} POST /your-webhook-endpoint HTTP/1.1 Host: your-domain.com Content-Type: application/json X-Webhook-Signature: sha256=abc123... X-Event-Type: message.delivered X-Event-ID: msg_7f8a9b0c1d2e3f4g X-Timestamp: 1705488600 ``` ## Node.js example ```javascript theme={null} const crypto = require('crypto'); function validateWebhook(req, webhookSecret) { const signature = req.headers['x-webhook-signature']; const body = JSON.stringify(req.body); const hmac = crypto.createHmac('sha256', webhookSecret); hmac.update(body); const expectedSignature = `sha256=${hmac.digest('hex')}`; return signature === expectedSignature; } app.post('/webhooks', (req, res) => { if (!validateWebhook(req, process.env.WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } // Process webhook... res.status(200).send('OK'); }); ``` ## Tips * **Use a constant-time comparison** for the signature check (e.g. `crypto.timingSafeEqual` in Node) to avoid timing attacks. * **Stringify the body identically to how it was received** - middleware that reformats JSON will break the signature. Either store the raw body before parsing or use a body parser that preserves the exact byte sequence. * **Reject stale events** by checking `X-Timestamp` is within (e.g.) 5 minutes of now. Combined with signature validation, this protects against replay attacks. * **Don't log the secret.** It should only ever appear in your secret manager and in memory inside the validation routine. # Changelog Source: https://docs.politicalcomms.com/changelog Recent updates, improvements, and fixes to the Political Comms platform. Updates roll out continuously. The most recent changes appear first. **November 10, 2026** ## Added * **Voter data purchases become contact lists.** A completed CSV voter data purchase now becomes a contact list on its own, with its cell phone, name and address columns mapped, so there is nothing to download and upload again. Purchase History shows the list with a link to it, a **Create list** button for purchases made before this change, and **Retry list** if an import fails. A file with no cell phone column stays a download only. * **One uploader for every file.** **Assets > File Uploads** opens on **Upload to**: choose the owner once, then drop up to 10 files. Lists and media are sorted for you, so there is no upload type to pick, and media is ready as soon as it lands. Rename a file from its preview in the media library. * **One list for texting and email.** A file with phone and email columns becomes one list. Choose **Audience** or **Do not contact** once for the batch, then each file's phone and email columns; L2 and Aristotle voter files find their cell phone column for you. See [Step 3: Upload & Organize Contacts](/onboarding/contacts). ## Changed * **Recurring Usage is now Subscriptions.** Billing > Subscriptions has one **Cancel subscription** action for campaigns and numbers: **At end of period** stops renewal and can be reversed with **Don't cancel**, and **Now** ends it immediately after you type the campaign name or the number's last four digits (numbers are released, no refund). Cancelling and deleting campaigns and numbers moved here from the 10DLC page. * **Expired and Rejected campaigns.** The 10DLC page now shows Expired and Rejected as their own states instead of Failed. When a campaign expires its billing stops and its numbers are held for 30 days, and you can move them to a new campaign from the 10DLC page. Deleting a brand now requires typing its name, and a draft campaign that was never submitted can be discarded. See [10DLC registration](/onboarding/10dlc-registration). * **API.** Creating a project on, or moving a project to, an expired campaign returns `409` `CAMPAIGN_EXPIRED`, alongside the existing `CAMPAIGN_SUSPENDED`. * **Lists is one page.** **Assets > Lists** replaces Contact Lists and Email Lists. Each list shows its phone numbers and, when it has emails, their totals, unsubscribes, bounces and quality grade. Deleting a list removes both. WinRed and Anedot feeds are one list each, and two lists can now share a name. * **Do not contact covers email too.** A do-not-contact file adds its phone numbers to an opt-out list and its emails to your unsubscribes, in the background for large files. Both apply to every send automatically. See them under **Lists > Do not contact > Unsubscribes and bounces**, and read [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions). * **Email images.** Upload them from the **Email** tab of the media library or the email editor's image picker. Choosing a texting image for an email now uses the same file instead of making a copy. * **Breaking API change: one list import.** `POST /v1/contact-lists/import` now imports phone numbers, emails, or both, or a do-not-contact file, and `POST /v1/email/lists/import` is removed. This removal is an exception to our 90-day deprecation policy: the endpoint had no API usage. To move over, send `name` as `list_name`, the column you mapped to `email` as `email_column`, and the rest of `mapping` as `merge_tags`; `email_domain_id` and `acquired` are unchanged, and `consent` is now optional (allowed only for an audience with an `email_column`). With `merge_tags`, phone numbers map only the columns you name, while emails also map every remaining column by its default name. Unknown top-level fields in the request body are ignored. Lists also report which channels they carry. The TypeScript SDK 0.19.0, Python SDK 0.18.0, CLI 0.19.0 and MCP server 0.19.0 match. See the [API reference](/api-reference/introduction). **November 9, 2026** ## Fixed * **Bought domains.** You now get an email when a domain you bought through the platform expires, and its setup is cleaned up from your account. Adding email to a domain you bought for links only now works correctly. See [Buying a domain](/help/buying-a-domain). **November 8, 2026** ## Changed * **Campaign Verify expiry dates and reminders.** Verifications, tokens and sender email addresses are valid for two-year cycles: requests submitted November 15, 2024 to November 14, 2026 are valid until January 31, 2027, and requests submitted November 15, 2026 to November 14, 2028 are valid until January 31, 2029 (11:59 PM Central Time). We email one reminder per organization about 30 days before expiry, listing every campaign, and show a notice in the last 30 days of a cycle that a request submitted now expires soon. Expired tokens are refused for new brand and toll-free registrations, and a new campaign cannot be registered on a brand with expired vetting. A political brand's vetting expires with its Campaign Verify token, so it must be re-vetted with a token from a new-cycle verification before January 31, 2027 at 11:59 PM Central Time, or the brand and its campaigns deactivate. New-cycle verifications can be submitted starting November 15, 2026. A renewal is a new verification request with another \$95 fee; from November 15 of a cycle year, each verified request on the Campaign Verify page has a Renew button that opens a prefilled request (same details, election date set to the next general election, editable, with your choice of where the PIN goes), and after the PIN and token are generated, a Re-vet action applies the new token to the brand. See [Campaign Verify](/compliance/campaign-verify). **November 6, 2026** ## Added * **Bare domain redirect for domains bought here.** Send visitors of `candidate.com` to one `https://` address. With no address set, nothing is served and no record is written. * **Domain reputation and campaign sample warnings.** Pre-flight warns when reputation services flag a domain, and when no registered 10DLC campaign shows a tracking domain in its samples. Neither blocks adding the domain. * **Buy a domain in the dashboard.** Search for a name with most common endings, or choose from the similar available names the search offers, pick app, link tracking and email uses, and we register it and write every DNS record for you. Prices vary by ending and are shown before you buy: the registrar's price plus a flat \$6 per year domain hosting fee, charged from your wallet and renewed yearly 30 days before expiry. Your organization owns the domain, we manage it, and there is nothing for you to verify. See [Buying a Domain](/help/buying-a-domain). ## Changed * **Two DNS records for customer-managed app and link-tracking domains.** These domains now show two records at once. Both must be plain CNAMEs with proxying turned off. * **All your domains are on one Domains page.** **Domains** in the sidebar now has one row per root domain, showing its app, link-tracking and email state and what to do next, with one **Add domain** button. Open a domain for its DNS records and actions. Old links and bookmarks still work. **November 5, 2026** ## Added * **Link Stripe with a restricted API key.** Resellers who prefer not to use Connect can have support link their Stripe account with a restricted key, which has no access to account details, balances, payouts or disputes. See [Bring Your Own Stripe](/help/bring-your-own-stripe). * **Your organization ID is one click away.** The top-right user menu now shows your organization's name and ID under your name and email, with a copy button, so support requests and API setup can start with the right ID. ## Changed * **Lincoln, the in-app assistant, is now a chat bubble in the bottom-right corner.** The sparkles icon has left the header. Click the bubble on any page to ask a how-to or account question; the page stays visible while you chat, and the conversation is kept when you collapse it. * **Lincoln answers only what your role can see.** Account lookups (balance, pricing, brands, registrations, phone numbers, contact lists, reports) follow the same permissions as the pages that show them. If your role cannot open a page, Lincoln says so and suggests an owner or admin rather than reading the figures out. * **Lincoln points you to the right person when it cannot help.** A user in a sub-organization is given their parent organization's contact; a top-level organization is pointed to **Send feedback** in the user menu and their account rep. Lincoln's help guide was also brought up to date with the current Text, Email, Assets, Billing, and Admin menus. * **Your invoice shows texts you sent apart from replies to STOP, START and HELP.** Each text message line now carries two sub-lines, "Sent by you" and "Replies to STOP, START and HELP", the usage-by-day blocks show replies beside each day, and the CSV gains the same split in its own sections. Nothing about what is charged changes; the split is there so a count of your campaign sends reconciles to the invoice. ## Fixed * **The 10DLC and email pricing tables are back on the Billing, Campaign Registry, 10DLC registration, and onboarding overview pages.** The shared pricing table was referenced in a way the site never rendered, so those pages showed the prose around it and no table. **November 4, 2026** ## Added * **Email sequences.** A campaign is now a Broadcast or a Sequence: a first email, then follow-ups a chosen number of days apart at a chosen hour, each from its own template. Follow-ups go to the people the first email reached and skip anyone who has unsubscribed or replied; they can be sent as replies in the first email's thread; replies are forwarded to your reply address and end that person's follow-ups, and a **Stop follow-ups** action covers people who phone instead. One test send tests every email, and scheduling, unscheduling or deleting the first email applies to the whole sequence. The campaign page lists every email with its counts and a total. Over the API, `POST /email/campaigns` takes a `sequence` with the follow-up steps, campaign reads carry `sequence_id`, `sequence_position`, `stop_on_reply` and `counts.replied`, and webhooks can subscribe to `email.replied`. ## Changed * **Email list uploads match every column for you, like texting lists.** The mapping step now opens with every column already matched: the email address, the standard fields a header names, and every other column as a merge field named from its header. Check the email column, skip anything you do not want, and continue. Merge fields from email lists now appear in the **Insert data** menu when you write an email. Over the API, leaving `mapping` out of an email list import now imports every column the same way. * **Asset pages show only the organization you are working in.** 10DLC brands and campaigns, the Media library, Contact Lists, Short Codes, Campaign Verify submissions, and Email Lists no longer list a sub-organization's rows for a parent's owner or admin. To work with a sub-organization's assets, use View As to view as a user in that sub-organization. The Projects dashboard and Email > Campaigns still list sub-organization work, and now have an **Include sub-organizations** switch in the Filters popover (on by default, remembered for you). * **Your monthly invoice now shows where your balance started and ended.** The summary reads like a bank statement: opening balance, payments, adjustments and refunds, usage, closing balance, and the amount due, which is \$0.00 when your balance covered the month. The Invoices card on Billing > Ledger shows the same opening and closing balances per month. Invoices already issued keep their original layout. * **A completed project can no longer be edited.** Its edit page now opens the report, and an edit sent by other means is refused. Duplicate the project to send it again. * **Members of more than one organization see one organization at a time.** Lists show the organization you are working in; switch organizations to see another's records. A membership elsewhere no longer mixes that organization's records into your current one. ## Fixed * **Downloads of an uploaded email list carry your columns.** "Current list" and "Unmailed addresses" exported the right addresses but blank columns for the fields you had mapped. Lists uploaded from now on export every mapped field under its field name; a list uploaded earlier shows its fields again once re-uploaded. * **Brands can be deleted once their numbers are released and their campaigns ended.** The delete was refused with "Cannot delete brand with 1 phone numbers" even after every number had been released, because released numbers still counted as in use. * **Test messages render a contact your send would actually reach.** When a test fills merge fields from a sample contact, that contact is now chosen under the same rules as the real send: suppression lists, opt-out lists and global opt-outs all apply. Supplying your own merge values on a test is unchanged. * **Pages for a record you cannot see, or that was removed, now say so.** Editing a campaign, segment, template, verification, project or contact list by a link that no longer resolves shows "This item isn't available" with a way back, instead of an empty form. * **Brand limits apply to every record reached through a project.** Looking up a contact by phone and putting a number on a campaign both respect the brands a user is limited to. **November 3, 2026** ## Fixed * **The schedule time zone now defaults to Mountain Time for Arizona lists.** Arizona does not observe daylight saving, so its recipients are tracked on their own clock for quiet hours, and the Start dialog used to leave the time zone on Eastern for an Arizona list instead of picking one for you. It now starts in Mountain Time. Quiet hours for Arizona recipients are unchanged and still follow Arizona's clock. **November 2, 2026** ## Changed * **Numbers another organization released stay off the market for 90 days.** A phone number released by one organization cannot be bought by a different organization for 90 days, up from 30, so the earlier owner's replies and opt-outs are never delivered to someone new. Your own organization can still buy back a number it released at any time. ## Fixed * **Searching numbers for a client's campaign no longer offers numbers you cannot buy.** When a user from one organization searched numbers for a campaign owned by another organization they manage, the results could include numbers their own organization had just released, and buying them failed with "not available". The search now shows only numbers the campaign's organization can buy. * **Data exports of very large projects finish, and a report email tells you right away if a file failed.** On heavy send days the Data Export (CSV) for projects over about a million recipients could fail a few minutes in with "This export could not finish", and an "Email this report" request for that project waited 90 minutes before reporting a timeout. The export now reads the project's conversations in the order its index stores them, so its size no longer changes how the database runs it, and a report email whose file fails is marked failed within a minute with the file's own reason so you can request it again. * **Download all works for very large projects.** The combined ZIP of a project's report files is now built as a stream, so a project with hundreds of megabytes of export data no longer fails the download or slows other work while it is assembled. **October 31, 2026** ## Added * **Webhook endpoints that keep failing are turned off, and you are told.** An endpoint that has failed every delivery for 3 days is turned off and your owners and admins get an email. Fix the URL, then choose Re-enable under Admin > API > Webhooks. See [Retry Policy](/api-reference/webhooks/retry-policy). * **SDK 0.18.0 and Python SDK 0.17.0.** The TypeScript SDK, CLI, MCP server (`@political-comms/sdk`, `@political-comms/cli`, `@political-comms/mcp`) and the Python package (`political-comms`) now read a survey project's results (`GET /projects/{id}/survey-results`), pause projects, reply with MMS, and document carrier pacing in message parts. Each package now ships a CHANGELOG. ## Fixed * **Message length limits now match the editor everywhere.** A text message is limited to 10 parts (1,530 standard or 670 Unicode characters) and MMS text to 1,500 characters. The API now refuses longer text on projects, survey questions, templates and conversation replies with a message naming the limit, instead of accepting it. See [Create Project](/api-reference/projects/create-project). **October 27, 2026** ## Changed * **Email campaigns handle a bad send on their own.** When a campaign's bounce rate reaches 3%, it no longer pauses and waits for you: the addresses never mailed before, which are where bounces come from, are dropped from it and the campaign keeps sending to everyone else. If the rate climbs again, or the complaint rate trips, the campaign is finished automatically and reads Stopped with how many were not sent. Pauses for a low balance, an inactive sender, missing content or a suspended sender now end on their own once the problem clears, and a Gmail spam-rate pause lifts once Google reports the domain under the line. There is no second-pause support rule any more. * **Recipients export shows everyone.** The recipients download and the report's recipient list now include the people a campaign never sent to, with the reason, so a stopped or trimmed campaign's report is the whole audience. * **A paused email campaign is edited in place.** Editing a paused campaign no longer stops it and returns it to draft; it stays paused with its audience and progress, and your changes reach the people not yet sent to when you resume. A content change asks for a test before resuming, and a list change rebuilds the audience on resume while keeping everyone already sent to. Campaigns paused automatically for bounces or spam keep that pause and its rules through an edit. * **A part-sent campaign no longer looks new.** Before, a part-sent campaign that was edited could show more sent than recipients and a Start button, as if it were new. Finished campaigns now show their true sent-to-recipients ratio. ## Fixed * **Phone number rentals, renewals, 10DLC campaign fees and domain setup fees now charge each organization in a roll-up at its own rate**, as messaging already did. Before, every parent organization paid the sub-organization's rate for these fees, so a reseller's margin on them was lost. The domain setup fee is now your organization's own rate from **Billing > Pricing** instead of a fixed amount, and the Add domain dialog shows that rate. **October 25, 2026** ## Added * **Tracking Export.** Projects with link tracking on have a new Tracking Export (CSV) download: one row per link click, showing which phone number's link was clicked, when, where it went, and the device, browser and operating system. It is also included in Download All and in report emails. ## Fixed * **Deleting a WinRed or Anedot list now disconnects its feed.** Before, the connection kept running after the list was deleted: new donors kept arriving in a list you could no longer see, and there was no way to switch the feed off. Deleting the list now disconnects the feed at the same time, and the delete confirmation says so. To keep collecting donors, connect a new list before deleting the old one. * **Emailing the report for an older project works again.** For projects past the 180-day window, the report email now sends the report and data export instead of waiting on a replies file that is no longer available. * **Replies asking you to stop are honored however they are worded.** A reply such as "please stop", "wrong number", or one telling you to go away in stronger language now opts the contact out, the same as STOP. Replies like these received since October 1 have been opted out as well. Angry replies that are opinion rather than a request to stop still keep the contact sendable and are tagged hostile in the inbox. **October 24, 2026** ## Added * **Replies can include an image or video.** Replies in the inbox and through the API can now carry a picture or video from your library. Pictures contacts send you now stay viewable permanently instead of expiring after 30 days. ## Changed * **Email campaigns send to proven addresses first.** Addresses this platform has delivered to before now go out ahead of addresses it has never mailed, and the bounce breaker judges the whole send, so an unproven tail stops a campaign only if it lifts the total to 3%. Never-mailed addresses at Gmail, Microsoft and Apple go before those at other domains, which bounce about twice as often. Imports also remove Gmail addresses Gmail could never have issued (under 6 or over 30 characters, or with characters other than letters, digits and dots). A bounce pause names how many never-mailed addresses are still waiting and what to do; the list page offers a download of the **Unmailed addresses** for cleaning; the list page and the campaign checklist show how many addresses are unproven before you send. See [campaigns and deliverability](/help/email/campaigns-and-deliverability#deliverability-breakers). ## Fixed * **Starting a brand from a Campaign Verify token works for a token you have used before.** Pasting a token your organization had already added could fail with an error; it now fills in the brand form as it does for a new token. * **Retrying a custom domain no longer charges when another organization owns it.** If someone else verified the domain after your setup failed, Retry now tells you so before charging, instead of charging the setup fee again and failing. **October 23, 2026** ## Added * **Send reset link on the Users page.** When a person also belongs to an organization you do not manage, the Password button is replaced by **Reset link**, which emails them the same link Forgot password sends so they choose the new password themselves. The link expires in 30 minutes. ## Fixed * **Starting a project uses your current pricing.** The balance check before a send priced the project at the rate in effect when it was last saved, so a price change made afterward could leave a start blocked as "insufficient balance" while every wallet in your organization could cover it. The check now prices the send at the moment you start it, including nonprofit rates and toll-free or short-code numbers. * **Setting a sub-organization member's password works again.** The password dialog now acts on the organization you are viewing; before, it judged the person's default organization and could refuse a parent-organization owner with "User is not in an organization you manage". * **New Organization starts with your organization as the parent.** The selector no longer opens empty and fails with "A parent organization is required", and the form starts clean on every open. ## Changed * **DNS records copy the way your registrar wants them.** On every domain page, the Host column now shows each record's name relative to your domain, with the domain greyed out after it, and the copy button copies only that part (`_sender-verification`, or `@` for the domain itself). Most DNS editors append your domain to whatever you type, so pasting the full name used to publish the record one level too deep and it never verified. * **`www.` is dropped from a domain you add.** Typing `www.candidate.com` registers `candidate.com`, the domain your mail is sent from. App and link-tracking hosts refuse `www`, since that is your website's address. * **A deactivated membership no longer counts as belonging.** When deciding who may change a person's password, email, name or phone, only the organizations they are active in count, plus their default organization unless it was deactivated. * **A re-purchased phone number is a new number record.** When you buy a number that was released earlier, by your organization or by another one after the 30-day cooling-off period, it now appears as a new number with its own id and a purchase date that is yours. The earlier owner's conversations and projects stay with the earlier record. In the API, `created_at` on a phone number is now the date your organization acquired it. **October 22, 2026** ## Added * **Auto-renew and delete controls on the 10DLC page.** Each campaign and each of its phone numbers now has the same auto-renew switch and Delete / Release button as the Recurring Usage page, so you can manage a number or campaign from where you see it. ## Changed * **One auto-renew setting per campaign.** Turning auto-renew off now also tells the registrar right away that the campaign should not renew; turning it back on asks the registrar first, and a campaign that has already expired there cannot be resumed (the page says so). * **Managers can now turn off auto-renew and remove numbers and campaigns.** Anyone who can buy a number can also release it; roles that cannot see these controls disabled with the reason instead of an error after clicking. ## Fixed * **Auto-renew and delete now work on a sub-organization's numbers and campaigns.** Turning auto-renew off or on, or deleting, a number or campaign that belongs to one of your sub-organizations answered "not found" even though the Recurring Usage and 10DLC pages listed it. Owners and admins can now manage every charge those pages show. * **Uploading many videos at once no longer fails.** Video compression now runs on a dedicated background process, one video at a time, so a large batch is queued and finishes in order instead of overloading the service. A queued video shows as Queued, then Compressing, then Ready in your media library. **October 21, 2026** ## Fixed * **Video and GIF sent by text now show as `Tap-To-Watch.mp4` or `Tap-To-Watch.gif` on iPhones** that display them as a file icon (iOS 27 does this for senders the recipient has not saved or replied to), instead of a generated name like `m8512.mp4`. Existing media library files are covered as well as new uploads. * **The "Replies received" figure in an emailed project report now matches the report page.** It counted every inbound message, opt-out replies included; it now excludes opted-out and test conversations, as the page does. ## Added * **Choose the attachment name per video or GIF.** Open the file in your media library and set it from the preview; every new upload starts as `Tap-To-Watch`. Up to 16 letters, numbers, hyphens or underscores; the extension is added for you. * **Emailed project reports now include the Responses CSV** (one row per reply, opt-outs removed) alongside the report PDF and the data export, for both "Email this report" and the report that goes out after a project completes. ## Changed * **Signups on your white-label domain now land under your organization, and you approve them.** Someone who registers through the public form on your app domain (for example after a signup link has expired) appears under Organizations as Requested; your owners and admins get a "New client registration" email and an in-app notice, and Approve or Deny sit on the Organizations list and on the organization's page. Until you decide, the registrant cannot sign in. The confirmation and account-ready emails they receive carry your page title, support address and login domain, and are sent under your name from the platform's neutral notifications address, never from a Political Comms address. The same applies to anyone who registers through one of your signup links. **October 20, 2026** ## Changed * **Contact and opt-out lists accept CSV files up to 500 MB**, up from 100 MB, so the largest voter files upload in one piece (10 files per drop, as before). The row count shown while you map columns is now an estimate; the exact count is written when the import finishes. Importing a list by URL through the API keeps its 50 MB limit. * **Email lists accept CSV files up to 500 MB**, up from 50 MB, and an email list import interrupted along the way now resumes on its own. Importing an email list by URL through the API and uploading an unsubscribe list stay at 50 MB. * **List imports run as a background job.** Uploads no longer tie up the app while a large file is read, and an import interrupted along the way resumes on its own. A list that still cannot finish is marked failed within about three hours instead of staying on Uploading. * **Lists uploaded without a brand now apply your organization's org-wide opt-out lists.** They used to honor only platform-wide opt-outs, so expect slightly higher opted-out counts on those lists. ## Fixed * **Smaller sends no longer wait behind very large ones.** When several million-recipient sends ran at the same time, a smaller project could sit at 95 percent for most of an hour while its last messages waited their turn. The platform now keeps the hand-off line to a couple of minutes of work, so a project finishes within minutes of its last message being queued, whatever else is sending. Overall sending speed is unchanged. * **New text-messaging numbers show Active only once every carrier has registered them.** A number used to show Active a few minutes early, while one or more carriers were still registering it, so a test sent in that window could go undelivered on that carrier. Registration usually completes 10 to 15 minutes after purchase; the number stays Pending until then. **October 16, 2026** ## Changed * **Delivery details for successful webhooks no longer show the request payload or your endpoint's response.** Both are kept for failed deliveries, where you can inspect them and retry. Successful deliveries still show the event, the HTTP status and the time. **October 14, 2026** ## Added * **Windstream mailboxes are removed from email lists at upload.** Windstream recipients reported our email as spam at an unusually high rate, so they are removed from every upload, contact added over the API and donor-platform sync, and never sent to. Existing lists were cleaned and the "removed at upload" breakdown shows them. * **Lists remember your filters.** Every table that can be searched, filtered or sorted now keeps what you set, per person and per organization, and restores it when you come back, on any browser. That covers projects, 10DLC, email campaigns and lists, contact lists, media, the ledger, organizations and the rest. Page position is not kept. Clearing the filters clears what is remembered. * **Create a 10DLC brand from a Campaign Verify token.** On the 10DLC page, open **Create Brand** and choose **From Campaign Verify token**, paste the token, and review the brand that will be created: the committee's name, EIN, address, contact name, email and phone are filled in from the Campaign Verify record (and the website, when the committee gave Campaign Verify one) and every field can be edited. Nothing is created until you submit; then the brand is registered and the token is applied as its vetting as soon as the registrar finishes creating the brand, usually within a minute or two. Token-created brands are always non-profit political brands. If the vetting still cannot be applied, the brand page says so and offers the apply action, with no second registration. * **Apply a Campaign Verify token before the brand is identity-verified.** The apply action now shows for every registered political brand that is not yet vetted, on the 10DLC page and on the brand's page, including brands whose identity the registry could not confirm on its own. A token already applied to a brand before it was registered is now imported when you apply it again, and expired or inactive tokens are refused with a plain message. ## Changed * **The T-Mobile daily cap is now a speed limit, not a stop.** Past a brand's cap, T-Mobile and unknown-carrier recipients keep sending at about 300 message parts per minute per campaign. After about 300 over-cap receipts with under 5% failures, the rate rises to about 3,000 parts per minute. Only a carrier rejection pauses a project: it closes the campaign's T-Mobile lane for the Pacific day, and projects pause with `pause_reason` `brand_daily_cap` once only T-Mobile and unknown-carrier recipients remain. Calling `POST /projects/{id}/schedule` on such a project reopens the lane and tries T-Mobile again, and `daily_cap_bypass: true` now means skip the reduced rate. In `GET /projects/{id}/throughput`, `t_mobile.will_pause` is always `false` and `t_mobile.estimated_send_days` is always `1`. * **Email lists are no longer held for review.** Every list you upload can be sent to as soon as it is ready, whatever its quality grade. A list graded **Bad** (previously shown as Poor) sends at the slower pace used for acquired lists, the same as a **Fair** list, and the campaign checklist shows a warning. The list's page shows the signals behind the grade. Sending first to people who signed up or engaged recently protects your domain. ## Fixed * **The audience builder tells you how long the voter-data provider asks you to wait.** When the provider is busy, the estimate and the value lists now say how long to wait instead of asking you to try again in a few seconds, and they hold off for that long before asking again, so the wait does not grow. * **The unsubscribe page shows the sender, not your organization.** The hosted preferences page now names only the From name the recipient saw and its sending domain, with no organization name or logo, and its widest option is that sending domain rather than the whole organization. Agencies sending for several clients were showing the agency to every client's recipients. **October 13, 2026** ## Added * **Audit every sub-organization's payments and balance adjustments from your own Ledger page.** Parent organizations get a new **Sub-organization payments and adjustments** section under Sub-organization spend. It lists every payment a sub-organization made (including those paid into your connected Stripe account) and every manual balance adjustment applied to one, across all levels below you, with the organization, who applied an adjustment and why, the amount, and the balance after. Filter by type or by one organization. Until now this meant opening each sub-organization's ledger in turn. ## Changed * **The T-Mobile daily cap now counts message parts.** T-Mobile's per-brand daily limit counts 160-character SMS segments, the same way AT\&T's per-minute limit does, so a text that splits into three parts spends three of the day's allowance per recipient. The sender-side counter, the launch modal's pause estimate (which now says "message parts" when a text splits) and `GET /v1/campaigns/{id}/throughput` (`daily_cap`, `used_today` and `remaining_today`, documented as parts) all count the same way; the response shape is unchanged. * **Yahoo, AOL and AT\&T mailboxes are removed from every email list at upload.** Recipients at Yahoo-run providers (Yahoo, AOL, AT\&T, Verizon, Cox, Frontier and the rest) report political email as spam many times more often than anyone else, and one shared sending reputation carries every customer. The upload summary shows how many were removed; contacts added over the API come back `rejected` with reason `yahoo_family`, and donor-platform syncs skip them. Existing lists were cleaned the same way. Nothing to do on your side. * **Email lists show what was removed at upload.** The lists page and each list's detail page now carry a "removed at upload" count with its breakdown (Yahoo/AOL first, then role addresses, typos, throwaway domains, no mail server). It covers uploads, contacts added over the API and donor syncs, and existing uploaded lists were filled in from their original files. * **Send the final email to someone the list missed.** On a campaign that has already gone out, the Test dialog can now send the final email, subject and all, with no \[TEST] tag. * **Text delivery statuses lost to a carrier-side outage are now recovered automatically.** When our messaging vendor stops sending delivery receipts (as happened on October 13 from about 1:30 PM to 3:45 PM Eastern), texts still reach their recipients but projects showed them as "sent" rather than "delivered." The platform now checks every unanswered message with the vendor starting two hours after it is sent, at any volume, and updates project delivery counts the same way a normal receipt would. No action is needed; affected projects from October 13 are being corrected as the check runs. * **Campaign complaint rates now count only mail to providers that report complaints.** Gmail never reports individual spam complaints, so a rate divided by every send read far too low. Complaint rate on the campaign report, the automatic complaint pause and the warm-up check now use the same denominator mailbox providers use. Bounce rate is unchanged. * **Email unsubscribe pages and one-click unsubscribes stay on your link domain.** The unsubscribe and preferences page used to redirect to the platform's API hostname, and the one-click unsubscribe URL in every message's headers named it, even on a branded campaign. Both now use the campaign's link domain. Campaigns without a branded tracking domain use a neutral shared link host (`e.txtplatform.app`) for every link, the open pixel, view in browser, the page and the one-click URL, so no recipient ever sees the product's hostname. * **Uploading an email list returns you to the Lists page**, the same as a texting contact list, with a confirmation, and a list that is still importing shows a spinner on its Processing badge. ## Fixed * **Resubscribe actually resubscribes.** The Resubscribe button on the preferences page removed the sender suppression but left the recipient marked unsubscribed on every list, so the next campaign still skipped them. It now restores the list rows the unsubscribe flipped. Rows removed for a bounce, complaint or invalid address stay removed, and an organization-wide opt-out is not undone. **October 12, 2026** ## Changed * **Organization signup links now show the client organizations that registered through them, and you can rename a link.** The link's name is your own reference for it, not the name of the organization it creates: whoever signs up chooses their own organization name. Each link's row in **Admin > Organizations** now lists the client organizations that have actually registered through it, so you can confirm a prospect's signup without asking them, along with who created the link. Renaming works at any time, including after a link has been used or revoked. The link URL itself is still shown only once when you create it and cannot be retrieved afterwards; if you lose it, revoke the link and create a new one. **October 11, 2026** ## Changed * **Self-service text rates are now $0.020 per SMS segment and $0.045 per MMS.** Previously $0.018 per SMS segment and $0.040 per MMS. Rates are still lower with volume. * \*\*Full-service text is now a flat $0.015 per message added to your self-service rate, the same amount for SMS and MMS.** This replaces the separate SMS and MMS starting rates ($0.028 and $0.050). At posted rates that is from $0.035 per SMS segment and \$0.060 per MMS, and your volume rate still applies underneath, so the upcharge does not reset it. There are no monthly minimums. * **Self-service email is now $3.00 per 1,000 emails ($0.003 each), lower with volume.** Previously $5.00 per 1,000 ($0.005 each). The new rate applies to every email sent from today; a campaign already in progress moves to it on its next batch, and emails already sent keep the price they were charged. Full-service email stays \$0.01 per email. **October 10, 2026** ## Changed * **Paused projects can now be edited, including their sending setup.** `PATCH /v1/projects/{id}` accepts broadcast projects in `draft`, `awaiting_test`, `ready`, and `paused`. `channel` (`10dlc`, `toll-free`, or `short-code`), `brand_id`, `campaign_id`, and `toll_free_verification_id` are no longer immutable; only `organization_id` and `type` are. Sending any of the four requires the full setup for the channel plus `phone_number_ids`, with the same checks as create, and returns `409` `CAMPAIGN_SUSPENDED` or `400` `ASSET_OUT_OF_SCOPE` when the campaign is suspended or the project's lists or media belong to the old brand or registration. Any edit moves the project to `awaiting_test`. To resume a paused project: `PATCH`, then `POST /v1/projects/{id}/test`, then `POST /v1/projects/{id}/schedule`. Recipients already sent are never re-sent, and held messages are refunded and sent again with the edited message and sending setup. See [Update Project](/api-reference/projects/update-project). * **Scheduling a toll-free project now checks verification.** `POST /v1/projects/{id}/schedule` (and starting or resuming in the dashboard) returns `409` `TOLL_FREE_NOT_VERIFIED`, with `details.phoneNumberIds`, when a number has not finished toll-free verification. ## Fixed * **Editing a paused project can no longer send the old message.** Messages that were on their way when you paused are now always pulled back and refunded when you edit, from the dashboard or the API, including any that were still waiting to go out. When you start the project again, everyone who has not received a message gets the edited version and is billed once. Deleting a paused project refunds those messages too. **October 9, 2026** ## Fixed * **A project report no longer counts refunded held messages as sent or failed.** When a paused project is closed or deleted, the messages it was holding are refunded and now disappear from the report entirely; before, they stayed listed as failed, and the project's sent and failed totals could jump by that many the next morning even though nothing more went out. Reports affected by this have been corrected. * **Exports of very large projects no longer fail partway through.** A project export over several large contact lists could run for twenty minutes and then stop while listing the recipients who were never reached, and the retry produced three failed copies in Downloads. The recipient lookup now finishes in seconds, and an export that cannot finish shows one failed entry with a clear message instead of three. * **Campaigns now wait and resume automatically at the platform's daily sending limit** instead of retrying every few seconds. ## Changed * **The sub-organization spend table no longer breaks out carrier fees.** Charged, cost, and margin are unchanged; the carrier passthrough is an internal detail. * **Dedicated sending is now per sending domain, and the toggle moved to the Email > Domains page.** The \$35.00 per month add-on is unchanged, but each pool now belongs to one sending domain and is billed to the organization that owns it. Turn it on from the domain's row under Email > Domains once the domain is verified; an organization can run several, each billed separately. Turning it off stops billing at the end of the month and the domain returns to shared sending. See [Dedicated sending](/help/email/campaigns-and-deliverability#dedicated-sending). * **Sending domains have their own page under Email > Domains, and each domain opens to a detail page.** DNS records, warm-up, DMARC, Google Postmaster, sender identities and dedicated sending for a sending domain now live on that page instead of an expanding row. Admin > Domains keeps app and tracking domains. ## Fixed * **A lapsed or unpaid dedicated-sending renewal now releases the pool and tells the organization.** If the monthly renewal cannot be charged before the grace period ends, the pool is released, the domain returns to shared sending, and the organization is notified with how to turn it back on. **October 8, 2026** ## Changed * **Email sending is now $5.00 per 1,000 emails ($0.005 each), lower with volume.** The new rate applies to every email sent from today; a campaign already in progress moves to it on its next batch, and emails already sent keep the price they were charged. Full-service email stays \$0.01 per email. ## Fixed * **The email campaigns list showed a campaign's cost at one hundredth of the real figure.** A campaign that had sent 1,196 emails showed $0.03 instead of $2.99. The campaign report was always right, and so was your bill; only the list was wrong. It now shows the same figure as the report. * **Messages held by a pause are refunded automatically after 24 hours.** When you pause a send, messages that were already prepared but not delivered are held and stay paid for so they can go out when you resume. If the project stays paused for more than a day, those messages are now refunded to your wallet automatically, whatever state the project is in, and you get a notification with the count and amount. Resuming later sends them again and bills them again. Previously the refund only happened when a paused project was closed after 14 days of inactivity, and a project that kept receiving delivery reports never counted as inactive, so some held messages were never refunded; those have been refunded. * **Editing a paused project with a very large number of messages held no longer fails.** When you pause a send, the messages that were already prepared but not yet delivered are held and stay paid for. Editing the message text refunds those held messages and re-creates them with your new wording when the project restarts; recipients who already received the message keep what they got. A hold of several hundred thousand messages used to make that edit, and deleting the project, fail with a generic error and refund nothing. The refund now runs in steps that are saved as they complete. If a very large hold takes longer than about 90 seconds, the save or delete stops, tells you how many messages were refunded so far, and asks you to save or delete again to finish; nothing is lost between attempts. * **A project that has already sent can be edited whenever it is not actively sending.** Paused, scheduled, ready, and awaiting-test projects all accept message edits now, including a second edit after the first. Only a project that is sending right now, or building its audience to send, asks you to pause first. **October 7, 2026** ## Changed * **Video in MMS on iOS 27 shows as a file until the recipient knows you.** iPhones on iOS 27 display video and GIF attachments from an unsaved number as a filename instead of a preview; still images are unaffected, and the preview appears as soon as the recipient replies or saves the number. We verified this with a controlled test and found no encoding or sending change that avoids it. [What to do about it](/help/best-practices#why-does-my-video-show-as-a-file-instead-of-a-preview-on-iphones). ## Added * **Pause a project from the API.** `POST /projects/{id}/pause` stops a running or scheduled send the same way the dashboard's Pause button does, with an optional reason you can read back later. Resume it with the schedule call, as before. [Reference](/api-reference/projects/pause-project). * **Toll-free verification matches your 10DLC registration.** The verification form asks what kind of organization you are (political, 501(c)(3), or 501(c)(4)) and writes the use case summary, sample messages, opt-in workflow, and hosted privacy and terms pages for you. Those fields are generated for carrier review and cannot be edited by hand; the additional details field stays yours. A "Fill from 10DLC brand" picker copies a registered brand's legal name, EIN, address, and contact onto the form. A Campaign Verify token is asked for only on political verifications. The opt-in image field is now optional, and when six or more numbers are on one request the form writes the explanation the carrier requires for the count. * **Notes on toll-free verifications.** Add a short internal note to any verification from the Toll-Free page, the same as brands and campaigns. `GET /toll-free-verifications` returns it as `notes`. * **A status page inside your dashboard.** Open it from the status line at the bottom of the sidebar or from the command menu (type "status"). It shows the health of each service, any active incident with its running updates, scheduled maintenance, and the last 90 days of incidents, all inside your own branding. ## Fixed * **A segment can be created even when its count takes too long to preview.** The builder used to turn a slow count into a validation error that disabled Create, so a very large campaign could not be segmented at all. It now says "Count unavailable", keeps Create enabled, and the exact count comes from the build. * **Segments built from a large campaign's results (failed, delivered, clicked, replied, no reply) count and build in seconds again.** A campaign that had just finished sending could take over two minutes to count and fail; the same count now takes two to eleven seconds and runs off the read replica, so it no longer competes with sends in progress. * **Toll-free submissions tell you what the carrier rejected.** A submission the carrier turns down now reports the field and the reason instead of a generic error, and the opt-in workflow field shows its 500-character limit as you type. * **The sidebar status line under-reported severity.** A partial outage showed as "Investigating active incident" and scheduled maintenance never appeared. Both now match the public status page. * **Link click counts for sends on October 6 and 7 were under-reported, and some clicks from those days were missed.** Click totals, unique clicks and click-through rates on affected sends have been recomputed, the missed clicks have been restored, and the click notifications for them were delivered late. The reporting path now records clicks and their totals together so they cannot disagree again, and it is sized for election-week volume. **October 6, 2026** ## Changed * **Users limited to certain brands are limited everywhere.** Brands, campaigns, numbers, messaging profiles, contact lists, media, projects, surveys, conversations, and exports now stay inside the brands a manager is assigned to. Before, some screens let them open another brand's records from a direct link. * **Parent organizations can suspend and reinstate their sub-organizations.** A suspension applied by Political Comms staff can only be lifted by staff. Customers can only create organizations under one they manage. * **Organization signup links need sub-organizations turned on.** They stop working if the issuing organization is suspended or loses the feature. * **Email costs show your own price.** Campaign cost, test-send cost, and cost per thousand were overstated and now use your organization's price. Template test sends respect a sending pause, skip suppressed addresses, and do not charge for them. * **Number lookup cost after queueing a list** now shows your organization's own price. * **Custom domains go to whoever verifies first.** A pending, unverified claim by someone else no longer blocks the real owner of a hostname. ## Fixed * **Messages that were charged but could not be queued are refunded automatically.** The refund notice shows your organization's own refund amount. * **Data exports and audience builds interrupted by maintenance resume right away** instead of about an hour later. * **One spam complaint no longer holds an email warm-up.** A domain's daily limit is held only after at least 2 complaints or 5 bounces in a day, with the rate over the limit. * **Home lists only what you can act on.** The held warm-up notice, the blocklist notices, and the "For your information" line are gone, along with their emails. A held warm-up still shows on the domain. The notices that remain say what to do. * API: a brand or campaign that is not in your organizations now answers "not found" instead of a permission error, a brand in a sub-organization works without naming the organization, and survey question media must belong to your organization. See the [API reference](/api-reference/introduction). **October 5, 2026** ## Changed * **Scheduled Sends has its own address and an Email tab.** The page moved to `/schedule`; old links still work. The **Texting** tab shows how many messages each project sends and a total for each day. The new **Email** tab shows each campaign on every day it sends: days already sent show what went out, and the remaining warm-up days show an estimate, including how campaigns on the same domain take turns. * **Media Files accepts videos up to 500 MB**, up from 250 MB, so a minute of 4K phone footage uploads as is. Videos are still compressed for MMS after upload, so what your recipients receive is unchanged. * **Contact and opt-out lists accept CSV files up to 100 MB**, up from 50 MB, so a full voter file with dozens of columns uploads in one piece. Email list uploads stay at 50 MB. * **A sender has one reply field: Where replies go.** It is required, and it is the address replies to that sender's emails go to, so use an inbox someone reads. Senders that had only filled in the old second field now use that address for replies. * **Seed addresses are just addresses.** The email provider dropdown is gone from Email settings; it never changed where seed copies were sent. * **Senders and Domains no longer have select-all checkboxes.** Use the buttons on each row or on the sender's page to activate, pause, verify, retry, or remove. * **Home shows texting and email side by side.** Each has its own column for this month and this week, the 7-day chart switches between them, recent activity includes your email campaigns, and Quick actions can start a new email campaign. * **The Email Overview page is gone.** Everything it showed is now on Home, so the Email menu opens on Campaigns, and old links to the overview land there too. * **Notes that need no action no longer count as needing attention.** They sit under "For your information" on Home. The note about a receiver blocking a shared sending address now links to dedicated sending in Email settings. **October 4, 2026** ## New * **Autopilot for AI replies.** On a broadcast project with **Use AI for responses** on, turn on **Autopilot** and Lincoln sends its reply right away instead of waiting for your approval. You set a reply limit per conversation (1 to 100); after that many automatic replies to one person, Lincoln stops replying to them, and in long conversations it starts wrapping up after 10. Replies that read as hostile, and anything that cannot be sent, still wait for you in chat view. Automatic replies are marked **Sent by Lincoln** in the thread, and Lincoln says it is an automated assistant if someone asks. Each automatic reply is billed as one AI draft plus one normal message. Autopilot is off unless you turn it on. ## Changed * Uploading an opt-out list with a name you already use no longer fails. The new list is saved with a number after the name, such as "October opt-outs (1)", the way a second copy of a file is named. ## Fixed * A small number of `message.delivered` webhooks could be missed while the platform was being updated or was scaling down after a large send. They are now delivered reliably. * Conversations and AI reply drafts are now checked against your organization on every request. * Approving an AI draft while your organization's sending is paused is now refused up front instead of charging for a message that is then held. * Creating or updating an organization with a `type` field now returns a validation error instead of silently ignoring the field. **October 3, 2026** ## Changed * Billing for replies you receive and for automatic opt-out confirmations now appears in your usage ledger as one line per project every few seconds, with the number of messages on it, instead of one line per message. The amounts you pay are unchanged. ## Fixed * Replies and opt-outs are no longer delayed during very large sends. * `link.clicked` webhooks could be missed during very large sends. They are now delivered reliably. * A survey could send its next question twice when a reply was retried. It now sends once. * Adding a number back to an opt-out list after removing it no longer fails. **October 2, 2026** ## Added * You can now rename, switch, or remove the merge tag for any column from the **Fields** section on a list's page. Select **Edit fields**. This works for uploaded lists and segments. See [Merge tags from your columns](/onboarding/contacts#merge-tags-from-your-columns). * You can now send email from a domain that already has mailboxes or is already set up elsewhere, including your main domain. Several organizations can send from the same domain, and each verifies it with its own DNS record. See [Sending domains and DNS](/help/email/sending-domains-and-dns#using-a-domain-that-already-has-email). * Email import now skips addresses with a common domain typo, such as `gmial.com`, and reports them as "Likely typo in the domain" so you can fix them. It also recognizes many more disposable addresses. See [Lists and address screening](/help/email/lists-and-validation#what-import-removes-and-holds-back). * You can now download your email suppressions as a CSV from the suppressions page. See [Bounces, complaints, and suppressions](/help/email/bounces-complaints-and-suppressions#suppression-scopes). * Monthly invoices now show volume by day. Each service you send or look up with gets a day-by-day list with a total that matches its monthly line, and the invoice CSV has a row per service and day. See [Billing](/help/billing#can-i-download-invoices-and-receipts). ## Changed * Uploading a text contact list now maps every column for you. Pick who owns the list and which column holds the phone number, and every other column becomes a merge tag automatically. You can still choose which columns to map instead. Standard columns such as first name and zip get the standard tag; any other column gets a tag named after its header, like `{donor_tier}`. This applies to lists created from now on; existing lists are unchanged. See [Merge tags from your columns](/onboarding/contacts#merge-tags-from-your-columns). * Contact list API: importing a list without merge tags now gives every column other than the phone column a merge tag automatically. If you send merge tags, only the columns you name are mapped, as before. Reading a list through the API now returns its available merge tags, so you can see the tag each column was given. See the [API reference](/api-reference/introduction). * Paid list validation is retired, so there is nothing to run or pay for before a send. Every campaign email is now screened as it goes out, and an address that looks undeliverable is skipped, not counted as a bounce, and held out of sends for 90 days. Skipped addresses are still billed at the normal email rate, and the campaign report shows them as Screened as invalid. See [Lists and address screening](/help/email/lists-and-validation#address-screening-at-send-time). * Acquired lists are no longer blocked until validated; they still warm up at half the normal daily ceiling. Role addresses such as info@ are now always removed at import, and a campaign sends to every subscribed contact that is not suppressed, so the recipient policy choice is gone. List export is now a plain contact export. * Email API: list and contact objects no longer include validation fields, campaigns no longer include a recipient policy, and the list import takes no options. The import summary reports a `screened` count. See the [API reference](/api-reference/introduction). * A bounce record that already exists and already authorizes this platform is now reported as already in place instead of as a conflict. * An address is no longer blocked when a mailbox provider rejects a message because of reputation or policy. It still counts as a bounce on that campaign, but the address stays sendable. ## Fixed * `sent_at` on `message.delivered` webhooks is now always set. It could arrive empty when the carrier confirmed delivery before the send was recorded; it now falls back to the carrier-reported send time, or the delivery time. See [Webhook events](/api-reference/webhooks/events#message-delivered). * Removing a sending domain no longer touches the domain's own email. Your DNS and mailboxes stay as they were, and setup another organization on the same domain relies on is left alone. * Opens and clicks are now recorded against your contacts, so the inactive-contact policy no longer holds back or drops people who read your email. Automated opens from privacy proxies and security scanners do not count. * The DMARC record we generate for a new sending domain now includes a reporting address, so DMARC reports arrive and the DMARC page fills in. For a domain you set up earlier, add the reporting address shown in your DNS records table to your DMARC record. See [Sending domains and DNS](/help/email/sending-domains-and-dns#the-records). * An address that soft bounces on three sends in a row is now stopped for your organization and that sender. Before, the count never reached three. * Seed addresses in Email settings now receive every campaign, with the first batch. They are left out of the audience count and every statistic. **October 1, 2026** ## Added * Email campaigns on a new sending domain now show their warm-up schedule before you send. A campaign larger than the domain's daily ceiling has always gone out over several days; the builder now lists how many messages each sending day will send, and asks you to confirm. The campaign page shows what went out each day and when the next day starts, and resuming a paused campaign shows the schedule again, updated for what is left. See [Warm-up](/help/email/campaigns-and-deliverability#warm-up). * Warm-up progress now appears on the sending domain under **Admin > Domains**, since every sender on a domain shares one ramp. ## Changed * Later days of a multi-day email send now start at the same time of day as the first day, in the campaign's time zone. Before, each later day started just after midnight Pacific, which is 3 AM Eastern. * A paused email campaign offers **Stop and edit** in place of Cancel. It returns the campaign to ready so you can change it, send a new test, and schedule the remaining recipients. People already sent to are not sent to again. * An email campaign waiting on its test send moves to ready (or to awaiting approval) as soon as the test is accepted. You no longer need to submit it a second time. * The Senders list no longer shows warm-up, lifetime bounce rate, or lifetime complaint rate columns, and the sender form no longer has a shared or dedicated pool choice. The two rate columns always read zero, and dedicated sending is set once for the organization under Email settings. Bounce and complaint rates remain on each sender's health panel. * The pacing setting has been removed from the email campaign builder. It was saved but never changed how a campaign sent. Large sends on a new domain are spread by the warm-up schedule instead. * Quiet hours now follow the time zone that holds most of your recipients, and a nationwide list gets a wider window. Each project still has one sending window. If more than half of your recipients are in one time zone, messages send from 8 AM to 10 PM in that zone, as before. If no time zone has a majority, the window opens at 8 AM Eastern and closes at 10 PM Pacific. Contacts are not held for their own local time, so on a nationwide list a recipient on the West Coast can be texted as early as 5 AM their time and one on the East Coast as late as 1 AM their time. Replies in two-way conversations are still not held. A project still sending at the close pauses itself with `pause_reason` `quiet_hours` and needs a manual restart once the window opens. ## Fixed * The warm-up timeline on an email campaign report was always empty. It now lists each sending day with what was planned, sent, and rolled over. * New sending domains would have spent an extra day on the first warm-up step from November 1, when clocks change. The nightly step-up now runs after the sending day has ended in both summer and winter time. * Editing a stopped, part-sent email campaign to remove a list now also removes that list's unsent recipients from the send. * An email campaign set to require approval can now be approved from its campaign page. Before, it stayed in awaiting approval with no way to approve it in the app, and the builder reported it as sending. * The Gmail Verified Sender checklist on a sender now shows Google Postmaster Tools as verified once the sending domain is verified there. Before, that check stayed unmet no matter what. **September 30, 2026** ## Fixed * Auto-recharge no longer stops for the rest of the day after ten recharges. A large send on a small target balance could use up that limit in minutes, after which the balance ran down with no warning. Auto-recharge now keeps running; the first time it runs ten times in a day, your billing contacts receive one email so you can check that it matches your sending. See [Billing](/help/billing#what-is-auto-recharge-and-how-do-i-enable-it). ## Changed * AT\&T recipients are now sent right away, like every other carrier, and the carrier delivers them at your campaign's AT\&T rate, usually within about an hour of sending. Before, the platform held most AT\&T recipients back and released them at that rate. In the last 90 minutes of the sending window the platform still holds back AT\&T recipients that could not be delivered before the window closes; they go out when you start the project again in the next window. The Start dialog now says AT\&T recipients are "all sent right away, and AT\&T usually finishes delivering within about an hour", and the AT\&T time estimate in the project throughput API now covers the AT\&T messages your campaign already has waiting plus this project's recipients. See [Sending speed](/help/sending-speed). * A project sending at its AT\&T rate no longer shows a carrier limit note or a time estimate under its progress bar. That is normal sending and needs no action, so the dashboard now just shows progress. The estimate before you start, in the Start dialog, is unchanged. * Bring your own Stripe: the Connect card now says you can sign in to an existing Stripe account or create one at Stripe's sign-in step, and that an account created there is set up under the Political Comms platform. See [Bring Your Own Stripe](/help/bring-your-own-stripe). * The auto-recharge section on Payment Methods now explains that each recharge tops up to the target balance and never more, so a send larger than the target is funded by several charges, and recommends a target close to a typical send. * Recharges during a fast send are no longer spaced a full minute apart. The next recharge starts as soon as the previous one has landed in your balance, with a 15 second minimum, so a send larger than your target balance is funded in a fraction of the time. A card is still never charged twice for the same shortfall. **September 29, 2026** ## Added * Every 10DLC campaign now sends to AT\&T at that campaign's carrier rate, whatever the brand type. AT\&T counts each part of a text, so the estimate accounts for your message length and a one-part text reaches AT\&T recipients faster; recipients on other carriers are never slowed. A send at the AT\&T limit shows an estimated finish time, and the Start dialog shows when your AT\&T recipients will be reached and warns before the sending window closes. The schedule time zone now defaults to your recipients' time zone. See [Sending speed and carrier limits](/help/sending-speed). API: `GET /projects/{id}/throughput` now reports the AT\&T estimate for political brands too, in the same fields. * API: you can now download a contact list's results. `GET /contact-lists/{id}` links the original file and, once analysis finishes, the analyzed file with phone type, carrier, city and state, and a new webhook event tells you the moment a list is done. See [Event types](/api-reference/webhooks/events#contact-list-analyzed). * SDKs and the CLI add a contact list download (`@political-comms/sdk` 0.14.0, `political-comms` 0.13.0 on PyPI). * Message webhooks and conversation messages now include the contact's mobile carrier. `message.sent`, `message.delivered`, `message.failed` and `message.replied` carry `carrier`, and so does each message from `GET /conversations/{id}/messages`. See [Carrier values](/api-reference/webhooks/events#carrier-values). * Segment a list by carrier: the Segment Builder has a new **By Carrier** operation (AT\&T, Verizon, T-Mobile, Other carriers, Unknown), and an analyzed list has a **Split by carrier** card that creates one list per carrier with no second analysis charge. * My Organizations has a **Make default** button, so you can choose which organization you land in and leave the one that used to be your default. ## Changed * API: running analysis on a list is now billed per number, like the dashboard, and a retried request no longer charges twice. If your balance is too low nothing is queued, and a list with nothing left to analyze costs nothing. * API: you can now resume a paused project by scheduling it again. * A contact list that is still being analyzed can no longer be used on a project. Creating, scheduling, or resuming a project with one now shows a clear message asking you to wait until the analysis finishes. * Every card payment to your balance, manual or auto-recharge, now emails a receipt to your organization's billing email (or contact email). When your parent organization collects payments through its own Stripe account, the receipt comes from that account. * Adding someone who already has a Political Comms login now adds them right away. There is no invitation to accept: they get an email and see your organization the next time they sign in. * Deactivating a member turns off their access to your organization only. Their login and their other organizations are not affected. * Signing in lands you in an organization you can work in. A pending or inactive organization no longer blocks your others, and its screen lists your other organizations with a Switch button. * Accounts are no longer deactivated after 90 days without a login, and the warning email is gone. Sessions still expire after 30 days, so you sign in again. * A person's name, email, phone, password and two-factor reset can be changed by an organization's admin only when that admin manages every organization the person belongs to. Anyone can still reset their own password from the sign-in page. ## Fixed * The Segment Builder's Field Mappings now offer the custom tags you have already created, and each column starts on the tag it already uses, so a new segment keeps the same merge tags as the lists it came from. A segment built from another segment now shows its columns too. * Mapping columns on a list upload now offers custom tags you created on any of your lists, including lists that are not tied to a brand. * Buying a phone number that takes unusually long to confirm no longer leaves it stuck as "not available". You now see that the purchase could not be confirmed and that you were not charged, and the number is freed up again within a few minutes. * A project that fails to start now tells you right away, with a notification that it could not finish building its recipient list and a prompt to start it again. * A contact list read through the API now shows as processing from the moment its analysis is queued. * A project that paused at the daily T-Mobile limit now tells you to schedule it for the next day's sending hours instead of resuming at midnight Pacific, which falls in quiet hours. At the limit, recipients on other known carriers keep sending while T-Mobile and unknown-carrier recipients wait, so analyzing your list first means only T-Mobile recipients wait. * Daily limit counts now follow the day a message was sent, so a status report that arrives after midnight no longer closes the new day early. * Paused-project alerts now fire once per pause instead of repeating. * A sub-organization's project no longer pauses when its parent organization runs low while the parent's auto-recharge is already processing. Sending waits up to a minute for the recharge and then continues on its own. If the recharge fails, the project pauses and the parent is notified, as before. * Organization member counts now include members whose default organization is a different one. **September 28, 2026** ## Added * API: you can now check carrier sending limits before you send. A campaign's throughput shows its daily T-Mobile allowance, how much is used today and the AT\&T per-minute rates, and a project's throughput estimates whether it will pause at the limit and how long it will take. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). * API: a project now tells you why it is paused, whether the platform paused it, and whether it is running through the daily limit, so you can resume it instead of waiting for it to finish. ## Changed * Terms of Use and Client Agreement: interest on late payments is now capped at 1.5% per month, down from 18% per month. You will be asked to accept the updated agreements the next time you sign in. * API rate limit raised to **600 requests per minute per key**, up from 100. The limit is now the same for every scope; the separate write (60/min) and delete (30/min) tiers are gone. See [Rate Limits](/api-reference/rate-limits). * Bursts are now fine: the limit works like a bucket of 600 tokens that refills at 10 per second. After a burst you keep getting 10 requests per second instead of being locked out for the rest of the minute, so a sync that sends a few hundred calls at once no longer loses most of them to `429`s. ## Fixed * The API reference said the setting to run through the daily limit lasts for the life of the project. It holds until the next schedule or resume, so send it each time. * On a `429`, `Retry-After` and `X-RateLimit-Reset` now report when capacity actually frees (the moment the oldest request in the window ages out) instead of always reporting a full 60 seconds. Clients that honor the header retry in seconds rather than idling for a minute. * Admin > API > key usage: the Success Rate and Avg Response Time tiles showed 0 for every key. They now show real values, and a new Rate Limited tile counts the requests your key had rejected with `429`. * SDKs (`@political-comms/sdk` 0.12.1, `political-comms` 0.11.1 on PyPI): a `429` retry now waits for `Retry-After` first, then `X-RateLimit-Reset`, so a skewed local clock cannot stretch or shorten the wait. **September 26, 2026** ## Added * Data Exports: `message_events` now carries `updated_at`, and a message is exported again in the window that holds a later delivery status change, so your warehouse converges on the final status. Keep the row with the greatest `updated_at` per `message_id`. * A new Help Center page, [Data exports to your S3 bucket](/help/data-exports), documents setup, schedules, the file layout and every column of the four datasets. * Monthly invoices: Billing > Ledger lists your last 12 months, each downloadable as a branded PDF (usage by service, sub-organization usage, adjustments, refunds, payments) or a CSV of the same lines. Invoices are generated automatically on the first of each month. See [Billing](/help/billing#can-i-download-invoices-and-receipts). * Payment receipts: Billing > Payment Methods lists every payment added to your balance with a receipt PDF per payment. ## Fixed * Data Exports: each scheduled run now starts exactly where the previous run for the same destination and dataset ended, so a missed run no longer leaves a gap. A destination that fell behind catches up seven days per run. * Data Exports: a window with no rows no longer writes an empty file, and a failed run no longer leaves a partial file behind. * Data Exports: Parquet files are now SNAPPY compressed as documented; earlier files were written uncompressed. Existing readers need no change. **September 25, 2026** ## Added * Internal notes are now on the API: `GET /brands`, `GET /campaigns` and `GET /tracking-domains` each return a `notes` field (up to 100 characters, null when unset; tracking domains carry it on owned rows only). Notes are set in the dashboard and are never sent to the registrar or to recipients. * The bulk brand CSV template has an optional `notes` column; whatever you put there is stored on the imported brand and shown beside it wherever brands are listed or picked. * Tracking domains now take a short internal note, edited inline on the Domains page. * Test sends can now use values you supply for merge fields, from the test dialog or the API, instead of a contact from your list. Use one set for every number or a set per number. Leave a field blank to see its fallback, and survey follow-up questions use the same values. **September 24, 2026** ## Changed * Self-service email sending is now $2.50 per 1,000 recipients, and the optional dedicated IP pool add-on is $35.00 per month. Full-service email, list validation, and AI drafts are unchanged. See [pricing](/help/billing). **September 23, 2026** ## Fixed * Segments now show the real mobile, landline and other counts carried over from the lists they were built from, and the Analyze Numbers page works for them. Analyzing a segment only charges for numbers that have never been looked up; existing segments have been corrected. * Segments built from a project's results (failed, delivered, clicked, replied, no reply) now preview and build in seconds on large campaigns. They previously reported "too large to preview" and the build failed on ordinary campaign sizes. * Short code and toll-free projects now show the number's name and the number under the project name, on the dashboard, the schedule, the approvals page and the project report. They previously showed an empty brand and campaign line, since those projects have neither. **September 22, 2026** ## Added * Import brands from a CSV. On the 10DLC page, **Import CSV** takes a spreadsheet of up to 100 brands, lets you match its columns and choose the entity type and use case for the batch, checks every row and shows the total registration cost before anything is created, then registers all of them in the background. Each brand is billed at your normal registration price. ## Fixed * Projects now finish on their own the moment the last message has gone out. A project could sit at 99.99% (for example 52,174 of 52,175) even though every message had been delivered or failed, because the finish line was measured by a running tally that could miss a count, and the recount that should have caught it never ran while replies kept arriving. Completion is now decided from the actual send records, and the final numbers on the project page are recomputed from those records shortly after the project completes, so they always add up. * Newly registered brands no longer show "Registration Pending" longer than they should. Their status now updates on its own within a couple of minutes even when the registry is slow to report back, and the 10DLC page refreshes statuses while brands are settling, so there is no need to sync manually. * Very large projects now send at full speed from start to finish. A project with two million recipients previously slowed to a crawl after the first half hour and did not finish in its sending window. Sending now runs several parallel lanes for large audiences, the sending fleet no longer shrinks in the middle of an active send, and the platform's capacity is reserved rather than opportunistic, so a busy evening cannot leave a send waiting for machines. * STOP replies during a large send no longer slow down delivery reporting. Delivery and reply updates could lag by more than an hour after a big send; they now keep pace. Opt-out list counts on the Contact Lists page can trail the latest opt-outs by a few seconds. **September 19, 2026** ## Changed - Email is generally available. The early access notice is gone from the API reference: email write endpoints require the email entitlement on your organization and return `403 ENTITLEMENT_REQUIRED` without it, and reads are open. - Toll-free messaging is now priced the same as 10DLC for new organizations. Short code messaging has its own lower per-message rate. Inbound SMS is included on every channel. - The dedicated IP pool add-on for email is now $35.00 per month. ## Added - Full-service email: our team sets up your sending domain and builds and sends every campaign, at $0.01 per email plus a \$1,000 one-time setup, with no monthly fee. **September 17, 2026** ## Changed * Carrier sending limits now slow down only the recipients they apply to. When a carrier's per-minute or daily limit is in use, recipients on every other carrier keep sending at full speed, and the send page tells you which limit is in effect and that it clears on its own. Projects on brands with a per-minute limit now front-load a large block of that carrier's messages and let it drain at the allowed rate instead of pausing every minute. The launch summary quotes the estimated number of recipients on the daily-limited carrier so the pause choice is an informed one. * Conversation threads read through the API now report a failed message's error code in the same short form the message.failed webhook and CSV exports already use, and platform-side outcomes that are not delivery results are left blank. Delivery error descriptions have been reworded in plain platform terms. See [Delivery error codes](/api-reference/webhooks/error-codes). * A custom domain that is waiting on a DNS record now reminds you once a day, not every few minutes, and the Domains page shows how long the platform will keep waiting. Every step that needs a record from you has the same seven-day window; after it the setup stops and the setup fee is refunded, and a retry starts again from that step. * If a certificate request expires before its validation record is published, the platform renews the request on its own. The record you were given does not change, and nothing is refunded or charged again. ## Removed * The organization-wide **Donation page URL** email setting and its `{donate_url}` tag. Paste the donation link into the button itself; a button saved without a link is now flagged before sending. ## Fixed * A Campaign Verify token generated in one organization and applied to a brand in another is now treated as an import for that organization: it shows as imported with its expiry, keeps its own copy of the verification, and no longer offers token generation. The organization that generated the token keeps its original verification. Imported verifications are now labelled in the Campaign Verify list. * When a DNS record is entered with the domain repeated at the end (which some registrars do automatically when you paste a full hostname into the Name field), the Domains page now says exactly where the record was found and what to type instead, rather than reporting it as missing. * The Domains page now names the DNS provider for app and link-tracking domains, the way it already did for email domains. * Adding an email sending domain that already has a mail (MX) record no longer stops setup. Sending is unaffected by that record, so the check ignores it. * When you add a domain for email, the sending domain now defaults to the domain you typed (so senders are [hello@yourdomain.com](mailto:hello@yourdomain.com)), instead of a `mail.` subdomain. You can still change it to a subdomain before continuing. **September 16, 2026** ## Added * If you manage sub-organizations, an owner or admin can now set a sub-organization's credit line and create, edit, cancel, or forgive its spend commitment from **Admin > Organizations**. See [Billing](/help/billing) for how commitments work. ## Fixed * Pausing a project and resuming it with a scheduled time now keeps every message that was already in progress on hold until the scheduled time, and sends it then. Previously those messages could be dropped and had to be recovered by hand. **September 15, 2026** ## Fixed * Message sending was interrupted between 8:54 AM and 10:47 AM ET after a change on the carrier gateway side rejected every outbound request. Projects that ran during the window were refunded. The platform now stops itself within seconds if the gateway starts rejecting every request, instead of letting a project run to completion. * Removing the image from an MMS project now saves. Previously the save succeeded but the image reappeared on refresh. * **Short Code** is back in the Text menu for every organization. **September 14, 2026** ## Added * Some features now require enablement by Political Comms. An API call to a feature your organization is not yet entitled to returns `403 ENTITLEMENT_REQUIRED` instead of succeeding; contact support to request enablement. See [Error Handling](/api-reference/errors) for the full list of entitlement keys. * Sending can now be paused for an organization or platform-wide by Political Comms. A create or send call made while paused returns `409 SENDING_PAUSED`. See [Error Handling](/api-reference/errors). ## Fixed * The **Data Export (CSV)** on a project report now lists every recipient in the project's audience, including anyone who was never sent a message because the project was paused, stopped, or is still sending. Those rows show **Not sent** in the Message 1 Disposition column, so the row count matches Total Recipients minus Ineligible. **September 12, 2026** ## Fixed * The **Messages** column on the billing ledger and in the ledger CSV export is now exact for every row. It previously showed a dash whenever a day combined more than one send batch for the same project. **September 11, 2026** ## Added * 10DLC brands can now carry a DBA (doing business as) name. Enter it as the optional **DBA / Display Name** on the brand form and it is registered as the brand's display name, with your legal name kept separately. Leave it blank to register under the legal name as before. **Use Org Profile** fills it from the organization profile's DBA. ## Fixed * Survey test sends now fill merge fields on every question, not only the first. The whole test reads as one recipient from the project's contact list; with no list, tags resolve the way they would for a recipient with an empty field. * A test message never borrows contact data from another account. * Survey results, the responses list, and the survey CSV export no longer include answers given on test conversations. * Random Sample operations in the segment builder estimate and build correctly again. Since August 15 they previewed as 0 contacts, and a segment built from one failed. **September 9, 2026** ## Changed * An EIN is no longer required to finish account setup. Leave it blank if your organization does not have one; brand and toll-free registrations ask for it when a carrier needs it. * The business profile is now your organization profile. The setup step opens already filled in with the name, address, and contact you gave at registration, so most organizations only choose an entity type and industry vertical. Business details live on **Admin > Organization > General**; the separate Business profile tab is gone. ## Fixed * Sub-organizations whose billing is managed by their agency no longer see an auto-recharge step or a prompt to add a card. The funding step names the agency that adds balance for them, and the agency's owners and admins get the day-7 and day-12 setup reminders for those sub-organizations. **September 8, 2026** ## Added **Gmail Verified Sender Program** Committees with a verified Campaign Verify identity can now submit a sender address to Google's Gmail Verified Sender Program straight from the sender identity page, with pre-submission checks, the exact address to enter, and status confirmed from Google Postmaster Tools once submitted. Verified status shows on the senders list, the campaign sender picker, **Admin > Domains**, and your Campaign Verify page. See [Gmail Verified Sender Program](/help/email/gmail-verified-sender-program). Over the API, a sender now reports its Gmail verified sender status and the dates it was submitted and verified. ## Fixed * The business profile form now marks the exact fields that still need attention instead of a bare "Validation failed", and an EIN typed as "N/A" or "Applied for" is called out as not an EIN rather than reported as blank. * Over the API, `VALIDATION_ERROR` responses now name each rejected field in `details[].field`. See [Errors](/api-reference/errors). * Sub-organizations that have not uploaded their own logo show their agency's logo and favicon again. Some showed the agency's name as text instead. **September 7, 2026** ## Added * Your integration can now hold a two-way conversation: reply inside a thread, read it, and list conversations with inbound replies. Guide: [Two-Way Conversations](/api-reference/two-way-conversations). ## Fixed * The DMARC summary, sending sources, and policy recommendation pages load again; they had returned an error since September 3. * Chat replies to an opted-out contact or a deleted project are refused before any charge, and a billed-but-unsent reply is refunded. * Releasing a phone number pauses any project still sending from it. * A project with link tracking on can no longer be saved without a tracking domain, which used to send unattributed links. * RCS can no longer be picked for a project. It was accepted at save, then failed at send. * CSV exports no longer split a record across two rows when a field contains a line break. * A batch send retries briefly-refused messages rather than billing them and failing them. * Two-factor changes and trusted devices are recorded in your audit log again. **September 6, 2026** ## Added **Guided account setup** New organizations start on a three-step checklist: business profile, funding, and auto-recharge. You have 14 days to finish the first two, after which creating anything new is blocked until you do, while everything already set up keeps running. **Business profile** Your legal details now live on **Admin > Organization > Business profile** and prefill your 10DLC and toll-free verification forms. **Organization signup links** Create a revocable signup link from **Admin > Organizations**, and anyone who registers through it becomes an active client organization one tier below yours. **Multi-org accounts** One login can now belong to more than one organization, each with its own role and brand access, switchable from your account menu. **Invite existing accounts** The Users page can invite someone who already has an account, and **Transfer ownership** moves the Owner role in one step. ## Changed * A paused project's message can be edited after some messages have gone out; recipients still on hold get the update when it restarts. ## Fixed **Pausing stops sending within seconds** Pausing holds every message that has not gone out, where previously ones already lined up kept sending. ## Removed * Archiving is gone everywhere. Completed is now the final state for a project, and its report stays available. **September 5, 2026** ## Added **Bring your own Stripe** * Reseller organizations can connect their own Stripe account from **Billing > Payment Methods**, so sub-organization recharges carry your descriptor, payout schedule, and disputes. See [Bring Your Own Stripe](/help/bring-your-own-stripe). * Charges route to the direct parent organization's connected account, so each tier needs the tier above it connected. * If a reseller's Stripe account is disconnected, affected sub-organizations are refused new cards and recharges right away and billing roles are notified. ## Changed **Email templates: a document editor, not a canvas** The email template designer is now a document editor: write the email like a document, press `/` for a menu of blocks and `@` to insert a merge tag as an editable pill. A Design rail sets colors and fonts, and a Checks panel shows compliance and message size against Gmail's clipping limit next to a desktop and mobile preview. Pasting from Google Docs or Notion keeps your formatting, and **Draft with Lincoln** now returns editable blocks. Templates come in two kinds: built in the editor, or imported as HTML. An editor template can be converted to HTML, which is one-way, and until it is converted it has to be edited in the dashboard rather than over the API. ## Removed * **The Payouts page** and the manual payout request flow. Payouts are now handled entirely in the reseller's own Stripe dashboard. * **The Agency Mode setting.** The features it controlled are unchanged, just no longer behind a single toggle. **September 4, 2026** ## Changed **A smaller, clearer email API** The public email API is about half the size, with list curation, validation, exports, test sends, and Lincoln drafting moved to the dashboard, and the reference regrouped as Text, Email, Assets, Billing & Usage, and Admin. **The file you upload is the list** The CSV you upload becomes the list, named after the file, instead of asking you to create a list first. **One kind of list** Any email list can now be chosen as a campaign's suppression list, and lists are scoped organization-wide or to one sending domain. **Unsubscribe files** Upload them under **Assets > File Uploads > Email unsubscribes** and they apply automatically to every campaign in their scope. **Faster, more accurate validation** A 100,000-address list finishes in tens of minutes instead of hours, and catch-all domains are actually tested rather than assumed deliverable. **A simpler sender page** Setup, health, deliverability, the Gmail program, and settings now run in one column, so each requirement appears once. ## Fixed * Warm-up progress counts down sending days rather than calendar days, because a day with no sending does not advance the ramp. **September 3, 2026** ## Added **Branded link domains** Every campaign link, the open pixel, the unsubscribe page, and view-in-browser now use the tracking domain you pick under **Link domain**, so link reputation stays with your own domain. **Download a list's validation results** **Export results** downloads a CSV of your uploaded file plus every verdict, filterable to just the undeliverable addresses. ## Fixed **Text Dashboard loads in under a second** It could take 5 to 30 seconds because replies were counted across every conversation on the page. **You stay signed in** Refreshing from two tabs at once could sign you out. A session now lasts 30 days from sign-in. **Domains: record status and Verify now** Active domains showed their DNS records as "Pending" even though they were live. **Email domain pre-flight** The Add domain check was failing silently, so it never warned you about a conflicting SPF record. **September 2, 2026** ## Added **Email is in early access** Political Comms now sends email alongside text: sending domains you verify with your own DNS records, From addresses with the CAN-SPAM address and paid-for-by disclaimer in every footer, lists with recorded consent, suppressions, and campaigns with scheduling and warm-up ramping. There is no inbox surface and no A/B testing. **Email pricing** \$1.50 per 1,000 recipients, plus optional list validation and a dedicated sending add-on. Sending domains and hosted unsubscribe pages are free. **The email API is published** Domains, senders, lists, suppressions, campaigns, and five new outbound webhook events, all refused until general availability so you can build against a stable contract. **Test sends are required** Every email campaign needs a successful test send before it can be submitted, and editing the content or recipients invalidates it. Approval is now a per-campaign toggle. **Lincoln drafts email templates** **Draft with Lincoln** turns a description, your images, and your brand colors into a finished subject, preheader, and design for **\$3.00 per draft**. ## Changed **One page for every upload** Uploading is now one flow at **Assets > File Uploads**, where you choose the kind first. **API keys and webhooks live on one Admin page** They are now a single **API** page with three tabs, each shown only to roles with that permission. **August 31, 2026** ## Added **Send each recipient to their own destination URL** A link tracking destination can now be a whole-URL placeholder instead of one fixed link, so each recipient's tracking link goes to the URL stored in their own contact field. You must also set a fallback URL, which catches recipients whose field is empty or invalid. Each recipient's destination is locked in when their link is created, so the click export always shows the real URL that person was sent to. **August 28, 2026** ## Changed **Generated files expire after 90 days** Billing exports, report PDFs and data exports are now actually removed after the 90 days their expiry date has always shown. ## Fixed **WinRed lists with "SMS opt-in required" now add donors** They were adding none at all, because the consent check looked for field names WinRed never sends. **Campaign Verify state and local submissions accepted again** Campaign Verify began requiring a second jurisdiction field, so every such submission was rejected. **Short code projects can be created and edited** A project assigned a short code was rejected at save because the number was checked against the 10DLC pool. **Exports no longer email the requester** The only email a report sends is the one you address yourself from its Email dialog. **Dialogs and headers fit a phone screen** Dialogs scroll inside themselves and header actions wrap instead of pushing off-screen. **August 27, 2026** ## Added **Ledger rebuilt** The Ledger page under Billing & Usage now has one filter bar covering dates, entry types, services, sub-organization, and a search across projects, lists, numbers and brands, and every filter, sort, and export responds in milliseconds across a full year. **Sub-organization spend** Organizations with sub-organizations see what each direct sub-org was charged, what those sends cost you, and the margin between them. **Responses (CSV)** A project report can now download every inbound reply, one row each, with the message it answered and, for surveys, the matched answer. ## Changed * Billing exports over long date ranges no longer time out on high-volume accounts. * Notification emails no longer show "January 1, 1970" or "\$NaN" in place of a missing value. ## Fixed * For part of August 27, a reply to a broadcast opened a new conversation instead of continuing its thread. Replies were still delivered and honored for opt-outs, and affected conversations are being consolidated. * Opening the Ledger no longer errors for organizations whose entries did not fit on one page. * Downloading a previous ledger export now returns the file that was actually generated. * Ledger days are counted in UTC, so the newest charges no longer go missing if you are west of UTC. **August 25, 2026** ## Fixed **Sub-organizations blocked by a parent's balance are now paused and told** Charges roll up, so a parent that runs out of funds blocks its sub-organizations from sending even when their own balance is healthy. That block used to be invisible: the project kept retrying, and the parent, the only one who could fix it, had no idea. Now those projects are paused with the reason "insufficient funds (parent organization)", the parent's billing admins are notified, and both organizations see a banner until funds are added. Over the API, an insufficient balance error tells you whether the shortfall is yours or a parent's. **August 24, 2026** ## Added **Choose how a scheduled project handles the daily carrier limit** T-Mobile limits how many of its subscribers a vetted brand can reach each day, and a project simply paused when it hit that limit, so a large send could take several days and several manual restarts. You can now choose, when you schedule or resume a project, to run straight through to completion in one pass instead. Messages to T-Mobile recipients beyond the daily limit may fail, and failed attempts are still billed. Leave the setting off and the project pauses at the limit exactly as before. **August 22, 2026** ## Added **Download all your project exports as a single ZIP** The Downloads menu on a project report now bundles every export into one archive named after the project, and fails with a specific reason rather than handing you an incomplete bundle. **Survey report emails now include the survey responses** Emailed survey reports arrived without the responses themselves; they now carry all three files. ## Fixed * Report PDFs no longer fail to generate on projects with a lot of link-tracking data. * If the report page cannot load its data in time, generation stops and tells you, instead of handing you a PDF that reads "Failed to load report data". * Report and export failures now name the actual cause instead of a generic "Server error". **August 20, 2026** ## Changed * A unique click counts a distinct **device and network**, not a distinct person. See [Webhook events](/api-reference/webhooks/events) for the full explanation. ## Fixed **Link tracking: per-link click details, a corrected unique-click count, and Android taps no longer filtered** The **Top Performing Links** table showed 0 unique clicks and no click times for every link, and dropped links whose contact record was missing. The data was recorded correctly the whole time, so nothing needs to be re-run. The headline **Unique Clicks** figure was overstated because it added up per-day counts, double-counting a supporter who clicked on two different days. It is now a single count of distinct devices across the whole window, with **repeat clicks** alongside. Expect existing campaigns to drop slightly; the new number is accurate. Taps from **Google Messages**, the default texting app on most Android phones, were being filtered out as automated traffic and now count. **August 8, 2026** ## Added * Project stats now report test-send activity separately from real traffic, so test clicks no longer inflate your real totals. The split is forward-only; test clicks recorded before this change stay in the production counters. ## Changed * Scheduling a project no longer requires a start time at least 60 seconds out. Any valid time is accepted, and the project starts sending as soon as audience compilation finishes. **August 7, 2026** ## Added * A new [Delivery error codes](/api-reference/webhooks/error-codes) page documents every failure reason a failed-message webhook can report, plus which failures are permanent, temporary, or sender-side. ## Fixed * Failed-message webhooks now always include a readable failure message, and send-time and carrier-reported failures use the same short codes documented in the [error codes reference](/api-reference/webhooks/error-codes). If you matched on the old long codes, match on the documented short ones instead. **August 4, 2026** ## Added * All four message webhook events now say whether the message was a test, so you can separate test traffic from real sends. Identifier meanings are documented in a new [Identifiers](/api-reference/webhooks/events#identifiers) section. ## Fixed * Every unique click now delivers a click event. Previously only the first came through and further ones were silently suppressed for 7 days. * The dashboard's **Send test webhook** button now produces a payload that matches real traffic exactly. * Message webhooks deliver phone numbers and timestamps exactly as documented in [Event Types](/api-reference/webhooks/events). If you worked around the old shapes, switch to the documented ones. * Webhook signature validation now works; verification against the raw request body always failed before, so if you skipped it, re-enable it. See the [signature validation guide](/api-reference/webhooks/signature-validation). * Failed webhook deliveries now make all four documented retry attempts instead of stopping after three. **July 31, 2026** ## Added **Link parameter placement** A tracking link's destination URL can now carry the selected link parameter anywhere in the address instead of always appending it, which supports providers that only echo back one specific field. URLs without a placeholder behave exactly as before. **Opt-out footer control on the API** You can now turn the automatic STOP footer on or off per broadcast project over the API, matching the toggle in the composer. It defaults to on, and surveys never carry it. ## Fixed * Editing a project no longer silently clears a saved link parameter, and clearing one back to "None" now sticks. **July 30, 2026** ## Added **Official SDKs, CLI, and MCP Server** Four official packages are now published: [`@political-comms/sdk`](https://www.npmjs.com/package/@political-comms/sdk) (TypeScript), [`political-comms`](https://pypi.org/project/political-comms/) (Python 3.10+), [`@political-comms/cli`](https://www.npmjs.com/package/@political-comms/cli), and [`@political-comms/mcp`](https://www.npmjs.com/package/@political-comms/mcp), which lets Claude and other MCP clients manage projects, contact lists, media, analytics, and billing. Source: [Political-Comms/political-comms-sdk](https://github.com/Political-Comms/political-comms-sdk). **Versioning and deprecation policy** The API's guarantees, including the 90-day sunset window, are now documented on a dedicated [Versioning & Deprecation](/api-reference/versioning) page. ## Fixed * Several developer-facing documents misstated the API rate limit as 100 requests per hour. The real limits, per key per minute, are 100 reads, 60 writes, and 30 deletes, which is what the API has always enforced. **July 29, 2026** ## Added **Delete contact lists and media files over the API** Deletion is blocked while a scheduled, sending, or active project depends on the item, and the error names the blocking projects. **Copy and archive projects** You can now duplicate a project over the API: message content, media, numbers, link tracking, and survey questions carry over, while contact lists, the schedule, and stats do not. **Create projects without a contact list** Contact lists are now optional at creation. Leave them out and the project is created as a draft; attach lists later and it moves on automatically. ## Improved * Dozens of situations that showed "An unexpected error occurred" now tell you what is wrong and how to fix it, including two-factor setup, CSV imports, exports, and user management. * Submitting a toll-free verification now shows the real rejection reason, and stuck drafts can be deleted. **July 27, 2026** ## Added **File URLs on the media API** Listing or reading a media file over the API now returns a direct URL for the file, alongside its size, content type, and status. Previously you only got identifiers and names, with no way to fetch the file itself. The URL is stable for the life of the file, which makes it usable as a verification baseline. Two things to know: it is empty until the file is ready, and it should be treated as opaque rather than rebuilt from the file name, because the stored name can differ. **July 26, 2026** ## Improved **Cost estimates that match what actually bills** The composer's cost estimate now reflects real message lengths per recipient, with personalization filled in from your actual contact data, and shows a message-parts range with the matching cost range. **July 24, 2026** ## Added **Dynamic Lists tab and Anedot integration** Contact Management has a new Dynamic Lists tab for lists that keep themselves up to date, and Anedot joins WinRed as a donation-platform integration: paste your secret and qualifying donors flow into a list automatically. **Recent clickers and recent repliers lists** Two new self-updating lists built from contacts who clicked a tracking link or replied, over a 30, 60, or 90-day window or all time, with no analysis cost. ## Fixed **API reference corrected against live behavior** A full audit of the [OpenAPI specification](https://politicalcomms.com/openapi.json) found many documented shapes had drifted; every documented request and response now matches what the API actually returns. If your integration was built from live responses, nothing changes for you. The corrections include [Error Handling](/api-reference/errors), which now documents the three real error shapes. **July 23, 2026** ## Added **Automatic pause on carrier blocking** If carriers start blocking a send as suspected spam, the project now pauses itself instead of burning the rest of your budget on messages that will not deliver. Managers are notified with the reason, and resuming starts the check from a fresh window. **July 22, 2026** ## Added **Lists that analyze new contacts automatically** Dynamic lists can now analyze new contacts as they arrive, an opt-in billed at the normal analysis rate. Scheduled projects also pick up contacts their lists gain after scheduling. ## Improved **Shorter tracking links** Tracking links now drop the "https\://" on domains phones still make tappable, saving 8 characters, often the difference that keeps a message inside one billed segment. **July 20, 2026** ## Added **Survey report: response rate, nudge history, and unread badges** The survey report now shows an initial response rate and a per-question history of nudges sent. "Poke" is now called "Nudge" everywhere, and the Chat button on the projects dashboard shows a red badge when a project has unread conversations. ## Fixed **Incoming replies recovered** A bug introduced in early June silently dropped incoming replies from contacts who had not messaged you before. It is fixed, and the dropped replies were recovered and delivered to their conversations. **July 16, 2026** ## Added **Survey projects on the API** The [Projects API](/api-reference/introduction) can now create and run surveys, not just broadcasts: questions with branching, per-question media, merge tags and tracking links, and the AI response analysis toggle. A new results call returns the same topline results as the dashboard. **Idempotency keys on API writes** Every API write now honors an optional `Idempotency-Key` header, so retrying within 24 hours returns the original response instead of running twice. See [Error Handling](/api-reference/errors) for the retry rules. ## Changed **New Jersey voter data paused** Voter-data purchases for New Jersey are paused while the industry works through the state's new data-broker law (A.5328). Every other state is unaffected, and lists you already own are untouched. **July 15, 2026** ## Added **WinRed report feeds for vendor accounts** WinRed vendor-level accounts can now feed contact lists through WinRed's scheduled report exports, with no per-committee setup required. Choose one combined list or a list per committee. ## Fixed **Merge tags and messy CSVs** Contact files with stray line breaks inside a field could push a line break into your message right before a personalized name. Values are now cleaned at import and again when the message renders. **July 14, 2026** ## Fixed **Personalization on WinRed lists** WinRed lists had no personalization fields available in the composer. Donor fields such as first name, last name, and city now work on all WinRed lists, including ones created before this fix. **July 9, 2026** ## Improved **Streamlined campaign registration** The 10DLC campaign registration form now starts from your organization type: pick it, and the form fills in a sensible default use case, sample messages, and the correct compliant opt-in website automatically. **July 8, 2026** ## Changed **Updated legal agreements** The platform agreements have been revised. Everyone is asked to re-accept once at their next sign-in; your account and sends are unaffected in the meantime. **July 7, 2026** ## Added **Custom roles and permissions** Organizations can now define their own team roles with exactly the permissions they choose, on a new Roles & Permissions page. Navigation and page access follow each member's permissions automatically. **Broadcast and survey filter** The projects dashboard can now filter by project type. ## Improved **Survey question numbering and reordering** Question numbers in reports and exports now match what recipients actually see, and reordering uses up and down buttons instead of drag-and-drop, which fought your text selection. **July 6, 2026** ## Added **Sign in with a passkey** You can now sign in with a passkey, using Face ID, a fingerprint, or a hardware security key, as a phishing-resistant alternative to a password plus an authenticator code. Your existing password and two-factor setup keep working. **July 3, 2026** ## Added **Template library** * Save broadcast messages, survey questions, or whole surveys as reusable templates shared across your organization, and pull them into a new project from the builder. **Survey nudges** * Re-engage people who stalled mid-survey by re-sending the question they stopped on, with the eligible count and cost shown before you send. ## Changed * Project creation is rebuilt as two columns: settings on the left, a live phone preview and running cost estimate on the right, plus a checklist of what is still missing before the project can send. * Survey reports now show per-question response totals and drop-off percentages, so you can see exactly where people quit. **July 2, 2026** ## Added **AI survey analysis** * Surveys can now read free-form replies, so an answer like "Yeah, of course, absolutely" counts toward the option it expresses and follows that option's branch instead of landing in "Other". Turn it on per survey at \$0.05 per analyzed reply; exact matches stay free. **Linc can answer account questions** * The Linc support assistant can now look up your own account data, including delivery totals, contact lists, registration status, and billing history, without ever seeing individual contacts, message bodies, or free-text answers. ## Fixed * Large sends no longer slow the rest of the platform down, the overnight stalls some accounts saw are gone, and a duplicated inbound message can no longer be billed twice. **July 1, 2026** ## Added **WinRed integration** * Pipe WinRed donors and leads straight into a contact list: create a WinRed list under Contact Management, paste the generated URL and secret into WinRed, and every qualifying donation or lead lands in the list with donor details usable as merge tags. * Each WinRed list has its own opt-in requirement, automatic removal on refunds and disputes, and a rolling retention window based on the donor's last WinRed activity. **June 30, 2026** ## Added * Your organization can now be granted a credit limit, so sending continues past a \$0 balance down to the agreed line, with your remaining spendable funds shown in the header balance tooltip and on the Payment Methods page. Setting a credit line turns auto-recharge off; contact your account representative to set one up. **June 29, 2026** ## Added * You now get an email whenever a 10DLC campaign is rejected at any stage, including early rejections that previously notified nobody. ## Changed * A design pass across the whole app: softer corners, layered shadows, clearer table headers, and subtle motion that respects your reduced-motion setting. * When a 10DLC brand fails registration, the brand page now explains why in plain language and lets you edit and resubmit right there, free of charge. ## Fixed * A custom domain is marked active only once your final DNS record resolves, and shows the exact record to add until then. * The composer's character and segment counter now matches what carriers send and what you are billed. * Billing export and ledger line items now carry their real signs instead of showing everything as positive. **June 17, 2026** ## Added **Organization-wide segments** * The segment builder now offers "All brands" and "All projects" scopes, so you can build an audience like everyone who clicked a link anywhere in your organization. **Default merge-tag values** * Set a default for each merge tag once in Organization Settings, used whenever a contact is missing that field. **Quiet hours** * Messages no longer send between 10 PM and 8 AM in each recipient's local time, and a project still sending at 10 PM pauses itself. **Campaign Verify expiration tracking** * The list now shows a Valid Until date for each authorization and warns you by email before it lapses. **Campaign goals for Linc replies** * Projects gain an optional goal and extra context, and Linc steers drafted replies toward it. ## Fixed * Brands no longer sit on "Vetting Pending" after vetting finishes, and re-testing a project sends from its current numbers. **June 12, 2026** ## Added * A new "By Area Code" segment operation lists the area codes present in a contact list, grouped by state with counts, so you can cut a list geographically. * Search on the Media Files page now covers your entire library, and the media picker has its own search box. * Accounts approaching the 90-day inactivity suspension get a warning email 7 days ahead. ## Fixed * Survey follow-up questions now reach everyone who answered the first question, and stalled conversations were sent their pending question. * Survey questions bill by their own SMS or MMS setting, and cost estimates model the real response funnel. * The failed-attempt lockout now shows a clear message with a live countdown. * Rapid clicking on manual send can no longer double-bill, and a scheduled campaign can no longer stall at activation. **June 4, 2026** ## Added **Multiple phone numbers per project** * A project can now send across up to 49 phone numbers, and every later message in a conversation comes from the number that started it. **Schedules page** * A new Schedules page under Projects shows every scheduled send, past and upcoming, as a grouped list or a month calendar. **Choose your tracking-link parameter** * You can now pick which contact field a tracking link passes to your destination, or none, which is the new default. **Toll-free in the public API** * The API now lists toll-free verifications, includes toll-free numbers, and creates toll-free projects. ## Fixed * Toll-free sends were billed at 10DLC rates. Corrected, and toll-free rates are now visible on the pricing pages. * Dependent geographic filters in a data purchase now list only values inside the counties you already picked. **May 29, 2026** ## Added * Contact lists, media files, and opt-out lists can now belong to a toll-free registration, just as they can belong to a brand, and STOP replies on toll-free projects are recorded against that registration's own opt-out list. ## Changed * Contact imports now check numbers against real numbering rules, so invalid numbers are flagged at import instead of failing later. ## Fixed * Being signed out on every page refresh, or roughly once a day, is fixed, including the shared-office-network case. * One failed renewal charge can no longer release your phone number; it starts a grace window with an email so you can top up. * Toll-free verification submissions are more reliable: formatting rejections are fixed and status updates no longer go missing. * Purchases, chat replies, and saves made while viewing as a sub-organization now happen in that organization. **May 27, 2026** ## Added **Toll-free texting, end to end** * A complete toll-free path now sits alongside 10DLC: buy a toll-free number, complete carrier verification with a form you can save as a draft, and send once it is verified. **Aristotle voter data** * Aristotle (VoterListsOnline) joins L2 as a second data provider, with political filters and itemized quotes showing what each add-on costs. **Survey authoring matches broadcasts** * Every survey question now supports MMS media, merge fields with fallbacks, accurate segment counting, and link tracking. **Survey exports carry list columns** * Survey exports now include the same audience columns as data exports. ## Changed * The character and segment counter fills in realistic merge-tag values, so a personalized message is no longer over-counted. ## Fixed * Contact list uploads no longer land in "Failed", and report-ready emails send again. **May 19, 2026** ## Added * Setting up a recurring data export is now a single screen: give a bucket and access credentials and exports start flowing. ## Fixed * Large data exports finish faster and no longer get stuck showing "Running" for an hour. **May 18, 2026** ## Added * Contact-list uploads now handle CSV files with no header row or with blank header cells, explaining what was detected with a one-click toggle between "first row is headers" and "first row is data". ## Changed * Large contact-list uploads of 50,000 rows and up now finish in minutes rather than tens of minutes, completing as soon as your contacts are in. **May 13, 2026** ## Added * The Campaign Verify form now explains what to do when your filing information is not published online, covering the two paths Campaign Verify accepts and how to use `https://forms.irs.gov/` as the Filing Record URL. **May 9, 2026** ## Added * The message editor now warns you before you send when your message uses a public link shortener, which carriers commonly block, or repeats opt-out instructions that the required footer already adds. Both warnings are dismissible and neither blocks sending. **May 3, 2026** ## Changed * The project chat screen is rebuilt for clarity and space, with contact avatars, unread badges, more readable timestamps, and a composer that stays pinned when the phone keyboard appears. **May 2, 2026** ## Added * Uploaded media files now show their progress and survive a page refresh, so uploads no longer disappear mid-compression, and the composer hides media that is still processing so you cannot attach it by mistake. ## Changed * Home page metric cards load instantly for organizations of any size, including parent organizations with many sub-organizations that used to render blank. * Filtering and counting against the L2 voter file is much faster, and saved searches load quickly instead of redoing the work. * Reports start downloading within seconds instead of waiting for the whole file. ## Fixed * On white-labeled custom domains, two-factor authentication was prompted at every login and ignored "Remember this device". Trusted devices are now remembered everywhere. * A small number of projects stayed stuck in Sending after all their messages had finished, and now move to Completed correctly. **May 1, 2026** ## Added * Project test sends now accept several phone numbers separated by commas, so you can check a campaign on multiple devices in one send. ## Changed * Image and video compression is tuned for cleaner MMS, and photos taken on a phone keep their orientation through upload. **April 27, 2026** ## Added * Build a custom voter universe in-app with live filters and an estimated count, then buy the resulting list with a credit card. Purchases arrive as CSV or JSON and stay downloadable from the new Purchase History tab, billed separately from your platform wallet. **April 23, 2026** ## Added * External tools and partners can now build, test, and schedule projects entirely through the public API, so everything the in-app build flow does is available programmatically. * When you attach a media file in the composer, its thumbnail, filename, and size appear inline, so you always know which file is attached. ## Fixed * Number lookups are steadier: slow lookups are no longer cut off mid-job, and lookups you have waiting complete more predictably. **April 19, 2026** ## Added * Parent organizations can become resellers with an in-app verification flow and receive payouts to their own bank account on a daily, weekly, or monthly schedule when a sub-organization adds funds. Any organization can now save a payment method on file. **April 17, 2026** ## Added * Survey questions can now branch on each answer, sending Yes to one question and No to another, or skipping straight to the end, with branch targets updating themselves when you reorder or delete questions. ## Fixed * Copying a project now keeps the opt-out footer setting from the original, and copying a survey is all-or-nothing, so a failure part way can no longer leave you with half a survey. **April 6, 2026** ## Added * Enterprise accounts can now stream project and message data to your own Amazon S3 bucket, Snowflake, or Databricks on an hourly or daily schedule, with a Data Exports admin page to manage destinations, watch job history, and trigger a one-off export. **April 4, 2026** ## Changed * Opt-out detection now catches many more phrases and typos, including "stip", "srop", and "remove me". That is roughly 700 more opt-outs caught per day, which keeps your lists cleaner and more compliant. **April 3, 2026** ## Added * Link tracking now filters out bot clicks automatically, so your click analytics reflect real people. **March 30, 2026** ## Added * Archived projects can now be copied to create a new active project. **March 28, 2026** ## Fixed * MMS media no longer changes quality when it is sent to carriers. **March 25, 2026** ## Added * Seven new read-only additions to the public API let you pull more of your data programmatically. **March 23, 2026** ## Added * You can now export your API configuration as a Postman collection for easy testing. **March 22, 2026** ## Changed * The dashboard loads much faster. Pages that took several seconds now open instantly. * Delivery status updates arrive noticeably sooner. * Message sending capacity is doubled, so large campaigns finish considerably faster. **March 20, 2026** ## Added * Organizations can now set custom pricing for 10DLC brand registration and campaign vetting. ## Fixed * The Campaign Verify submission form no longer shows validation errors on valid entries. * Project cost on the dashboard showed less than the actual cost. Corrected. * Large sends with link tracking could lock the platform up under heavy click volume. Redirects are now stable no matter the send size. * Sending speeds set on a campaign were not being applied. Fixed. * MMS previews now display in survey projects. * Survey projects no longer show validation errors on valid entries, and an edited survey now correctly requires a re-test before sending. **March 12, 2026** ## Fixed * A campaign using link tracking could freeze the dashboard while it was sending. Fixed. **February 28, 2026** ## Added * Agency Mode lets you manage several organizations from one admin interface, switching between clients in one place. * You can now duplicate an existing project to start a new campaign with the same settings. ## Fixed * Reply metrics now exclude opted-out recipients, so they reflect only active, opted-in people. **February 22, 2026** ## Added * In-app notifications now alert you to project completions, low balance, payment confirmations, and more, with full history behind the bell icon. * The billing page gained search and filtering for recurring charges. ## Fixed * Phone numbers and 10DLC campaigns were not always billed on their recurring schedule. Fixed, and every missing charge was backfilled. * You now get a notification when a scheduled project completes successfully. **February 20, 2026** ## Added * Dropdowns across the platform gained search and filtering, so finding the right option is faster. * Realistic iPhone message previews appear throughout the platform to show how your message will look to recipients. * Non-political brands get a streamlined vetting flow, which makes approval for messaging easier. ## Changed * Brand setup, campaign verification, and campaign creation flows are smoother and more intuitive. ## Fixed * Login error messages are clearer about what actually went wrong. * Decimal values in organization pricing settings now save correctly. **February 13, 2026** ## Added * Videos and images you attach are now compressed automatically to fit under the 900KB carrier limit, keeping as much quality as possible. Common video formats are supported, including MP4, MOV, and clips recorded on an iPhone. ## Changed * The reporting page has clearer charts and shows your message the way it will appear on a recipient's phone. ## Fixed * Login failures now tell you what went wrong instead of showing a generic error. * Pricing you set for your organization keeps its exact decimal amount instead of being rounded. **February 4, 2026** ## Fixed * Link click tracking now records every click. Some clicks were previously missing from your reports. **February 3, 2026** ## Changed * Messages send faster and hold that speed on large projects. ## Fixed * Large data exports finish instead of timing out partway through. **February 2, 2026** ## Changed * Analyzing a contact list is now about ten times faster, so you can move from upload to sending much sooner. ## Fixed * The cell count shown for a contact list now matches the number of contacts you actually have. **February 1, 2026** ## Changed * Pages across the platform load faster, and message status updates appear sooner after a message goes out. **January 26, 2026** ## Added * You can now run surveys. Build up to 30 questions that advance automatically based on how each person replies, watch completion rates as responses come in, and export the results to CSV. **January 11, 2026** ## Added * You can now filter the project dashboard and the archive, which makes finding a specific project much faster when you run a lot of them. ## Changed * The homepage handles resellers and sub-organizations properly, so agencies managing several tiers of accounts can navigate between them without leaving the page. ## Fixed * On the chat page, the message window now sits in its proper position instead of dropping below the conversation list. * Selecting more than one contact list in the segment builder no longer crashes the page. **January 8, 2026** ## Added * A daily usage ledger now shows every billing entry, filterable by date range, so you can see exactly what you were charged for and when. ## Changed * Pages now show a preview of the layout while they load instead of a spinner, so you can tell what is coming. ## Fixed * Recurring charges now calculate and run on the correct schedule. Some monthly charges were running at the wrong time or for the wrong amount. **January 4, 2026** ## Added * The platform now meets WCAG 2.1 AA accessibility standards, with better keyboard navigation, screen reader support, skip navigation links, and higher contrast text. ## Changed * Dark mode now uses one consistent color set, so every screen looks the same rather than some pages reading lighter or darker than others. * The interface has been redesigned throughout with more consistent spacing, type, and color. * Pages load faster on first visit because the app now downloads roughly 90KB to 100KB less. **January 1, 2026** ## Changed * Uploading a contact list is now up to 2.5 times faster, and searching for a phone number is about ten times faster. A list of 100,000 or more contacts now processes in under two minutes instead of more than five. * Dashboard pages, including your brand and campaign lists, now load in a fraction of a second even when you have a lot of them. ## Fixed * Searching for and buying a phone number no longer fails partway through, and the messages you see when something does go wrong now explain the problem. **December 20, 2025** ## Added * **Contact list segmentation** builds new lists from how people engaged with a project. Pull out everyone who clicked a link, everyone who replied, or everyone who did neither, and message that group directly. * **Outbound webhooks** send you a notification the moment something happens: a project starts or finishes, a message changes status, or a contact list updates. Deliveries are retried and signed so you can confirm they came from us. ## Changed * Projects start faster and the platform stays responsive when you are sending heavily. **December 10, 2025** ## Added * **API documentation** is now published, with working examples in cURL, JavaScript, and Python, plus a guide to authenticating and a set of best practices. * **API keys** can be created and managed yourself, with per-key permissions so an integration only gets the access it needs. * **Merge tag mapping** matches your CSV columns to merge tags during upload and detects the common ones on its own, so a column named FirstName becomes first\_name without your help. * **Multiple contact lists** can be used in a single project, with duplicates removed automatically across every list you add. * **Template fallbacks** let you write `{first_name|Friend}` so a contact with a blank field still gets a natural message. The editor previews it with sample contact data. **December 4, 2025** ## Added * You can now send a test message to up to 10 phone numbers at once. Add or remove numbers with the plus and minus buttons, and see the delivery result for each one in your test history. **December 2, 2025** ## Added * Link tracking is here. See who clicked a link in your campaign, measure click-through rates, spot links being shared onward, and break clicks down by device, browser, and operating system. Every organization gets the shared domains vter.io and msg.vote, and you can add your own branded short domain. ## Fixed * Contact list selections now save with a project draft, so you can stop mid-setup and come back without rebuilding your audience. **November 29, 2025** ## Fixed * Editing a project now loads every field. Some fields came up blank and had to be re-entered. * Deleting a project works again. * The reporting page now opens for projects that are still sending, not just finished ones. * You now stay logged in until 48 hours of inactivity, or 30 days at the outside. Sessions were ending sooner than that. * Suppression lists can be attached to a project again. **November 19, 2025** ## Added * Campaign Verify now has its own page, separate from brands. Save a draft, submit it, confirm your PIN, and generate as many tokens as you need for 10DLC, toll-free, and short code messaging. You can also import tokens you already hold from another Campaign Verify account. ## Changed * Brand pages have been redesigned around brand registration and 10DLC campaigns alone, with clearer status and navigation. Political vetting now lives on the Campaign Verify page instead. **November 18, 2025** ## Added * **Two-factor authentication** is available using an authenticator app such as Google Authenticator or Authy. * **Session activity** on your profile page shows every active session, when it started, and where it signed in from. ## Changed * The billing balances page now loads in under a second instead of 13, and the dashboard and projects pages load 40% to 60% faster. ## Fixed * Closing and reopening your browser no longer signs you out. * You can be signed in on several devices at once, and manage all of those sessions from your profile. * You are no longer signed out every 15 minutes or whenever we release an update. * Devices you marked as trusted for two-factor stay trusted through updates. ## Security * Sessions now expire after 48 hours without activity. * An account locks automatically after 10 failed sign-in attempts, which blocks password guessing. **November 14, 2025** ## Added * You can now run the platform on your own domain, such as app.yourcompany.com. Verify the domain through your DNS provider for a one-time \$5.00 setup fee, and we handle the security certificate and worldwide delivery. * A branding page in Admin gives you the rest of the white-label controls: upload your logo and favicon, manage several domains at once, watch each one's setup progress, and pick the primary domain that the others redirect to. Setup usually takes 20 to 50 minutes end to end. **November 12, 2025** ## Changed * Large projects and high message volumes run more smoothly, and pages that used to time out while loading now finish. **November 11, 2025** ## Changed * The dashboard now opens almost instantly, and messages send about three times faster with more accurate live progress on big sends. ## Fixed * Campaigns of 100,000 or more messages no longer fail partway through. **November 7, 2025** ## Fixed * You can download a contact list again once its analysis finishes. **November 6, 2025** ## Changed * Message status updates now arrive on time during heavy sending, instead of lagging behind when volume spiked. **November 4, 2025** ## Changed * Project exports now include the delivery status and disposition of each individual message, so you can see exactly what happened to every send rather than just the totals. **November 3, 2025** ## Changed * The dashboard activity feed loads far faster, so recent messaging activity appears as soon as you open the page. **November 2, 2025** ## Changed * The recurring usage page now nests phone numbers under the campaign they belong to, and a single toggle turns auto-renew on or off for a campaign and every number attached to it. ## Fixed * Recurring charges now run on schedule. Some were not triggering at all. **November 1, 2025** ## Added * A status page now shows live platform health, uptime history, and any active incident, so you can check whether an issue is on our side before you call support. ## Changed * Navigation has been reorganized so the sections you use most are fewer clicks away. ## Fixed * Auto-recharge no longer gets stuck. Your wallet tops up whenever the balance falls below the threshold you set. * Inbound messages are now billed correctly, so your usage and charges match what you actually received. * Projects no longer show as incomplete after every message has been delivered. **October 31, 2025** ## Added * Compliance and policy pages are now published, covering messaging policies, legal disclosures, and the carrier-required guidelines your campaign has to follow. * A Help Center and FAQ cover setup, common questions, troubleshooting, and how to reach support. * A features page lays out what the platform does and what it costs. ## Changed * The onboarding guide now walks through the whole path end to end, from registration and campaign setup through sending, billing, and reporting. **October 30, 2025** ## Added * This changelog is now available inside the app, so you can see what changed without leaving your dashboard. * You can add your own description to a phone number, which makes a long list of numbers far easier to keep straight. **October 19, 2025** ## Added * Archived projects are now viewable, with the metrics they finished with. Filter them in or out of your project list, and a clear marker shows they cannot be edited. ## Changed * Billing keeps up during large bursts of messages instead of timing out. ## Fixed * Every charge now records a ledger entry. Some charges were being applied without one, which left gaps in your billing history. **October 18, 2025** ## Added * You can now use bold and italic text in message templates. ## Changed * A project of 3,600 or more messages now finishes in under two minutes instead of more than 13. ## Fixed * Every message is now billed exactly once. Sending at high volume could previously drop a charge. * Registering a brand charges once instead of twice. * Any column header from your CSV now works as a placeholder in a template, so you can write `{FirstName}`, `{Company}`, or `{Title}` and have it filled in per contact. * Delivery rate now excludes replies from the calculation, so the percentage reflects actual deliveries. **October 14, 2025** ## Changed * The billing ledger now attributes each cost to the project or resource that caused it, so you can see where your money went rather than a single running total. * Your wallet balance updates the instant a charge lands, rather than a few seconds later. **October 13, 2025** ## Changed * Pausing and resuming a project is now reliable. Everything already sent is preserved and the project picks up exactly where it stopped, with no duplicate messages. * A campaign of 10,000 or more messages now sends in under an hour instead of more than four. * Projects start in under a second instead of 10 to 15, because messages are prepared while you finish editing. **October 9, 2025** ## Added * **Auto-recharge** keeps your account funded. When your balance drops below the threshold you set, we charge your payment method automatically so sending never stops mid-campaign. * **Automatic renewal** for phone numbers and campaigns. Numbers are prorated by the days remaining, campaigns renew on their anniversary date. * **Auto-completion and archiving** marks a project complete once every message has sent, then archives it 14 days later to keep your workspace clear. * **Real-time balance** now includes today's usage before it has been billed, so the number you see is what you can actually spend. * **Approvals** are now a single toggle, and projects that need approval are labeled as such in the workflow. ## Changed * Every project now requires a test message before the full send, and editing a project returns it to testing so nothing goes out by accident. * Creating a project is about ten times faster, and a campaign with thousands of contacts opens immediately. **January 20, 2025** ## Added * Custom domains now carry your own branding across every public page, including login, registration, and legal documents. Your users see your logo, organization name, and contact details rather than ours. # The Campaign Registry (10DLC) Source: https://docs.politicalcomms.com/compliance/campaign-registry Centralized registration system for verified business text messaging in the United States. Brand setup, campaign creation, costs, and timelines. Centralized registration system for verified business text messaging in the United States. ## What is The Campaign Registry (TCR)? The Campaign Registry (TCR) is the central hub where Campaign Service Providers (CSPs) register brands and campaigns for the 10DLC messaging ecosystem. 10DLC stands for "10-Digit Long Code" - standard local phone numbers (like 347-555-1234) used for Application-to-Person (A2P) text messaging. Think of TCR as the gatekeeper that verifies organizations are legitimate before allowing them to send high-volume messages. This protects consumers from spam and scams while giving legitimate senders a clear path to reliable messaging. ## Why 10DLC registration exists > [card] Consumer Protection > > Reduces spam, scams, and fraud by verifying sender identity before messages are sent. > [card] Transparency > > Both the "who" (brand) and "what" (campaign content) are known upfront and traceable. > [card] Deliverability > > Sanctioned messaging route with carriers ensures messages reach recipients reliably. ## 10DLC registration process (political organizations) > [!NOTE] > > **Note for consulting firms:** Each candidate or campaign you manage requires its own brand registration. Individual candidates register one brand for themselves. Consulting firms managing multiple candidates will complete this process for each client (brand), with each brand able to have multiple campaigns underneath it. **1. Setup Brand (\$4.50 per brand)** Register each candidate/campaign as a separate brand with The Campaign Registry. Provide the candidate's legal name, EIN/Tax ID, physical address, and active website with privacy policy and terms. **Brand registration is instant.** Consulting firms will register one brand per client. Registering many brands at once? Use **Import CSV** on the 10DLC page: download the template, fill one row per brand (legal name, EIN, contact, address, website), match the columns and pick the entity type and use case on the next screen, and every row is checked and priced before any brand is created. **2. Vet Brand with Campaign Verify (\$95 per brand)** Each brand (candidate/campaign) must get verified through Campaign Verify. You can either bring an existing Campaign Verify token or submit the verification request directly inside Political Comms. Our integration handles the FEC or state election filing record submission for you. Verification typically completes in \~2 hours on business days. Each token is valid for **1 year** and is specific to that candidate. **3. Create Campaign ($30 for 3 months, then $10/month per campaign)** Register campaigns under each brand (e.g., "GOTV 2024", "Fundraising Outreach"). A single brand can have multiple campaigns. Include sample message scripts and campaign description. Campaigns typically approve in 2 business days (faster if expedited). **4. Add Phone Number** Provision phone numbers and assign them to your approved campaign. Phone number costs vary based on your pricing tier. Numbers are ready to use immediately once campaign is approved. **5. Start Sending** Once your campaign is approved and phone numbers are assigned, you can start sending messages immediately. **Total setup time: typically 2–3 business days from start to sending.** ## Timeline & costs > [card] Registration Timeline > > * **Brand Registration:** Instant > * **Campaign Verify:** \~2 hours on business days > * **Campaign Registration:** 2 business days (faster if expedited) > * **Total Estimate:** 2–3 business days > [card] Registration Costs (Per Brand) > > **Initial Setup:** > > * Brand Registration (one-time): **\$4.50** > * Campaign Verify Token (one-time, valid 3+ years): **\$95.00** > * First Campaign (3 months prepaid): **\$30.00** > * **Total Per Brand: \$129.50** > > **Ongoing:** > > * Campaigns: \$10/month per campaign (after initial 3 months) > * Phone numbers: based on your pricing tier > * Message sends: per-message pricing (SMS/MMS) > [!TIP] > > **For consulting firms:** Managing 5 candidates = 5 brands × $129.50 = **$647.50 initial setup\*\*. Each brand can have multiple campaigns for different purposes (GOTV, fundraising, etc.). > [!NOTE] > > **10DLC Registration Pricing (per brand)** > > | Item | Cost | Notes | > | - | - | - | > | Brand Registration | **\$4.50** | One-time, instant | > | Campaign Verify Token | **\$95.00** | One-time, valid for the current two-year election cycle | > | First Campaign | **\$30.00** | Covers the first 3 months | > | Ongoing Campaign Fee | **\$10.00 / month** | Per campaign, after initial 3 months | > | **Total Initial Setup** | **\$129.50** | Per brand | > > Consulting firms managing multiple candidates multiply these costs by the number of brands (one brand per candidate). Phone numbers are billed separately based on your pricing tier. > [!NOTE] > > **Email Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Email sending | **\$3.00 / 1,000 emails** | \$0.003 per recipient. Lower with volume. | > | Full-service email sending | **\$0.01 per email** | Our team builds and sends every campaign. Lower with volume. No monthly fee. | > | Full-service email setup | **\$1,000 one-time** | Domain authentication, DNS records, warm-up, and list import. | > | Sending domains | **Free** | Unlimited domains and From addresses. | > | Hosted unsubscribe and preferences | **Free** | Included with every send. | > | Dedicated IP pool add-on | **\$35.00 / month per sending domain** | Optional dedicated managed sending IP pool for one sending domain. Warm-up usually takes up to about six weeks, depending on your volume. | > | AI email draft (Lincoln) | **\$3.00 per draft** | AI-drafted email template from a prompt, images and brand colors. | > > Test sends are real sends and are billed at the same per-recipient rate. Email charges appear in the ledger under the Email family and roll up through the organization hierarchy like texting. > [!NOTE] > > **Domain Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Domain registration | **Registrar's price** | One year. Prices vary by ending, shown before you buy. Non-refundable once registered; refunded if registration never happens. | > | Domain hosting fee | **\$6.00 / year** | Flat. Covers the DNS records we write and keep current for the domain. | > | App or link-tracking host setup | **Normal setup fee** | One per host. | > > Charged from your wallet at purchase and renewed yearly, 30 days before the domain expires. Dashboard only. ## Benefits of 10DLC registration > [card] Sanctioned Messaging Route > > Carriers recognize you as a legitimate sender. > [card] Higher Deliverability > > Avoid spam filters and carrier blocks. > [card] Local Phone Numbers > > Use familiar local area codes, not short codes. > [card] Build Trust > > Verified identity prevents impersonation. ## Security > [!NOTE] > > **The Campaign Registry is certified to ISO 27001:2022**, an international standard for information security management. Organization data submitted during brand and campaign registration is handled under that certification. ## Official resources * [The Campaign Registry Website](https://www.campaignregistry.com/) * [10DLC Ecosystem Overview](https://www.campaignregistry.com/10dlc/) # Campaign Verify Source: https://docs.politicalcomms.com/compliance/campaign-verify Nonpartisan verification service for U.S. political campaigns, PACs, and committees. Eligibility, process, costs, and validity. Nonpartisan verification service for U.S. political campaigns, PACs, and committees. ## What is Campaign Verify? Campaign Verify is a nonpartisan, 501(c)(3) nonprofit founded in 2020 to verify the identity of political campaigns and prevent impersonation in text messaging. They issue Authorization Tokens that prove to carriers, The Campaign Registry, and messaging platforms that your campaign is legitimate. > **Mission:** "Provide a public service on a non-partisan basis to verify the integrity and authenticity of text message and other communications related to political campaigns and elections in order to educate the public, ensure public confidence in American elections, and protect political and civic rights." ## Why Campaign Verify exists Election security is a major national concern. Foreign influences and domestic bad actors can exploit text messaging's high open rates to spread disinformation and impersonate campaigns. Campaign Verify provides a critical checkpoint to ensure message senders are who they claim to be. Campaign Verify was founded by a bipartisan board with expertise in wireless messaging and political campaigns from both sides of the aisle. They work with the FCC, FBI Foreign Influence Task Force, and telecommunications industry to protect election integrity. > [!NOTE] > > Election security is neither a Republican nor Democratic issue - it's about protecting democracy itself. ## Who is eligible? > [card] Eligible Organizations > > * **Candidates:** Federal, state, local, tribal campaigns > * **Political Parties:** National, state, and local party committees > * **PACs:** Political Action Committees > * **527 Organizations:** Tax-exempt political organizations > * **Any committee** registered with FEC or state/local/tribal election authority > [card] What You Need > > * Publicly accessible filing record (FEC or state election website) > * Registration with election authority > * \$95 verification fee (credit card or check) > * Committee name and registration details > > **Note:** If your filing isn't online yet, verification may take longer while Campaign Verify confirms your registration. ## How Campaign Verify works **1. Find Your Filing Record Online** Locate your committee's public filing on the FEC website (federal) or your state/local election authority website. You'll need the direct URL to this record. **2. Submit Verification Request** You have two options: * **Submit through Political Comms (recommended).** During brand setup, choose "Request a new Campaign Verify token." Our integration submits your verification request, filing record URL, committee details, contact info, and the \$95 fee directly to Campaign Verify on your behalf. No separate account needed. * **Submit through CampaignVerify.org directly.** Create an account at [CampaignVerify.org](https://campaignverify.org), submit a verification request with your filing record URL, committee details, and contact information, and pay the \$95 fee. When approved, bring the token back to Political Comms: on the 10DLC page open **Create Brand** and choose **From Campaign Verify token** to create a new brand from it (you review and edit the brand before anything is registered, and the vetting is applied as soon as the registrar finishes creating the brand, usually within a minute or two), or apply it to a brand you already registered from the 10DLC page or the brand's page. The brand does not have to be identity-verified first. **3. Get Your Secure PIN Code** Campaign Verify reviews your filing and confirms your identity (typically 3–14 days depending on filing availability). Once approved, they issue you a secure PIN code. **4. Generate Authorization Token** Use your PIN to generate an Authorization Token in the Campaign Verify portal. This token is what you provide to your messaging platform for 10DLC registration. **5. Reach Your Voters!** With your Campaign Verify token, you can complete 10DLC registration and start sending verified messages. Your authorization is valid for the current two-year election cycle (see [Cost & Validity](#timeline--cost) for the dates); Political Comms shows a "Valid Until" date on your Campaign Verify list and emails you about 30 days before it expires. ## Benefits of Campaign Verify authorization > [accordion] Prevent Impersonation > > Stop bad actors from pretending to be your campaign and spreading misinformation. > [accordion] Increase Deliverability > > Verified campaigns have better message delivery rates with mobile carriers. > [accordion] Build Trust > > Voters trust verified messages more, increasing engagement and response rates. > [accordion] Protect Democracy > > Contribute to election security and reduce foreign/domestic interference in political messaging. ## Timeline & cost > [card] Verification Timeline > > * **If filing is online:** 3–5 business days > > * **If filing is delayed:** 7–14 business days > > * **Busy election periods:** May take longer (start early!) > > > [!TIP] > > > > Start your Campaign Verify request as soon as you file with the election authority. > [card] Cost & Validity > > * **Verification Fee:** \$95 (one-time) > * **Valid For:** a two-year election cycle. Verifications, tokens and sender email addresses all follow the same cycle, regardless of when in the cycle you verified: > * Requests submitted November 15, 2024 to November 14, 2026 are valid until January 31, 2027. > * Requests submitted November 15, 2026 to November 14, 2028 are valid until January 31, 2029. > * **Deadline:** Campaign Verify's cutoff is 11:59 PM Central Time on the expiry date. > * **Renewal:** a new verification request each cycle, with another \$95 fee. Political Comms emails one reminder per organization about 30 days before expiry, listing every campaign. Expired tokens are refused for new brand and toll-free registrations, and a new campaign cannot be registered on a brand with expired vetting. > * **Brand vetting expires with the token:** a political brand vetted with Campaign Verify must be re-vetted with a new token from a verification in the new cycle before the expiry (January 31, 2027 at 11:59 PM Central Time for the current cycle), or the brand and its campaigns deactivate. New-cycle verifications can be submitted starting November 15, 2026. > * **How to renew:** from November 15 of a cycle year, the Campaign Verify page shows a Renew button on each verified request. It opens a prefilled request with the same details and the election date set to the next general election; you can edit it and choose where the PIN goes. After the PIN is delivered and the token is generated, use Re-vet to apply the new token to the brand. > * **Late in a cycle:** in the last 30 days of a cycle, Political Comms shows a notice that a request submitted now expires soon. Unless you need verification right away, wait for the new cycle to begin on November 15 so the request covers the full two years. > * **Payment Methods:** Credit card or check > * **Reusable:** One token works for all your messaging platforms ## Email sending domains A verified Campaign Verify identity request also lets you submit a sender email address to Google's Gmail Verified Sender Program, for reliable Gmail inbox delivery on your sending domain. See [Gmail Verified Sender Program](/help/email/gmail-verified-sender-program) for eligibility, the pre-submission checks, and the exact Campaign Verify portal steps. ## Official resources * [Campaign Verify Website](https://campaignverify.org/) * [How Campaign Verify Works](https://campaignverify.org/how-it-works) * [Federal Election Commission (FEC)](https://www.fec.gov/) # Compliance Checklist Source: https://docs.politicalcomms.com/compliance/checklist Run through this 10-item checklist for every campaign to make sure you stay compliant with all regulations. Follow this checklist to ensure your campaigns stay compliant with all regulations: > [card] Consent & sender identification > > * [ ] Obtain consent before sending (when possible) > * [ ] Provide clear sender identification > * [ ] Include opt-out instructions (Reply STOP) > * [ ] Honor opt-outs immediately (automated) > * [ ] Send only between 8 AM – 10 PM > [card] Registration & technology > > * [ ] Complete 10DLC registration > * [ ] Obtain Campaign Verify token (\$95) > * [ ] Avoid random/sequential number generation (autodialer restrictions) > * [ ] Document consent and opt-outs > * [ ] Follow state-specific regulations ## Going deeper > [card] [TCPA](/compliance/tcpa) > > Federal autodialer restrictions, consent rules, opt-outs, calling hours, and penalties. > [card] [FCC Political Rules](/compliance/fcc-political) > > How the FCC applies TCPA to political text messaging campaigns. > [card] [CTIA Guidelines](/compliance/ctia) > > Wireless industry best practices that exceed legal minimums. > [card] [The Campaign Registry](/compliance/campaign-registry) > > 10DLC registration for brands and campaigns. # CTIA Messaging Principles & Best Practices Source: https://docs.politicalcomms.com/compliance/ctia Wireless industry standards for protecting consumers and maintaining message deliverability - opt-in consent, informed consent, opt-out handling. Wireless industry standards for protecting consumers and maintaining message deliverability. ## What is CTIA? CTIA (the wireless industry association) established messaging principles that go beyond legal requirements to protect consumers from spam and unwanted messages. Mobile carriers use these principles to filter and block messages that don't follow best practices. > [!WARNING] > > **Why this matters:** Even if your messages are legally compliant, carriers may filter them if you don't follow CTIA guidelines. Following these principles ensures your messages reach recipients and maintains your sender reputation. ## Three core principles ### 1. Obtain opt-in consent Get consumer permission before sending messages, even when not legally required. Consumers should actively choose to receive your messages. **Valid consent methods include:** * Website form with checkbox (not pre-checked) * Mobile webpage button click * Keyword opt-in (e.g., "Text JOIN to 12345") * In-person sign-up at events * QR code scan with explicit opt-in * Phone opt-in via IVR (interactive voice response) ### 2. Ensure informed consent When collecting consent, provide clear disclosures (called "call-to-action") about what consumers are signing up for. **Required disclosures include:** * **Program description:** What types of messages will they receive? * **Sender identity:** Who is sending the messages (campaign name)? * **Message frequency:** How often will they receive messages? * **Opt-out instructions:** How to stop messages (Reply STOP) * **Terms & Privacy:** Link to terms of service and privacy policy ```text Example call-to-action theme={null} By providing your phone number, you consent to receive campaign updates from Smith for Senate. Message frequency varies. Reply STOP to opt out. Msg & data rates may apply. View Terms & Privacy at smith2024.com ``` ### 3. Honor opt-out requests Consumers must be able to opt out at any time, and you must honor requests immediately. **Opt-out requirements:** * **Support STOP keywords:** STOP, UNSUBSCRIBE, CANCEL, QUIT, END * **Multiple methods:** Reply to text, phone call, email, web form * **Immediate processing:** Remove from lists within seconds (automated) * **No re-subscription:** Stay opted out unless they explicitly opt back in * **Confirmation message:** Send one final message confirming opt-out ## What NOT to do (spam triggers) > [!WARNING] > > **Don't share phone lists.** Consent to one organization doesn't transfer to another. No selling, leasing, or sharing recipient lists without explicit permission. > > **Don't pre-check opt-in boxes.** Consumers must actively choose to opt in. Pre-checked boxes or hidden opt-ins don't count as consent. > > **Don't bury disclosures.** Call-to-action must be clear and conspicuous, not hidden in fine print or long terms of service. > > **Don't use deceptive language.** Be honest about who you are and why you're texting. No misleading subject lines or sender names. > > **Don't ignore opt-outs.** Continuing to text after STOP is received is illegal and damages your reputation with carriers. ## How carriers filter spam Mobile carriers and messaging service providers use spam filters to protect consumers. Messages get flagged if they: * Generate high complaint rates (users marking as spam) * Have high opt-out rates or ignored STOP requests * Come from unregistered or suspicious phone numbers * Contain spam-like content (excessive links, ALL CAPS, deceptive language) * Send during restricted hours (before 8 AM or after 10 PM) * Show patterns of automated dialing without human interaction **Following CTIA guidelines prevents filtering** and ensures your messages are delivered consistently. ## Official resources * [CTIA Messaging Principles & Best Practices](https://www.ctia.org/the-wireless-industry/industry-commitments/messaging-principles-and-best-practices) * [CTIA Political Text Messaging Guide](https://www.ctia.org/homepage/political-text-messaging) # FCC Political Text Messaging Rules Source: https://docs.politicalcomms.com/compliance/fcc-political How the FCC applies TCPA specifically to political text messaging campaigns, including the Facebook v. Duguid autodialer ruling. FCC regulations for political text messaging under the TCPA. ## Overview During election seasons, there is typically an increase in texts from political campaigns. While campaign texts are exempt from National Do Not Call Registry requirements, the Telephone Consumer Protection Act (TCPA) contains specific rules for text messaging. The key distinction is whether a system qualifies as an "autodialer" under the TCPA. Systems that use random or sequential number generation are subject to strict consent requirements, while systems that send to specific, targeted contact lists are not classified as autodialers. ## What is an "autodialer"? The Supreme Court's ruling in *Facebook, Inc. v. Duguid* (2021) clarified the definition of an "automatic telephone dialing system" (autodialer) under the TCPA. > [!NOTE] > > **Legal Definition.** To qualify as an autodialer under the TCPA, a device must have the capacity **either to store a telephone number using a random or sequential number generator, or to produce a telephone number using a random or sequential number generator**. This definition is important because **only systems that use random or sequential number generation are subject to the strict "autodialer" consent requirements**. Systems that send to specific, targeted contact lists (without random/sequential generation) do not meet this definition. ## Opt-out requirements (all political texts) Regardless of whether a system qualifies as an autodialer, **all political text messaging campaigns must honor opt-out requests**. Recipients can revoke consent at any time and in any reasonable manner, such as: * Replying "STOP" to a text message * Requesting removal through any other reasonable method > [!TIP] > > **Best Practice:** Opt-out requests should be processed immediately and automatically. Maintaining a suppression list ensures opted-out contacts never receive future messages. ## When do TCPA autodialer rules apply? The TCPA's strict consent requirements for text messages apply specifically to systems that: * Use random or sequential number generation to store or produce phone numbers * Qualify as an "autodialer" under the *Facebook v. Duguid* definition **Systems that send to specific, targeted contact lists (without random/sequential generation) are not classified as autodialers and are not subject to these strict consent requirements.** That said, all campaigns should follow best practices: honor opt-outs immediately, send during reasonable hours (8 AM – 9 PM), clearly identify the sender, and maintain good deliverability practices. ## Official resources * [FCC Political Campaign Text Messaging Rules](https://www.fcc.gov/political-campaign-robocalls-robotexts) * [Facebook v. Duguid, 592 U.S. \_\_\_ (2021) - Autodialer Definition](https://supreme.justia.com/cases/federal/us/592/19-511/) * [FCC Consumer Guide - Text Messaging](https://www.fcc.gov/consumers/guides/stop-unwanted-robocalls-and-texts) # Compliance Glossary Source: https://docs.politicalcomms.com/compliance/glossary Definitions for 10DLC, A2P, ATDS, CSP, TCPA, TCR, 527 organizations, and other terms you'll encounter in political-text compliance. ## 10DLC 10-Digit Long Code. Standard local phone numbers used for Application-to-Person (A2P) text messaging. ## A2P Application-to-Person messaging. High-volume texting from software platforms (not individual phones). ## ATDS Automatic Telephone Dialing System. Equipment that dials numbers automatically without human interaction (restricted by TCPA). ## CSP Campaign Service Provider. Messaging platforms that register brands with TCR. ## Scheduled Messaging Sending messages to specific, targeted phone lists at a scheduled time. Does not use random or sequential number generation, so it does not meet the TCPA definition of an autodialer per *Facebook v. Duguid* (2021). ## TCR The Campaign Registry. Central hub for registering brands and campaigns in the 10DLC ecosystem. ## TCPA Telephone Consumer Protection Act (47 U.S.C. § 227). Federal law restricting automated calls and texts. ## 527 Organization Tax-exempt political organization under Section 527 of the IRS code (campaigns, PACs, parties). # Compliance & Regulatory Guide Source: https://docs.politicalcomms.com/compliance/overview Stay compliant with federal regulations and industry best practices for political text messaging - TCPA, FCC, CTIA, 10DLC, and Campaign Verify. > [!NOTE] > > **Legal Disclaimer.** The information provided in this guide is for educational purposes only and does not constitute legal advice. Compliance requirements may vary based on your specific circumstances, jurisdiction, and the nature of your communications. For specific guidance on regulatory compliance, consult with a qualified attorney familiar with telecommunications law and political campaign regulations. > [!WARNING] > > **Why compliance matters.** Compliance isn't just about avoiding penalties - it's about respecting voters, maintaining deliverability, and protecting your campaign's reputation. Following these regulations ensures your messages reach supporters while building trust in the political messaging ecosystem. Non-compliance can result in fines up to **\$1,500 per message**, carrier filtering, and damage to your organization's credibility. ## The five pillars of political-text compliance > [card] [TCPA](/compliance/tcpa) > > The federal Telephone Consumer Protection Act - autodialer restrictions, consent rules, opt-outs, calling hours, and penalties up to \$1,500/violation. > [card] [FCC Political Rules](/compliance/fcc-political) > > How the FCC applies TCPA specifically to political text messaging campaigns - including the *Facebook v. Duguid* autodialer ruling. > [card] [CTIA Guidelines](/compliance/ctia) > > Wireless industry best practices that *exceed* the legal minimum - opt-in consent, informed consent, opt-out handling, and what triggers carrier filtering. > [card] [The Campaign Registry (10DLC)](/compliance/campaign-registry) > > Registration for the 10DLC ecosystem - brand setup, campaign creation, costs, and timelines. > [card] [Campaign Verify](/compliance/campaign-verify) > > Nonpartisan verification for U.S. political campaigns, PACs, and party committees. Required for 10DLC registration as a political brand. ## Quick references > [card] [Compliance Checklist](/compliance/checklist) > > Run through this list for every new campaign to make sure nothing slips. > [card] [Compliance Glossary](/compliance/glossary) > > Definitions of 10DLC, A2P, ATDS, TCPA, TCR, and other terms you'll encounter. # Telephone Consumer Protection Act (TCPA) Source: https://docs.politicalcomms.com/compliance/tcpa Federal law protecting consumers from unwanted automated calls and text messages. Key requirements, political exemptions, and penalties up to $1,500 per message. Federal law protecting consumers from unwanted automated calls and text messages. ## What is TCPA? The TCPA (47 U.S.C. § 227) restricts the use of automated telephone equipment, including auto-dialers and prerecorded messages. Enacted in 1991 and amended multiple times, it protects consumer privacy by requiring consent for certain types of communications and establishing rules for telemarketing and robocalls. > [!NOTE] > > **Understanding the "Autodialer" Definition.** Under the Supreme Court's ruling in *Facebook v. Duguid* (2021), an "automatic telephone dialing system" (ATDS or autodialer) must have the capacity to use a random or sequential number generator to store or produce phone numbers. Systems that send messages to specific, targeted phone lists - without using random or sequential generation - do not meet this legal definition. Consult with legal counsel to understand how TCPA requirements apply to your specific messaging approach. ## Key TCPA requirements > [card] No Automated Dialers > > Cannot use equipment that automatically dials from a random or sequential number generator without human intervention. > [card] Consent Required > > Prior express written consent required for commercial messages. Political messages have exemptions but best practice is to obtain consent. > [card] Calling Hours > > Cannot call before 8 AM or after 9 PM (local time). Most carriers enforce 8 AM – 10 PM for texting. > [card] Honor Opt-Outs > > Must provide clear opt-out mechanism and honor requests immediately. Once opted out, cannot contact again without new consent. > [card] Identify Sender > > Messages must clearly identify the sender. Don't misrepresent who you are or hide behind vague identities. > [card] Emergency Lines Exempt > > Cannot call emergency lines, hospital rooms, or services where recipient is charged for incoming calls. ## Political campaign exemptions Political calls and texts may have certain exemptions under TCPA, but requirements can vary based on the technology used and specific circumstances. Best practices for campaigns include: * Avoid using random or sequential number generation (autodialer restrictions) * Honor opt-out requests immediately and automatically * Respect calling time restrictions (8 AM – 9 PM local time) * Clearly identify your campaign in all messages * Follow state laws (which may be more restrictive than federal rules) * Consult legal counsel for guidance on your specific messaging approach ## Penalties for violations > [!WARNING] > > **\$500 per violation** - Standard penalty for each illegal call or text message. > > **\$1,500 per violation** - For willful or knowing violations (up to 3× damages). > > **Private right of action** - Individuals can sue directly in state courts. > > **State attorney general enforcement** - State AGs can bring civil actions on behalf of residents. ## TCPA best practices > [accordion] Obtain Consent When Possible > > Even if not legally required, getting opt-in consent improves engagement and reduces complaints. > [accordion] Document Everything > > Keep records of consent, opt-outs, and campaign procedures. Audit trails protect you in disputes. > [accordion] Avoid Autodialer Technology > > Do not use random or sequential number generation. Send to specific, targeted phone lists only. > [accordion] Process Opt-Outs Immediately > > Support STOP keywords and honor requests within seconds (automated on our platform). ## Official resources * [FCC TCPA Overview](https://www.fcc.gov/consumers/guides/stop-unwanted-robocalls-and-texts) * [47 U.S.C. § 227 (Full Text)](https://www.govinfo.gov/content/pkg/USCODE-2022-title47/pdf/USCODE-2022-title47-chap5-subchapII-partI-sec227.pdf) * [Facebook v. Duguid, 592 U.S. \_\_\_ (2021) - Autodialer Definition](https://supreme.justia.com/cases/federal/us/592/19-511/) # Admin tools: API, Notifications, Audit Logs Source: https://docs.politicalcomms.com/help/admin-tools Create and revoke API keys, set up webhook endpoints and review their deliveries, choose who gets alert emails, and read your organization's activity log. Three pages under **Admin** cover the developer and oversight side of your organization: **API** for keys and webhooks, **Notifications** for alert emails, and **Audit Logs** for a running record of what happened. This page walks through each one. ## Who sees Admin The **Admin** section of the sidebar shows only the pages your role allows. Each page below has its own permission, so two people on the same team can see different items. | Page | Role permission that shows it | | - | - | | **Admin > API** | **Manage API keys** for the API keys tab; **Manage webhooks** for the Webhooks and Deliveries tabs | | **Admin > Notifications** | **Manage notifications** | | **Admin > Audit Logs** | **View audit logs** | If you hold only one of the API permissions, the API page shows only the matching tabs. If you cannot see a page you need, ask an organization owner to adjust your role. See [Organizations and memberships](/help/organizations-and-memberships). ## API keys Open **Admin > API** and stay on the **API keys** tab. A summary at the top shows your total keys, how many are active, and total requests. You can search keys by name and filter by **Active** or **Revoked**. ### Create a key 1. Choose to create a new key. 2. Enter a **Key Name**, such as "Production API Key", and an optional description of what the key is for. 3. Pick at least one permission: * **Read** lists and views resources. * **Write** creates and updates resources. * **Delete** deletes resources. 4. Create the key. The full key appears once, with a **Copy** button and a sample request. Save the key somewhere secure before you press **Done**. We cannot show it again. Afterward the table shows only the key prefix, so use the prefix to tell keys apart. New keys are limited to 100 requests per hour. Send the key in the `X-API-Key` header; see the [API reference introduction](/api-reference/introduction) for everything you can call. ### Review, edit, and revoke * Open a key to see its prefix, status, rate limit, created and last used dates, permissions, usage statistics (total requests, success rate, rate-limited requests, average response time), and its last ten requests. * Edit a key to change its name or description. * **Revoke** a key to block every request that uses it, immediately. This cannot be undone. Create a new key to replace it, then update the system that used the old one. To rotate a key, create the new one first, switch your integration over, then revoke the old one so nothing breaks in between. ## Webhook endpoints Webhooks send events to your own system as they happen. Open the **Webhooks** tab on **Admin > API**. The top of the tab shows your endpoint count and, for the last 24 hours, deliveries, success rate, and failures. ### Add an endpoint 1. Choose to add an endpoint. 2. Enter an **Endpoint Name** (for example "Production") and the **Webhook URL** that will receive events. 3. Select the events you want. The list covers message sent, delivered, failed and replied; link clicked; email delivered, bounced, complained, unsubscribed and clicked; and contact list analyzed. 4. Leave **Enabled** on and save. ### The signing secret When the endpoint is created, a **Webhook Secret** appears once. Save it now, store it in your environment variables, never commit it to version control, and use it to verify each event's signature. The [signature validation guide](/api-reference/webhooks/signature-validation) shows how. To replace a secret, choose **Rotate Secret** on the endpoint. The old secret stops working immediately, so update your receiver at the same moment. ### Test, edit, and delete * **Test** sends a sample event so you can confirm your receiver responds. * **Edit** changes the name, URL, events, or enabled setting. * **Delete** removes the endpoint and all of its delivery history. This cannot be undone. ### Endpoints that keep failing If an endpoint fails repeatedly, we switch it off and mark it **Disabled after repeated failures**, with the date the failures began. Fix your URL, then choose **Re-enable**. Events that occurred while it was off are not resent. A successful test also clears the failure marker. ### Deliveries The **Deliveries** tab lists every event we tried to send, with its event type, status (pending, delivered, or failed), time, HTTP status, and number of attempts. Filter by event type or status. Open a delivery to see the URL, the payload we sent, and the response we got back. For a failed delivery, choose **Retry** to send it again. ## Notifications **Admin > Notifications** controls which alert emails your organization receives. Account sign-in and registration emails are not affected by these settings. In-app notifications, shown by the bell icon, continue independently of the email choices here. 1. Under **Recipients**, add up to 10 email addresses. 2. Under **Events**, switch on each address for each event it should receive. Events with no recipients added show a prompt to add one first. 3. Choose **Save changes**. **Send test email** confirms your recipients can receive mail. Events are grouped as follows: | Group | Events | | - | - | | 10DLC | Campaign provisioned; campaign rejected | | Campaign Verify | PIN sent | | Projects | Project approved; project report delivered | | Billing | Payment failed; low wallet balance; auto-recharge running often; renewal payment failed; renewal grace expiring; campaign deactivated for nonpayment | Some billing events always go to organization owners, whatever you choose here. Two events have extra settings: * **Project report delivered** sends automatically after a project finishes sending. Select up to three dispatch times of 1, 3, 6, 12, or 24 hours after the send completes. With none selected, no automatic report emails go out. * **Low wallet balance** fires when your balance drops below a dollar amount you set. Leave it blank to turn the alert off. ## Audit Logs **Admin > Audit Logs** opens the **Activity Logs** page, a newest-first feed of what has happened in your organization. Each entry has a description, how long ago it happened, and the organization it belongs to. The feed records these kinds of activity: * Project created * 10DLC campaign registered * Brand registered * Contact list uploaded * Organization created * User created It shows 50 entries at a time; choose **Load More** to go further back. The page has no filters or export, so for a spreadsheet of your sending data, use [Data exports](/help/data-exports). ## Related * [API reference](/api-reference/introduction) * [Technical support](/help/technical-support) * [Platform features](/help/platform-features) # Messaging Best Practices Source: https://docs.politicalcomms.com/help/best-practices How to write effective opening messages, when to send, opt-out handling, response rate optimization, and what to avoid. ## What makes an effective opening message? Keep it short and conversational. Start with a clear identification of who you are, state your purpose briefly, and include a simple call-to-action or yes/no question. **Example:** `"Hi {{firstName}}, this is Jamie with the Smith Campaign. Can we count on your support on Election Day? Reply YES or NO."` Avoid long paragraphs or multiple questions in the first message. ## When is the best time to send messages? Messages can only be sent during your project's sending window: 8 AM to 10 PM in the time zone of most of your recipients, or 8 AM Eastern to 10 PM Pacific when no time zone holds a majority. Best engagement times are typically 10 AM to 12 PM and 5 PM to 8 PM on weekdays. Avoid sending during major events, holidays, or late evenings. Test different times with your audience to find what works best for your specific campaigns. ## How do I handle opt-outs and maintain compliance? The platform automatically processes STOP, UNSUBSCRIBE, CANCEL, and similar keywords to immediately opt out contacts. Once opted out, contacts cannot receive future messages from your organization. Maintain separate opt-out lists per brand and a global opt-out list. Always honor opt-outs within seconds of receiving them, this is both legally required and enforced by our system. ## How can I improve response rates? Personalize messages with merge fields, keep messages conversational and brief, ask simple questions, respond quickly to replies, send messages at optimal times, segment your audience for targeted messaging, use MMS for higher engagement, and always provide value in your communications. P2P texting typically achieves 90%+ open rates and 40 to 50% response rates when done well. ## What should I avoid in my messages? Never use deceptive language or misrepresent your identity. Avoid ALL CAPS (looks like spam), excessive punctuation (`!!!`), too many links, or promotional language without proper consent. Don't share phone numbers between organizations without permission. Always include opt-out instructions. Never message purchased lists without opt-in, this violates TCPA and will damage deliverability. ## Why does my video show as a file instead of a preview on iPhones? Starting with iOS 27 (released September 2026), Messages shows video and GIF attachments from a number the recipient has not saved or replied to as a file icon with a filename, instead of an inline preview. Still images are not affected. The video is delivered intact and plays when tapped, and the moment the recipient replies in the thread or saves your number, every video already in the thread switches to a normal preview. This is a display rule on the phone. We tested it directly: the same video file rendered from a saved contact and showed as a file from an unknown one, and changing the codec, container, file size, or caption made no difference. Nothing in how the message is encoded or sent changes the outcome. The name on the file icon is ours to set, and we set it. Every video and GIF you send by text is delivered as `Tap-To-Watch.mp4` or `Tap-To-Watch.gif`, so the icon reads as a call to action instead of a generated name like `m8512.mp4`. This applies to files already in your media library as well as new uploads; nothing to change on your side. To use your own name instead (a candidate or committee name, for example), open the video or GIF in your media library and set **Attachment name** from its preview; every new upload starts as `Tap-To-Watch`. Names are 1 to 16 letters, numbers, hyphens or underscores; the extension is added for you, and a change applies to the next send. What works: * **Open cold conversations with text or a still image**, and ask a question that invites a reply. Once a contact has replied, video previews render for them. * **Send video to people who have already replied.** A Recent Repliers dynamic list keeps that audience current without any manual work. * **Lead with the thumbnail.** If the video matters on a first contact, send its key frame as an image with the video, or attach the image and link to the video. Android phones are not affected. # Billing & Account Balance Source: https://docs.politicalcomms.com/help/billing How balance-based billing works, auto-recharge, organization hierarchy, 10DLC costs, and refund policy. ## How does billing work? Billing is balance-based with instant updates (under 100ms). You add funds to your account balance, and we deduct costs as messages are sent. Pricing varies by message type: SMS (single segment), MMS (with media), carrier lookup (phone validation), and 10DLC fees. All charges roll up through your organization hierarchy automatically. Text messages are charged only on successful delivery; email is charged per recipient when the send is accepted. ## What is auto-recharge and how do I enable it? Auto-recharge automatically adds funds to your balance when it falls below a minimum threshold. Set your minimum balance and your target balance under **Billing > Payment Methods**. When your balance drops below the minimum, we charge your card on file for the difference up to the target and add the funds instantly. Each recharge tops up to the target and never more, so a send that costs more than your target is funded by several charges in a row, each with its own receipt; set the target close to what a typical send costs to keep that to one or two. Each recharge waits for the previous one to land in your balance (usually a second or two) and then at least 15 seconds, so a card is never charged twice for the same shortfall. If auto-recharge runs ten times in one day, your billing contacts receive one email suggesting a higher minimum and target balance, sized from what you spent that day, so future sends need one or two charges instead of many; auto-recharge keeps running. Auto-recharge is always available for top-tier organizations (Tier 0 and 1). A sub-organization can add a card and turn on auto-recharge as soon as its direct parent organization has connected a Stripe account, so a reseller's clients get the same protection against interrupted campaigns. See [Bring Your Own Stripe](/help/bring-your-own-stripe) for how resellers connect their account. ## What do I need to add a card? When you add a card on Billing > Payment Methods, the form has two parts. **Organization billing details** (billing email, phone, billing address) are prefilled from your organization; anything missing is asked for right there and saved to your organization so you only do it once, and nothing already on file is removed. **Card details** (name on card, and the card's own billing address if it differs from the organization's) belong to the cardholder and are stored only with that card, so an agency can keep several client cards on file and switch between them. Your Stripe customer record is created when the first card is saved and is kept in step with your organization details before every charge. ## How does organization hierarchy affect billing? When a sub-organization sends messages, all parent organizations in the hierarchy are charged based on their respective pricing tiers. For example, if Sub-Org A sends 1,000 messages, both Sub-Org A, Parent Org B, and Top-Org C all pay their tier prices. Each org sees their own balance deducted in real-time. This allows flexible billing arrangements across complex team structures. Because charges roll *up*, funding responsibility runs *down*: every organization in the chain must be able to cover its own share of a charge. If a parent organization runs out of funds, its sub-organizations are blocked from new usage even when their own balance is healthy - the parent's balance acts as a spending cap for everything beneath it. ## What happens if my balance runs out? If your balance reaches \$0, your entire organization tree is locked from sending messages until funds are added. Set up auto-recharge to prevent interruptions. You'll receive warnings at 20%, 10%, and 5% remaining balance. Add funds manually anytime through the billing dashboard. This applies to parent organizations too. If a **parent** organization hits its floor, its sub-organizations are blocked from sending as well, even if those sub-organizations are fully funded - so the fix is to add funds to the organization that actually fell short, not the one that hit the error. The error identifies which organization ran out (`details.isAncestor` is `true` when it is a parent's wallet rather than your own). To keep sub-organizations sending through a temporary dip, ask your account representative about a credit line on the parent. When a parent's shortfall blocks a sub-organization's scheduled send, the sub-organization's running projects are paused automatically with the reason "insufficient funds (parent organization)", the parent organization's billing admins receive an in-app notification naming the sub-organization, and both organizations see a banner in the dashboard until the situation clears. Once the parent adds funds, the sub-organization starts its paused projects again from the Projects page; they do not resume on their own. Nothing is torn down and no account is locked: you can keep signing in, reviewing reports and managing contacts while sending is blocked. Organizations approved for post-pay billing can be granted a credit line, letting sending continue past \$0 down to the agreed credit limit. Your remaining spendable funds (balance plus available credit) appear in the header balance tooltip and on the Payment Methods page. A credit line disables auto-recharge, since post-pay organizations draw on credit rather than a card. Contact your account representative to set one up. If you manage sub-organizations, an owner or admin can set a sub-organization's credit line from **Admin > Organizations**; an organization can never set its own. ## What is a spend commitment? A spend commitment is a promise to spend at least a set amount per period (monthly, quarterly, or annual). At the end of each period the shortfall, if any, is billed to the committed organization's balance; meeting or exceeding the commitment costs nothing extra. Your organization's own commitment, with progress for the current period and the history of past periods, is shown on **Billing > Pricing**. Commitments are set by whoever funds the organization: your account representative for a direct customer, or the parent organization for a sub-organization. If you manage sub-organizations, an owner or admin can create, edit, cancel, and forgive a sub-organization's commitment from **Admin > Organizations**. ## How do agency clients join my organization hierarchy? An owner or admin can mint an **organization signup link** from **Admin > Organizations** to bring a new client on as a sub-organization without a manual setup call. Each link has a link name, a host (the main platform domain or one of your own custom app domains), an expiry (never, 24 hours, 7 days, 30 days, or a custom date), and a use limit (single use, a fixed number of uses, or unlimited). Links are revocable at any time, and the link URL is shown once at creation and cannot be retrieved afterwards, so save it somewhere your team can share it from; if you lose it, revoke the link and create a new one. The link name is only your own reference for the link: whoever signs up through it chooses their own organization name, so the two usually differ. You can rename a link at any time, including after it has been used or revoked. Each link's row lists the client organizations that have actually registered through it, which is how you confirm a prospect's signup went through. A prospect who signs up at `/register?link=` becomes an **active child organization one tier below yours immediately** - there's no platform approval step to wait on. You get an in-app and email notification the moment they register. The new sub-organization then goes through its own [account setup](/onboarding/account-setup): business profile and funding, with your organization able to add funding on its behalf per the hierarchy rules above. Anyone visiting the organization signup link before signing up sees only your organization's name and logo, nothing else about your account. Signup links only work while sub-organizations are enabled for your organization: they stop working if your organization is suspended or the feature is turned off. Registration links are a dashboard feature; they aren't part of the public API or SDKs. ## What are the 10DLC registration costs? Per brand (per candidate) setup breakdown: 1. **Brand Registration:** \$4.50 one-time 2. **Campaign Verify Token:** \$95 one-time (valid for the current two-year election cycle) 3. **First Campaign:** $30 for first 3 months, then $10/month ongoing \*\*Total initial cost per brand: $129.50.** Additional campaigns under the same brand: $30 for 3 months, then \$10/month each. Phone numbers cost extra based on your pricing tier. Consulting firms managing multiple candidates multiply these costs by the number of brands (candidates). Registration timeline: 2 to 3 business days per brand. > [!NOTE] > > **10DLC Registration Pricing (per brand)** > > | Item | Cost | Notes | > | - | - | - | > | Brand Registration | **\$4.50** | One-time, instant | > | Campaign Verify Token | **\$95.00** | One-time, valid for the current two-year election cycle | > | First Campaign | **\$30.00** | Covers the first 3 months | > | Ongoing Campaign Fee | **\$10.00 / month** | Per campaign, after initial 3 months | > | **Total Initial Setup** | **\$129.50** | Per brand | > > Consulting firms managing multiple candidates multiply these costs by the number of brands (one brand per candidate). Phone numbers are billed separately based on your pricing tier. > [!NOTE] > > **Email Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Email sending | **\$3.00 / 1,000 emails** | \$0.003 per recipient. Lower with volume. | > | Full-service email sending | **\$0.01 per email** | Our team builds and sends every campaign. Lower with volume. No monthly fee. | > | Full-service email setup | **\$1,000 one-time** | Domain authentication, DNS records, warm-up, and list import. | > | Sending domains | **Free** | Unlimited domains and From addresses. | > | Hosted unsubscribe and preferences | **Free** | Included with every send. | > | Dedicated IP pool add-on | **\$35.00 / month per sending domain** | Optional dedicated managed sending IP pool for one sending domain. Warm-up usually takes up to about six weeks, depending on your volume. | > | AI email draft (Lincoln) | **\$3.00 per draft** | AI-drafted email template from a prompt, images and brand colors. | > > Test sends are real sends and are billed at the same per-recipient rate. Email charges appear in the ledger under the Email family and roll up through the organization hierarchy like texting. > [!NOTE] > > **Domain Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Domain registration | **Registrar's price** | One year. Prices vary by ending, shown before you buy. Non-refundable once registered; refunded if registration never happens. | > | Domain hosting fee | **\$6.00 / year** | Flat. Covers the DNS records we write and keep current for the domain. | > | App or link-tracking host setup | **Normal setup fee** | One per host. | > > Charged from your wallet at purchase and renewed yearly, 30 days before the domain expires. Dashboard only. Toll-free numbers and toll-free message sends are billed separately at toll-free rates, visible on your pricing page. Toll-free projects skip brand and campaign registration, so none of the 10DLC fees above apply to them. ## How do I cancel a campaign or phone number subscription? Open **Billing > Subscriptions** and choose **Cancel subscription** on the campaign or number. You pick one of two modes: * **At end of period** stops renewal. The campaign or number keeps working until the period you already paid for ends, and you can reverse it with **Don't cancel** at any time before then. * **Now** takes effect immediately. To confirm, type the campaign name or the last four digits of the number. Numbers are released and there is no refund. Deleting a brand is done from the 10DLC page and requires typing the brand name. ## What do AI features cost? AI survey analysis is billed at \$0.05 per analyzed reply. Only replies that fail exact answer matching are sent for analysis; exact matches stay free. You enable it per survey, so surveys without the toggle are never charged. Linc reply drafting and the Linc support assistant are included at no extra charge. ## What happens to messages that are held when I pause a project? Pausing stops delivery immediately. Messages that were already prepared but not yet delivered are held, and they stay paid for so they can go out as soon as you resume. If the project stays paused for more than 24 hours, the held messages are refunded to your wallet automatically and you receive a notification with the count and amount. Resuming later sends those recipients again and bills them again. Editing the project while paused also refunds the held copies, including any still waiting to go out, and everyone not yet sent receives the edited version when you restart. Deleting the project refunds them too. Messages that were already delivered are never refunded. ## Can I get a refund for unused balance? Account balances do not expire and can be used anytime. Refund policies depend on your agreement terms. For most accounts, balances are non-refundable but remain available indefinitely. Contact your account manager for specific refund questions or special circumstances. ## Can I download invoices and receipts? Yes. **Billing > Ledger** has an Invoices card listing your last 12 months with each month's opening balance, usage, payments and credits, and closing balance. Each closed month has a PDF invoice that opens with an account summary (opening balance, payments received, adjustments and refunds, usage charges, closing balance, amount due) followed by every usage charge by service (text message lines show what you sent and the replies to STOP, START and HELP separately), volume by day for messages, email and lookups, adjustments, refunds and payments received, with a per-organization breakdown when you pay for sub-organizations, and a CSV with the same lines for your books. Invoices are generated automatically on the first of the month; older months generate the first time you download them. **Billing > Payment Methods** has a Payments card listing every payment added to your balance, each with a receipt PDF. Every card payment, manual or auto-recharge, also emails a receipt to your organization's billing email, or its contact email if no billing email is set. Documents carry the branding and support contact of the organization that bills you, and dates are in UTC, matching the ledger. An invoice covers usage in the calendar month. The amount due is the balance owed at month end: \$0.00 when your balance covered the month, since usage is drawn from your prepaid balance, or the balance owed if your account is on credit terms and closed below zero. # Bring Your Own Stripe Source: https://docs.politicalcomms.com/help/bring-your-own-stripe How resellers connect their own Stripe account to collect payments from their sub-organizations directly. ## Who this is for > [!NOTE] > > Bring your own Stripe is enabled per organization by Political Comms. If you do not see the **Your Stripe account** card on Billing > Payment Methods, contact support to have it turned on. This applies to reseller organizations with sub-organizations underneath them. If your organization has clients, teams, or candidates set up as sub-organizations, you can connect your own Stripe account so their card payments and recharges settle directly with you instead of with Political Comms. ## Before you connect: what Stripe verifies You can use a Stripe account you already have, or create a new one during the connection flow. Either way, Stripe verifies: * **Company details.** A US company or LLC settling in USD, with a legal entity name, EIN, and the identity of the business owner. * **Business details.** Industry: pick the one that matches your website. Consulting services fits most political consultants and firms, Advertising services fits digital advertising and direct mail shops, and Business services is the fallback. All three are standard-risk categories at Stripe. Do not pick Telecommunications or Political organizations, and never describe the business as telemarketing, robocalling, or lead generation: Stripe prohibits telemarketing outright and its review reads descriptions literally. Business type: Company, or the entity type you registered. Product description: describe what you sell to campaigns in the same words your website uses, because Stripe compares the two. A full-service firm might write: "We are a political consulting firm providing communication services to campaigns and committees, including strategy, digital advertising, direct mail, voter outreach programs, design, and print." A texting-focused firm might write: "We are a political consulting firm running compliant peer-to-peer voter communication programs for campaigns and committees, including message strategy, list management, and reporting." * **Website.** A live HTTPS site on your own domain, not a free subdomain from a site builder such as Wix, Squarespace, GoDaddy Sites, Google Sites, or Carrd. The site should name your business, describe what you sell, and show how to contact you, along with privacy, terms, and refund policy pages. * **Public details.** Business name, logo, brand color, support email, support phone, support URL, and statement descriptor. These are what your sub-organizations and their card issuers see on receipts and statements. * **Payouts.** Adding a bank account is how you receive your funds, but it is not required to start accepting charges. ## Connecting 1. Go to **Billing > Payment Methods**. 2. Click **Connect with Stripe**. 3. Sign in to your existing Stripe account, or create a new one. 4. Review and **Authorize** the connection. If the account you sign into is a Standard account already controlled by another platform, Stripe won't let you connect it as-is. It walks you through creating a separate Stripe account instead, which you can then connect. ### Sign in, or create an account on the spot When you click Connect, Stripe asks you to sign in. Already have a Stripe account? Sign in and authorize. No Stripe account yet? You can create one right there, and it will be set up under the Political Comms platform. It is your account, with your own Stripe login, bank, and payouts, and billing works identically either way. ## After you connect Once your Stripe account is connected and active: * Your direct sub-organizations can add a card and turn on auto-recharge. Their cards are stored on the Political Comms platform, but every charge runs as a direct charge on your connected Stripe account with your descriptor. * You are the merchant of record for those charges. They appear in your own Stripe dashboard, follow your payout schedule, and carry your statement descriptor, not ours. * Stripe emails your sub-organization a receipt after each successful payment, sent to its billing email (or contact email if no billing email is set). The receipt carries your Stripe account's public details. This happens whatever your Stripe account's customer email settings are. * Refunds and disputes for sub-organization charges are handled in your own Stripe dashboard. After issuing a refund in Stripe, adjust the sub-organization's balance in the app to match. * Every payment your sub-organizations make, and every balance adjustment applied to them, is listed on your own **Billing > Ledger** page under **Sub-organization payments and adjustments**, with who received the payment and who applied each adjustment. You do not need to open each sub-organization's ledger to audit them. Routing only ever goes to the **direct** parent. A sub-organization's charges settle with its immediate parent's connected account, not with a connected grandparent or higher ancestor. ## If Stripe pauses your account or you disconnect If your Stripe account is disconnected, or Stripe itself pauses it, your sub-organizations are refused immediately: they cannot add a new card or trigger a recharge while the connection is down. Your organization's billing roles receive a notification when this happens. Existing sub-organization cards are not removed. Once you reconnect a Stripe account, those cards and auto-recharge work again without needing to be re-entered. ## Connecting with a restricted API key If you do not want to use Connect, support can link your Stripe account with a restricted API key instead. Your sub-organizations' top-ups still go to your account, and everything else works the same. With a restricted key, we have no access to your account details, balances, payouts or disputes. Stripe enforces this. The key can read customers and payments on the account, so using a Stripe account dedicated to these top-ups gives you the most privacy. Contact support to set this up. If you are already on Connect and keep the same Stripe account, your sub-organizations' saved cards carry over. If you move to a different account, they re-enter their cards. # Buying a Domain Source: https://docs.politicalcomms.com/help/buying-a-domain Buy a domain in the dashboard and let the platform set up every DNS record for your app, link tracking and email. You can buy a domain without leaving the dashboard. Open **Domains** in the sidebar, click **Add domain**, and choose **Buy a domain**. Pick the domain, choose what it is for, and we register it and write every DNS record for you. There is nothing to copy into another provider. > [!NOTE] > > Domain purchase is available in the dashboard only. It is not part of the public API. ## What you choose * **The domain.** Search for a name with most common endings. We only offer endings that keep your people, address and contact details private. Some may show your organization's name. Prices vary by ending, and you see the price before you buy. When a name is taken, or its ending is not available here, the search offers similar names you can choose instead, each with its price. A few endings are not available: those that need a local address or extra registrant details, such as `.de`, `.uk`, `.ca` and `.eu`, and adult endings. Endings with two parts, such as `.co.uk`, are not available either. * **What it is for.** Pick any mix of **App** (your branded login and dashboard host), **Link tracking** (the host your text links use) and **Email** (the domain you send campaigns from). You see the full price before you pay. ## Who owns it Your organization owns the domain. Before you confirm, the purchase shows **Registered to** with your organization's legal name and billing address. If your organization is missing its legal company name, billing address, contact name or a US phone number, add them in your organization settings first. Nothing is charged until they are complete. There is nothing for you to verify. We manage the domain at the registrar and handle every registrar email, so you never have to click a link to keep it working. ## What it costs | Item | Cost | | - | - | | Domain registration | The registrar's price for the ending you chose, for one year | | Domain hosting fee | **\$6.00 per year**, flat | | Setup fee | The normal setup fee for each app or link-tracking host you turn on | The registration and hosting fee are charged from your wallet when you buy, and again each year at renewal. See [Billing](/help/billing) for how the wallet works and the pricing reference below for current rates. > [!NOTE] > > Domain registration is **non-refundable once the domain is registered**. If registration never happens, you are refunded in full automatically. ## What we write for you Once the domain is registered we create all of its DNS records and keep them current: * The records your app and link-tracking hosts need, as plain CNAMEs. * The authentication records for email sending (DKIM, the bounce path, DMARC and the ownership records), if you chose email. * The verification records that prove the domain is yours. You never edit DNS for a domain you bought here. Setup finishes on its own and the **Domains** page shows progress for each use on the domain's row. Open the domain for the detail of each one. ## Renewals The domain renews every year. We charge your wallet **30 days before the domain expires**, so keep enough balance or turn on auto-recharge. You get a notice before each renewal. If a renewal cannot be paid, the account enters the normal grace period for unpaid charges. If it is still unpaid after the grace period, the domain is not renewed and stops working when its current term ends. Anything using it (your app host, link tracking and email) stops with it, so renew or switch hosts before then. When the term ends we email your account owners and admins. The domain's app host, link tracking and email setup are then removed from your account, and its DNS is deleted. Links already sent on it stop working. You can try to buy the name again, but it may not be available right away and someone else may register it first. ## Changes and leaving We manage the domain for as long as you keep it with us, including its DNS, its registrar contacts and its renewal, so there are no registrar controls in the dashboard. To change anything, or to take the domain to another provider, contact support at the address on the [Technical Support](/help/technical-support) page and we will do it for you. ## Already own a domain You can still use a domain you registered elsewhere. See [Sending Domains and DNS](/help/email/sending-domains-and-dns) for email, and the notes below for app and link-tracking domains. ### App and link-tracking domains you manage yourself A customer-managed app or link-tracking domain shows **two DNS records at the same time**. Add both at your DNS provider: * Both must be plain **CNAME** records. * **Proxying must be off.** If your DNS provider offers an orange-cloud or proxy setting, turn it off so the record is DNS only. A proxied record cannot be verified. The page marks each record as found once it resolves. Records usually appear within a few minutes, though some providers take longer. # Compliance Basics Source: https://docs.politicalcomms.com/help/compliance TCPA, consent, CTIA principles, and how to handle opt-out requests. > [!NOTE] > > This page covers the most common compliance questions. For full detail on each regulation, see the dedicated [Compliance Guide](/compliance/overview). ## Is P2P texting legal for political campaigns? Yes, when done correctly. P2P texting is 100% legal and TCPA-compliant for political campaigns because it requires human interaction for each message sent. Political messages to personal phones are exempt from certain TCPA restrictions, but you must still follow carrier guidelines, honor opt-outs immediately, and avoid deceptive practices. Always obtain proper consent when possible. ## What is TCPA and how does it affect me? The Telephone Consumer Protection Act (TCPA) restricts automated calls and texts to protect consumer privacy. While political texts are generally exempt, TCPA still requires: 1. Honoring opt-out requests 2. Not using true "auto-dialers" that don't require human interaction 3. Not calling before 8 AM or after 9 PM 4. Identifying your organization clearly Violations can result in $500 to $1,500 per message in penalties. ## Do I need consent to text people? For political campaigns, prior express consent is not legally required but is strongly recommended to improve engagement and deliverability. Obtain consent through: * Website sign-ups * Event registrations * Keyword opt-ins (e.g., text JOIN to 12345) * Petition signatures with SMS opt-in checkbox * In-person sign-ups Document all consent methods. Carriers may filter messages without documented consent. ## What are CTIA Messaging Principles? CTIA (wireless industry association) established best practices that exceed legal minimums to prevent spam. Key principles: obtain opt-in consent with clear disclosures, provide easy opt-out mechanisms (support STOP keywords), honor opt-outs immediately, don't share phone numbers between organizations without consent, include sender identification in messages, and monitor for abuse. Following these prevents carrier filtering. ## How do I handle opt-out requests properly? Opt-outs must be processed immediately (within seconds). Support multiple opt-out methods: reply with STOP/UNSUBSCRIBE/QUIT/CANCEL/END, phone calls, email requests. Maintain updated opt-out lists and check against them before every send. Once opted out, contacts stay opted out permanently unless they explicitly opt back in. Our platform handles this automatically with audit trails. ## Going deeper > [card] [Full Compliance Guide](/compliance/overview) > > Deep dive into TCPA, FCC, CTIA, 10DLC, and Campaign Verify. > [card] [Compliance Checklist](/compliance/checklist) > > Quick checklist to make sure every campaign stays compliant. # Data exports to your S3 bucket Source: https://docs.politicalcomms.com/help/data-exports 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. Data Exports writes your messaging data as Parquet files into an S3-compatible bucket that you own, on a schedule you choose. It is a dashboard feature under **Admin > Data Exports** and needs the `admin.data_exports.manage` permission. There is no API endpoint for it. ## What you need * An S3-compatible bucket. AWS S3 works natively. Backblaze B2, Cloudflare R2, Wasabi, DigitalOcean Spaces and MinIO work with their endpoint URL. * An access key scoped to that bucket. The minimal policy is shown in the destination dialog and needs only `s3:PutObject`, `s3:AbortMultipartUpload` and `s3:ListMultipartUploadParts` on `arn:aws:s3:::YOUR_BUCKET/*`. * Optionally, a lifecycle rule on the bucket that aborts incomplete multipart uploads after a day. We check for it and warn if it is missing. The secret key is encrypted with AWS KMS envelope encryption and bound to the destination record. It is never logged and never returned by the API. You can rotate it by editing the destination and revoke it at any time in your own account. ## Setting up a destination 1. Open **Admin > Data Exports** and choose **New destination**. 2. Enter a name, the bucket name, region, access key ID and secret. Add a prefix if you want the files under a folder, and an endpoint URL for a non-AWS provider. 3. Pick a schedule, the datasets to export, and, for parent organizations, which child organizations to include. 4. Save. We write a small probe object under `_validation/` in your bucket. If the write fails, the destination is not created and the error from your provider is shown. ## Schedules and windows | Schedule | When it runs | What it covers | | - | - | - | | Hourly | Five minutes past every hour | Everything since the previous hourly export | | Daily | 08:00 UTC | Everything since the previous daily export | | Manual | When you press **Export Now** | A range you choose, up to seven days | Every window ends five minutes before the run starts so late carrier receipts are included. Each scheduled run continues from where the previous one ended, so a paused or failed run never leaves a gap; a destination that fell behind catches up seven days per run. The first run after a destination is created covers only the most recent hour or day. A **Full Export** walks your whole history in seven-day chunks, up to two years back, and can be started once every 30 days per destination. Failed chunks can be retried without restarting the batch. ## File layout Files land under your prefix in a Hive-style path that Athena, Glue, Snowflake, Databricks, BigQuery and DuckDB discover without configuration: ``` /v1/schema_type=message_events/year=2026/month=09/day=26/hour=08/ _message_events_20260926T080001Z_.part-000.parquet ``` * Parquet with SNAPPY compression. Files rotate every 100,000 rows (`part-000`, `part-001`, ...). * The `year`, `month`, `day` and `hour` folders are when the export ran, in UTC, not when the rows were created. Filter on the row timestamps for reporting periods. * A window with no rows writes nothing. The job still appears in the history with **No rows**. * Rows inside a file are not ordered. * Timestamps are Parquet `TIMESTAMP_MILLIS` in UTC. Phone numbers are E.164 (`+15555550123`); short-code senders appear as the short code itself (`471016`). * The `v1` prefix is the schema version. New columns are added at the end; existing columns are never renamed or removed within a version. ## Datasets ### message\_events One row per outbound and inbound message. A message is exported again in a later window whenever its delivery status changes after it was first exported (for example a delivery receipt that arrives the next day). Keep the row with the greatest `updated_at` per `message_id`. | Column | Type | Meaning | | - | - | - | | `message_id` | string | Message id | | `external_message_id` | string, nullable | Carrier message id | | `conversation_id` | string | Conversation the message belongs to | | `project_id` | string, nullable | Project id | | `project_name` | string, nullable | Project name at export time | | `project_type` | string, nullable | Project type | | `direction` | string | `outbound` or `inbound` | | `status` | string | Delivery status at export time: `unsent`, `queued`, `sending`, `sent`, `delivered`, `failed`, `received` (inbound) or `on_hold` | | `channel` | string, nullable | Channel | | `protocol` | string, nullable | `sms`, `mms` or `rcs` | | `from_phone_number` | string | Sender | | `to_phone_number` | string | Recipient | | `message_text` | string, nullable | Message body | | `media_url_count` | int32 | Number of attached media URLs | | `send_type` | string, nullable | `scheduled` (project send), `manual`, `auto-response`, `test` or `chat` | | `error_code` | string, nullable | Carrier error code in the display form used by the dashboard (the `40` prefix stripped: `300` for `40300`) | | `error_reason` | string, nullable | Human-readable label for `error_code` | | `sent_at` | timestamp, nullable | Accepted by the carrier | | `delivered_at` | timestamp, nullable | Delivery receipt time | | `failed_at` | timestamp, nullable | Failure time | | `url_clicked_at` | timestamp, nullable | First click on a tracked link in this message | | `url_click_count` | int32, nullable | Click count at export time | | `contact_id` | string, nullable | Contact id, for joins to your own contact data | | `organization_id` | string | Organization that owns the message | | `created_at` | timestamp | When the message row was created | | `updated_at` | timestamp, nullable | Last change to the row; use it to keep the latest version of a message | ### project\_summary One row per project, written in the window that holds its completion time. Drafts, scheduled and in-progress projects are not exported until they complete. | Column | Type | Meaning | | - | - | - | | `project_id` | string | Project id | | `campaign_id` | string, nullable | Campaign id | | `name` | string | Project name | | `type` | string, nullable | Project type | | `protocol` | string, nullable | `sms`, `mms` or `rcs` | | `channel` | string, nullable | Channel | | `status` | string, nullable | Project status | | `total_recipients` | int32, nullable | Audience size | | `messages_sent` | int32, nullable | Messages sent | | `messages_delivered` | int32, nullable | Messages delivered | | `messages_failed` | int32, nullable | Messages failed | | `scheduled_at` | timestamp, nullable | Scheduled start | | `sent_at` | timestamp, nullable | First send | | `completed_at` | timestamp, nullable | Completion time (the export window key) | | `organization_id` | string | Owning organization | | `brand_id` | string, nullable | Brand | | `created_at` | timestamp, nullable | Project creation time | ### opt\_out\_events One row per opt-out, in the window that holds its creation. | Column | Type | Meaning | | - | - | - | | `opt_out_id` | string | Opt-out id | | `phone_number` | string | Opted-out number | | `source` | string, nullable | How the opt-out was recorded: `Replied`, `CSV Upload`, `Tagged` or `Manual` | | `opt_out_message` | string, nullable | The reply that triggered it, when there was one | | `brand_id` | string, nullable | Brand the opt-out list belongs to | | `organization_id` | string | Owning organization | | `opted_out_at` | timestamp, nullable | When the person opted out | | `created_at` | timestamp | When the row was created | ### click\_events One row per click on a tracked link, in the window that holds the click. | Column | Type | Meaning | | - | - | - | | `click_id` | string | Click id | | `tracking_link_id` | string | Tracked link id | | `message_id` | string | Message that carried the link | | `project_id` | string | Project | | `contact_id` | string, nullable | Contact | | `phone_number` | string, nullable | Recipient number | | `short_url` | string | The tracked URL as sent | | `destination_url` | string | Where it resolved | | `clicked_at` | timestamp | Click time | | `ip_address` | string, nullable | Client IP | | `user_agent` | string, nullable | Browser user agent | | `device` | string, nullable | Device class | | `browser` | string, nullable | Browser | | `os` | string, nullable | Operating system | | `country_code` | string, nullable | Country | | `region` | string, nullable | Region or state | | `city` | string, nullable | City | | `referrer` | string, nullable | HTTP referrer | | `utm_source` | string, nullable | UTM source on the destination URL | | `utm_medium` | string, nullable | UTM medium | | `utm_campaign` | string, nullable | UTM campaign | | `is_unique_click` | boolean | First click from this recipient on this link | | `is_share_click` | boolean | Click on a forwarded link | | `is_bot_click` | boolean, nullable | Classified as a bot or link scanner | | `organization_id` | string | Owning organization | | `brand_id` | string, nullable | Brand | ## Reading the files * **Athena or Glue**: crawl the `v1/` prefix or create a table with partition projection on `schema_type`, `year`, `month`, `day` and `hour`. * **Snowflake**: create an external stage on the bucket and load with `COPY INTO` or Snowpipe auto-ingest. * **Databricks**: point Auto Loader (`cloudFiles`) at the `schema_type=...` prefix. * **DuckDB**: `SELECT * FROM read_parquet('s3://bucket/prefix/v1/schema_type=message_events/**/*.parquet')`. For `message_events`, deduplicate on `message_id` keeping the row with the greatest `updated_at`. ## Job history The **Export jobs** tab lists every run with dataset, status, rows, size and duration. Jobs retry up to three times on transient failures; a job that keeps failing shows the provider's error message. A failed run leaves no partial file behind. # Bounces, complaints, and unsubscribes Source: https://docs.politicalcomms.com/help/email/bounces-complaints-and-suppressions What happens when a message bounces or is marked as spam, how unsubscribes are recorded, and how these compliance records keep an address from being mailed again. Every mailbox provider judges you on the same two numbers: how many of your messages bounce, and how many people mark them as spam. Both are handled for you here, and the handling is deliberately conservative, because the cost of mailing an address you should not have mailed is much higher than the cost of skipping one you could have. Bounces, complaints, and unsubscribes are **compliance records**: they apply automatically to every email send, and you never attach them to a campaign. They are listed under **Assets > Lists > Do not contact > Unsubscribes and bounces**. A **suppression list** is something else: a list you choose on one campaign to leave out (see [Holding out a list from one campaign](#holding-out-a-list-from-one-campaign)). ## Bounces A bounce is the receiving server refusing the message. There are two kinds and they are treated very differently. ### Hard bounce (permanent) The address does not exist, or the domain does not. It will never work, and retrying it damages your reputation. Three things happen at once: 1. The message is marked **bounced**. 2. The address is **blocked platform-wide**, so no sender in any organization mails it again. 3. The **list contact is marked** `bounced`, so it disappears from the sendable set of every list it is on. One exception: sometimes the receiving mail system refuses a message because of your reputation or its own policy, such as a blocklist or an authentication rule, and not because the address is bad. That still counts as a bounce for the campaign's rate, but the address is **not blocked** and the contact is **not marked bounced**, since the address would have accepted the mail on another day. Platform-wide is the right scope here because a nonexistent mailbox is a fact about the address, not about your relationship with it. It is also why a clean list borrows the accumulated knowledge of every list before it. ### Soft bounce (transient) The mailbox was full, the server was busy, the message was greylisted. The message is marked **deferred**. Nothing is blocked on the first one, because a transient failure is usually exactly that. **After three soft bounces in a row from the same sender, the address is blocked for your organization and that sender.** In a row means three separate sends from that sender, one after another, with no delivery to that address in between; a single delivery resets the count, and sends from your other senders are not part of it. Three transient failures like that is no longer a busy server; it is an address that does not accept your mail. Bounces caused by the message itself, such as one rejected for its content or size, and temporary rate limiting by the receiving provider, do not count toward the three and do not interrupt them: they say something about the message or about your sending pace, not about the address. The block is not platform-wide, because unlike a hard bounce this is a fact about the relationship, not the address. A deferral is never charged a second time. The send was already billed when it went out. ## Complaints A complaint is a recipient pressing "report spam". It is the single most expensive event in email, and it is treated accordingly: the address is blocked at **three scopes at once**, for the sender identity, for your organization, and platform-wide. That is deliberately heavier than an unsubscribe. Someone who unsubscribes is telling you they do not want this mail. Someone who reports spam is telling Gmail you should not be sending mail at all, and the only correct response is to make certain it cannot happen again from anywhere. The list contact is marked `complained` and is never sent to again. ## Unsubscribes There are three ways a recipient can opt out, and all three work on every message you send: | Route | How it works | | - | - | | **One-click** | The mailbox provider's own unsubscribe button, powered by the `List-Unsubscribe` and `List-Unsubscribe-Post` headers. Required by Gmail and Yahoo for bulk senders. No confirmation page, no chance to mail again. The URL in the header is on the campaign's link domain, the same host as every link in the message. | | **Hosted preferences page** | The footer link opens a page where the recipient can opt out and give a reason, and choose to leave everything from the sending domain rather than just this sender. The page is served on your link domain (or the neutral platform link host) and shows only the From name the recipient saw and its sending domain: no organization name, no logo, so an agency's clients are never shown the agency. | | **The mailto address** | The `List-Unsubscribe` header also carries a per-message mailbox address, which some clients use instead of the URL. Mail sent to it is received and processed the same way, with no human in the loop. | **The default scope is the sender identity**, since that is the relationship the recipient acted on. The hosted page is where they can widen it to the whole sending domain if what they want is to hear from nobody on it. Organization-wide unsubscribes are yours to write (a do-not-contact upload, an address added by hand, or the API), never a recipient's choice. **Resubscribing.** A recipient who left one sender can come back from the same page. That lifts the sender unsubscribe and puts them back on every list of yours they had unsubscribed from, so the next campaign reaches them again. Rows that left for another reason (a bounce, a complaint, an invalid address) stay removed, and an organization-wide opt-out is not undone by a sender resubscribe. > [!WARNING] > > **An email unsubscribe never affects texting consent, and a text STOP never > affects email.** They are separate channels with separate consent, separate > records, and separate legal regimes. Someone who leaves your email list is still > a valid text recipient, and the reverse. If you want them off both, remove them > from both. Unsubscribes are honored synchronously. There is no batch window in which a recipient who just opted out can still receive a queued message. A provider retrying a one-click request does not produce a second unsubscribe event either; a recipient unsubscribes from one send exactly once. ## When these records are applied Twice, on purpose: 1. **When the campaign's audience is compiled.** Unsubscribed, bounced, and complained addresses are removed before the recipient count you see is calculated, which is why the number in the builder is often lower than the list total. 2. **Again at send time, per message.** A campaign that was compiled an hour ago and is still sending re-checks each address as it goes. The second check is the one that matters. Without it, a person who unsubscribed from message one of a large send would still get message eight hundred thousand, because the audience was fixed before they acted. ## Where an unsubscribe applies Unsubscribes and blocks live at three scopes and you can manage them yourself: | Scope | Blocks sending | | - | - | | `org` | Everywhere in your organization | | `identity` | From one sender identity, where a recipient unsubscribed | | `domain` | From every sender on one sending domain | All three apply automatically. There is nothing to attach to a campaign and so nothing to forget. Writes are bulk, up to 5,000 addresses per call, malformed addresses come back in an `invalid` array rather than failing the batch, and lifting an entry that was never set is not an error. Over the API these records are read and written at `/v1/email/suppressions`. ### Uploading a do-not-contact file To load your own do-not-contact file, go to **Assets > File Uploads**, drop the file, and choose **Do not contact** on the setup card. Choose the email column and whether it applies to the whole organization or to one sending domain, and every campaign in that scope skips those addresses from then on. A file that also has a phone column adds those numbers to an opt-out list at the same time. The emails are applied in the background, which takes minutes for a large file; they then show under **Assets > Lists > Do not contact > Unsubscribes and bounces**. Applying them also marks those people unsubscribed on your lists, so the counts you see are the counts that will actually send. To add a few addresses by hand, use **Add addresses** on the same page. ### Holding out a list from one campaign To exclude a set of people from a single campaign without unsubscribing them everywhere, choose an ordinary list under **Suppression lists** on the campaign. Any list can be used this way, exactly as a texting project holds out a list: both pickers on the campaign read from the same set of lists, and the campaign decides which are the audience and which are held out. ### Downloading your unsubscribes and bounces Use **Download CSV** under **Assets > Lists > Do not contact > Unsubscribes and bounces**. The file lists every entry for your organization, with its reason, scope, sender or domain, and date, so your own system of record can be reconciled against what the platform is actually blocking. Platform-wide entries, such as hard bounces, are not included. ## Why removing a contact does not delete it Removing an address from a list **unsubscribes it rather than deleting the row**, and that surprises people often enough to be worth explaining. The row is what carries the bounce and complaint history. Delete it, re-import the same file six weeks later, and you have resurrected an address that already complained, and you will mail it again. Keeping the row is the entire mechanism that keeps an address unmailed across imports. To erase an address completely, use [forget this address](/help/email/compliance-and-link-tagging#forget-this-address), which is a deliberately heavier and irreversible operation for genuine deletion requests. ## The sunset policy Mailing people who never open anything is the fastest way to lose a sending reputation, because that is precisely the pattern mailbox providers use to identify senders who are not paying attention. The sunset policy handles it, per list, controlled by `sunset_enabled`: | Stage | What happens | | - | - | | **90 days** with no engagement | The contact is **held out of sends**. It stays on the list and still counts in the total, but is not mailed. A human open or click resets the clock. | | **180 days** with no engagement | The contact's status becomes `sunset` and it leaves the sendable set for good. | Engagement is recorded on every list your organization has that contact on. Opens seen through Gmail's and Yahoo's image proxies count as activity, because those proxies load the image when the person opens the message, even though they are not counted as opens in your reports. Other automated opens, such as Apple's mail privacy proxy and security scanners, do not count, and neither do automated clicks. Contacts added in the last 90 days are never held: someone who has not had the chance to engage yet is not an unengaged contact. ### Winning people back before the drop The window between the hold and the drop is your chance to recover the people worth recovering. There is a **re-permission** starter template for exactly this: one short message asking whether they still want to hear from you. A campaign marked as a re-permission send is the one case that is **allowed to reach held contacts**, and it also ignores the frequency cap, because a message asking permission is worthless if the policy protecting you from over-mailing prevents it from arriving. Keep it plain, keep it short, and make the "yes, keep me" action a click, since a click is what resets engagement. Everyone who ignores it was going to cost you deliverability anyway. Letting them sunset is the right outcome, not a failure. ## Rate alarms Two thresholds pause a campaign automatically, well below the point at which the sending infrastructure would intervene: | Breaker | Threshold | Provider acts at | | - | - | - | | Bounce rate | **3%** | around 5% | | Complaint rate | **0.08%**, and at least 3 complaints | around 0.1% | The complaint rate divides by messages to providers that report complaints; Gmail reports none, so Gmail sends are left out, the same way the sending account is measured. Neither is judged until at least **500 messages** have been sent, and a complaint pause also needs at least **3 complaints**, so a handful of early bounces or a single spam click on a small send cannot trip them. See [Campaigns and deliverability](/help/email/campaigns-and-deliverability#deliverability-breakers) for what happens when one trips and how to resume. Separately, if our sending infrastructure disables one of your sender identities, every in-flight campaign on that identity is **paused automatically** and your organization is notified, rather than the sends failing message by message. See [Sender identities](/help/email/campaigns-and-deliverability#when-sending-is-paused-for-you). # Campaigns and Deliverability Source: https://docs.politicalcomms.com/help/email/campaigns-and-deliverability Sender identities, the campaign builder, test sends, the warm-up ramp, deliverability breakers, frequency caps, DMARC progression, tracking, and reporting. ## Sender identities A verified domain cannot send on its own. The thing that sends is a **sender identity**: the From address, plus the compliance information that goes in every footer. Create them under **Email > Senders**. | Field | What it is | | - | - | | **From name** | The display name recipients see, such as the candidate or committee name. | | **From address** | The mailbox part, on one of your active sending domains. | | **Where replies go** | Required. Replies to these emails go straight to this inbox, so use one someone reads. There is no inbox here. | | **Physical address** | The postal address CAN-SPAM requires in every message. | | **Disclaimer** | The paid-for-by attribution, plus whether the message is authorized by the candidate. | An identity activates only when **both** conditions hold: its domain is active, and the compliance fields are filled in. Try to activate one on a domain that is still verifying and you get a plain error saying so rather than a silent failure. If you later edit an active identity in a way that removes a required address or disclaimer, the identity is **paused rather than left sending non-compliant mail**. The save succeeds and sending stops, which is the safe direction: a paused identity is a problem you notice today, while non-compliant mail is one you find out about from a regulator. ### Each sender is isolated Every sender identity gets its own isolated reputation on our sending infrastructure. Practically, this means a committee that sends both a high-volume fundraising program and a careful volunteer-coordination program can keep them apart: if the fundraising sender runs into trouble, the volunteer sender is not dragged down with it. It is the reason to create a second identity rather than reuse one, whenever two programs have genuinely different audiences or risk profiles. ### When sending is paused for you Our sending infrastructure can disable an individual sender on its own judgment, usually for a complaint rate it considers unacceptable. When that happens the platform does not let campaigns keep failing message by message. **Every in-flight campaign on that identity is paused automatically**, the reason is recorded on the identity, and your organization is notified. Because identities are isolated, this stops at the one sender. Your other identities keep sending. ## Building a campaign A campaign is one message, from one sender identity, to one or more lists. Pick the audience, write the subject and body, and the platform deduplicates recipients across lists and removes anyone suppressed before it counts your audience. A campaign sends to every subscribed contact on its lists that is not suppressed. Each message is also [screened at send time](/help/email/lists-and-validation#address-screening-at-send-time): an address rated as likely undeliverable is not sent to, is not counted as a bounce, and shows in the report as **Screened as invalid**. The builder is organized in five groups: | Group | What you set | | - | - | | **Sender** | Which sender identity sends it. | | **Recipients** | The lists to send to, and any suppression lists to hold out. | | **Content** | The campaign name, a saved template, the subject, and the preview text. | | **Delivery** | Time zone, the send window (send after, stop by), how long to keep retrying, and whether the campaign requires approval. | | **Attribution** | Refcode, source code, link domain, whether to append UTM parameters, and whether this is a re-permission campaign. | When the campaign is built, choose **Save and continue**. The campaign opens on its own page and moves to the next step it needs: **Awaiting test**, **Awaiting approval**, or **Ready**. Scheduling is not part of the builder. Once a campaign is ready, choose **Start** on the campaign page or on its row in the Campaigns dashboard, then pick when it sends and in which time zone. The time starts at right now, so choosing it as is sends the campaign straight away. A scheduled campaign can be unscheduled from the same places, which returns it to ready. **The send window** is worth setting deliberately. It keeps a send from starting outside civilized hours in the recipient's time zone, rather than arriving at 3 AM. **Templates are built separately**, under **Email > Templates**, and the builder picks from your saved ones. That is where the document editor, **Import HTML**, and **Draft with Lincoln** live. See [Templates](#templates) below. **Link domain.** Every link in a campaign is rewritten to a tracked URL, the open pixel is added for you, and pasted bare URLs become links too, so click metrics are never optional. Choose which host those URLs use under **Link domain** in the builder: any active tracking domain the organization owns or shares (the `links.` host created with your sending domain under Admin > Domains), or the shared platform link host. Branding the host keeps link reputation with your domain and matches what recipients see. If the chosen domain is not active yet the checklist says so and the send falls back to the platform link host. The platform link host is `e.txtplatform.app`, a neutral hostname that carries no product name. Whichever host a campaign uses serves everything a recipient can reach: every tracked link, the open pixel, view in browser, the unsubscribe and preferences page, and the one-click unsubscribe the mailbox provider calls. A recipient on a branded campaign never leaves your domain. ### No A/B testing, and what to do instead There is no A/B split test. One campaign is one message to one audience. The supported equivalent is **Duplicate campaign** plus **Compare campaigns**: duplicate a campaign, change the one thing you want to test, send both to comparable segments, and then compare up to four campaigns side by side on the campaign page. It takes one more step than a split test and gives you a result you can read a week later, rather than a winner picked automatically on an hour of early opens. ## Sequences A campaign is a **Broadcast** (one email to everyone on its lists) or a **Sequence**: a first email, then follow-ups a chosen number of days apart, each from its own template. Pick the type when you create the campaign; it cannot be changed afterwards. A sequence is built on the first email's page. Under **Follow-ups**, add each later email, choose its template, and set how many days after the previous email it sends and the exact time (8:30, 9:15) in the campaign's time zone. The sender, lists, suppression lists, time zone and settings are the first email's and apply to every follow-up. Each follow-up has its own subject and preview text, filled from its template and editable. **Who gets a follow-up.** Each follow-up goes to the people the first email reached, minus anyone who has since unsubscribed, bounced, complained, replied, or been stopped by hand. Someone added to the list after the first email went out does not get a follow-up without it. Follow-ups are not held by the frequency cap: you chose their spacing. **Replies end the follow-ups.** With **Skip people who reply** on (the default), replies to a sequence email come back through this platform, are forwarded in full to the sender's reply address, and end that person's follow-ups. Reply from your own inbox as usual; the voter gets your answer directly. Automatic replies such as out-of-office notices are forwarded but do not count as a reply. Someone who phones or writes to a different inbox instead can be stopped from the campaign's **Recipients** table with **Stop follow-ups**. **Follow-ups as replies.** Turn on **Send follow-ups as replies in the same thread** and each follow-up arrives inside the conversation the first email started, under "Re:" its subject, the way a personal follow-up would; the follow-up subjects are set for you. Off (the default), each email stands on its own with its own subject line. **Scheduling, testing and stopping act on the whole sequence.** One test send sends one copy of every email. Scheduling the first email places every follow-up on the calendar; a follow-up whose time arrives while the email before it is still sending waits for it to finish. Unscheduling or deleting the first email takes the later emails with it, and a sequence stopped by a deliverability breaker never sends its next email. A follow-up that has started sending stays in the sequence. **Over the API.** `POST /email/campaigns` accepts a `sequence` object with the follow-up steps (template, days after the previous email, `send_time` as HH:MM), reads carry `sequence_id`, `sequence_position` and `stop_on_reply`, and the `email.replied` webhook event fires when a reply comes back. The recipients CSV of a sequence email opens with a table of every email's counts. **Reporting.** The campaign list shows a sequence as one row: how many of its emails have sent, how many people the first email reached and how many are still in the sequence (reached, minus everyone who has since replied, unsubscribed, complained, bounced or been stopped by hand), totals across its emails (sent, delivered, bounced, opened, clicked, replied, cost) and the status of the email up next; the chevron on the row expands it to one line per email with that email's own progress and metrics. Each email's page lists every email of the sequence with its status, timing and counts including bounces, a total row, the people reached and the people still in the sequence. Each email has its own report; sequence reports add a **Replied** count. ## Templates Templates live under **Email > Templates** and are reusable across campaigns. There are three ways to make one: * **The document editor.** Write the email like a document. Type `/` for a menu of blocks (text, headings, lists, buttons, donate buttons, images, columns, sections, dividers, spacers, quotes, footer text, a compliance footer, and a raw HTML block), and `@` to insert a merge tag as an editable pill. Paste from Google Docs or Notion and the formatting carries over. A Design rail sets the background, card color, font, and heading, text, link, and button colors, and a Checks panel shows live compliance checks, server lint, and the size against Gmail's 102 KB clip, alongside a desktop and mobile preview. * **Import HTML.** Paste HTML or upload a file, for a design your team already has or one exported from another tool. An HTML template is edited as text, and a document template can be converted to one, one way, with confirmation. * **Draft with Lincoln.** Describe the email and the platform's AI agent writes it, returning editable blocks in the document editor. See below. Every save returns a **lint** result. Read it: a template with lint errors will save, but a campaign built on it will not schedule. Warnings do not block. They include any image over 600 KB and a message whose images add up to more than 2 MB, for images in your email library. Links are not checked for whether they load, so click each one in your test send. ## Draft with Lincoln Lincoln, the AI agent already drafting your text replies, writes email designs too. The **Draft with Lincoln** button sits in the template editor's toolbar and on the templates page. Describe the email you want, optionally pick up to six images and your brand colors, and Lincoln returns a finished design: a subject, a preheader, and editable blocks that load straight into the document editor for you to edit. Four things worth knowing before you use it: * **It costs \$3.00 per draft**, at your organization's own price, and you are charged **only when a draft comes back ready**. A draft that fails, or that comes back invalid, is never billed. * **It is not instant.** Generation runs in the background and usually finishes in under two minutes. Leaving the page does not lose the draft. * **Images must already be in your email library.** Add them on the Upload tab of the image picker, or from the **Email** tab of **Assets > Media Library**. Picking a texting image adds that same file to your email library, with no second copy to keep track of. * **It replaces the document.** If the template already has content, you are asked to confirm before the draft overwrites it. Every draft is a starting point, not a send. It lands in the editor, and the same checklist, test send, and approval rules below apply to whatever you do with it. ### Drafting in the dashboard Drafting runs in the dashboard, not over the API. It is paid, asynchronous, and non-deterministic, so it stays a product feature rather than a versioned API contract: **Email > Templates > Draft with Lincoln**. If the wallet cannot cover the draft, generation does not start. If the balance runs out mid-generation the draft finishes failed and is not billed. ## The checklist A campaign will not schedule until its checklist is clear. The single-campaign API read returns a `blocked` array naming exactly what is unresolved, so an integration never has to guess: | Blocker | What to fix | | - | - | | `sender` | No sender identity chosen, or the one chosen is not active. | | `sender_compliance` | The identity is missing its physical address or disclaimer. | | `lists` | No lists selected. | | `sendable` | Zero recipients remain after deduplication, unsubscribes and bounces, and suppression lists. | | `subject` | The subject line is empty. | | `body` | The message body is empty. | | `lint` | The content has lint errors. Warnings do not block. | | `test_send` | Every campaign requires a successful test send before it can be submitted or scheduled, and none is on file. | | `balance` | The estimated cost exceeds your available wallet balance. | Some items appear as warnings rather than blockers, including sunset holds, frequency-cap holds, and warm-up ceilings. They tell you the send will reach fewer people than the list total, without stopping it. ## Test sends The builder's preview and every test send merge a real contact from the campaign's lists into the template, so a custom merge tag such as `{election_location}` shows that contact's value rather than the tag's name. **Preview as** on the builder steps through up to ten real contacts, and the test dialog lets you pick one of them or type any value for any tag before sending, as a texting test does. A campaign with no lists yet, or whose lists carry no fields, previews with a stand-in contact (Tyler Smith). The test copies of a sequence that sends follow-ups as replies arrive as one conversation, like the real ones. Send a real message to up to 10 addresses before committing. Test sends use sample merge data so you see what a recipient sees. **Every campaign requires a successful test send before it can be submitted or scheduled.** There is no setting to turn this off. If you edit a campaign after its test, the test is invalidated and you need to send another one before you can submit or schedule. A campaign that was only waiting on its test moves on by itself once the test is accepted: to ready, or to awaiting approval if it requires one. "Editing," for this purpose, means changing the body or content, the subject or preheader, the sender identity, the lists, the suppression lists, or the template. Changing the name, schedule, timezone, send window, or TTL does not invalidate the test. Two more things to know: test sends are **real sends and are billed** at the normal per-recipient rate, and they are **excluded from campaign statistics and never fire webhooks**, because they are your traffic rather than your audience's. They are also exempt from the warm-up ceiling, so a test never consumes your daily allowance. A test send skips any address that unsubscribed, bounced, or complained, and does not charge for it, and test sends are not available while sending is paused for your organization. ## Approval A campaign can require a sign-off before it sends. Turn on **Require approval before sending** in the campaign builder, which sets `require_approval` on the campaign (`false` by default). This is a per-campaign choice, not an organization-wide setting: some campaigns can require approval while others send as soon as their test is clear. When it's on, the campaign needs both a current test send and an approval before it can be submitted or scheduled. Editing the campaign after approval invalidates the approval the same way it invalidates the test, using the same definition of "editing" above. ## Warm-up A brand-new domain that sends 200,000 messages on its first day gets filtered, not delivered. Mailbox providers build reputation from a sending history, and no history plus sudden volume looks exactly like a compromised account. New domains ramp through a daily ceiling: | Step | Daily ceiling | | - | - | | 1 | 500 | | 2 | 1,000 | | 3 | 2,500 | | 4 | 5,000 | | 5 | 10,000 | | 6 | 25,000 | | 7 | 50,000 | | 8 | 100,000 | | 9 | 250,000 | | 10 | No ceiling | The ramp advances one step per **sending** day, **but only if yesterday went well**. The step-up is checked each night against your own numbers, and it is held if the previous day's bounce rate was 2% or higher or the complaint rate was 0.05% or higher. The complaint rate divides by messages to providers that report complaints; Gmail reports none, so Gmail sends are not in it, which is how mailbox providers and the sending account measure it too. A handful of events on a small day is not a rate, so a step is never held on fewer than 5 bounces or fewer than 2 complaints. A held step needs nothing from you: the domain keeps sending at its current ceiling, the addresses that bounced or complained are already suppressed, and the ramp resumes after the next clean sending day. The hold is shown with the domain's warm-up on the domain's page under **Domains**. This is the point of a ramp: a schedule that climbs regardless of results is a countdown, not a warm-up. A day on which the domain sent nothing does not count in either direction: it neither advances the ramp nor holds it. Reputation is built from a sending history, so a day with no history is no evidence. In practice this means the ten steps are ten days of sending, not ten days on the calendar: a domain that mails twice a week takes about five weeks to reach the top step. Two further points: * **Acquired lists ramp on half steps.** Every ceiling above is halved. * **The ramp belongs to the domain, not the sender.** Every sender identity on a domain shares the domain's step and its daily ceiling, and so does every campaign sending from it. A new identity on a warm domain is warm from its first send. Warm-up progress is shown on the domain, under **Domains**. The platform also has a daily sending limit shared by everyone. If it is reached, campaigns wait and resume on their own as capacity frees, usually within the hour; the campaign shows a waiting line while this happens. Nothing is lost and nothing is charged for messages that have not gone out. ### A campaign larger than today's ceiling It is not rejected. It goes out over several sending days. Before you send or schedule it, the Start dialog shows the schedule day by day. One million recipients from a brand-new domain looks like this: | Sending day | Sends | | - | - | | 1 | 500 | | 2 | 1,000 | | 3 | 2,500 | | 4 | 5,000 | | 5 | 10,000 | | 6 | 25,000 | | 7 | 50,000 | | 8 | 100,000 | | 9 | 250,000 | | 10 | 556,000 | What to expect while it runs: * **Later days start at the same time of day as the first.** A campaign started at 9 AM in its time zone sends each later day's share at 9 AM. * **The schedule is a projection.** Each step up still depends on the previous sending day's bounce and complaint rates, so it can take longer than shown. It does not go faster. * **Campaigns on the same domain take turns, in the order they joined the line.** A campaign joins at its scheduled start time; a resumed campaign joins again at its resume time. Campaigns at 11:00, 11:02 and 11:04 send in that order, whether each one is new or resumed. The campaign first in line gets each day's allowance first and finishes out before the next one starts. A later campaign sends whatever is left that day, and starts the moment the earlier one finishes. If the earlier campaign is waiting until tomorrow, today's leftover goes to the later one. The schedule shows days on which a campaign sends nothing as 0 and names the campaigns ahead of it. * **Pausing gives up your place.** A paused or unscheduled campaign stops holding the allowance, so the next campaign in line can use it the same day. Resuming it puts it at the back of the line, behind anything that started or resumed before it; what the other campaigns already sent stays sent. To let smaller campaigns go first, resume a large one at a later time. * **The campaign stays in `sending` between days.** The campaigns dashboard and the campaign page show when the next batch starts, in the campaign's time zone, and which sending day it is. The campaign page also shows what went out each day. The **Email** tab of **Scheduled Sends** (the calendar icon in the header) puts every sending day on the calendar: what went out on past days, and an estimate, marked "est.", for each day still ahead. * **You can pause at any time.** Later days do not send while it is paused. Resume works like Start: send now, or pick a date and time and the campaign shows as Scheduled until then, then resumes on its own. The resume time becomes its daily start time for the days after. It says how many recipients are still queued and shows the schedule again, updated for what has already gone out and where the domain is on the ramp. **Unschedule** calls a planned resume off and leaves the campaign paused. * **You can change it part-way.** Pause, then choose **Edit**. The campaign stays paused, and your changes reach the people not yet sent to once you resume. People who already received it keep the version they got and are never sent it again. If you change the content, send a test before resuming. If you change the lists, resume rebuilds the audience on the new lists: anyone no longer on them who had not been sent to is dropped, and anyone already sent to keeps their result. * **To abandon a paused campaign, delete it.** Its report is kept. The platform itself finishes a campaign early only when a deliverability breaker says it must (below); that campaign reads **Stopped** with how many were not sent, and the recipients download lists who they were. * **Some pauses end on their own.** When the platform pauses a campaign for something it can watch, it resumes the campaign itself once that clears: a balance that could not pay for the next batch (add funds, or let auto-recharge run), a sender that was not active, missing content, a sender whose sending was suspended, or a Gmail spam rate over the line. The banner says so. Resume is still there if you would rather not wait for the next sweep. Mailbox providers do not publish a daily reset time. Gmail counts bulk volume over a rolling 24 hours and asks senders for a consistent rate, which is why a multi-day send keeps one daily start time. ## Deliverability breakers If a send is going badly, continuing makes it worse. Three breakers act on a campaign automatically, and none of them waits for a person: | Breaker | Threshold | | - | - | | Bounce rate | **3%** | | Complaint rate | **0.08%**, and at least 3 complaints | | Gmail spam rate | **0.10%** (the sending domain's rate in Google Postmaster Tools) | The bounce and complaint rates are measured across the campaign (since its last resume, see below). The complaint rate divides by messages to providers that report complaints, which leaves Gmail out (it reports none), so it matches the rate the sending account is held to. Neither is judged until at least **500 messages** have been sent. A complaint pause also needs at least **3 complaints**: one or two spam clicks on a small send are noise, not a rate, so they cannot stop a campaign on their own. Rates are re-evaluated on a rolling sweep. For reference, our sending infrastructure begins suspending senders near 5% bounce and 0.1% complaint; these thresholds sit deliberately below that. Gmail does not report individual spam complaints to senders, so the complaint rate above cannot see Gmail. The Gmail spam rate fills that gap: it is read daily from Google Postmaster Tools for any domain connected there, and when the latest reported day is at **0.10% or more**, every scheduled or sending campaign on that domain pauses with `pause_reason` `gmail_spam_rate` and the domain's warm-up step is held. Google reports this rate about two days late, and it is the domain's rate, not one campaign's. Gmail begins filtering a domain to spam around 0.30%. The pause ends on its own: once a later daily reading is below 0.07%, or once Google has had nothing to report for four days, every campaign it paused resumes. **What the bounce breaker does.** Addresses this platform has never delivered to send last (next section), and they are where bounces come from. So when the bounce rate reaches 3%, the campaign does not pause: the never-mailed addresses still waiting are dropped from it (they read **Not sent** on the report and in the recipients download), you are notified, and the campaign keeps sending to everyone else and finishes on its own. From that point the breaker judges only what follows. If the rate reaches 3% again, or there was nothing left to drop, the campaign is finished automatically: it reads **Stopped** with how many were not sent, its report is kept, and you and our team are notified. **What the complaint breaker does.** Complaints are about consent and content, not addresses, so dropping anyone would not help: the campaign is finished automatically the same way. After any resume, the breaker judges only the mail sent after it: the campaign gets a fresh 500 sends before its rates are checked again. ### Addresses nobody has delivered to send last The one thing no upload check can tell is whether a mailbox still exists; only a delivery can. So a campaign sends every address this platform has delivered to before first, in the usual order (engaged, then recently added, then the rest), and only then the addresses it has never mailed: first those at Gmail, Microsoft and Apple, then those at every other domain, which bounce about twice as often. The bounce breaker judges the whole send since you started it, the way mailbox providers and our sending infrastructure read a sender: as a total. A resume does not reset that total; it only waits for another 500 messages before judging again. So an unproven tail trips the breaker only when it lifts the whole campaign to 3%, and by then everything that could be delivered has been. When never-mailed addresses are dropped, the notice says how many. To reach them, **Download** the list's unmailed addresses from the list page, run them through an address verification service, upload the result as a new list, and send a new campaign to it. The campaign checklist shows how many addresses on the selected lists are unproven before you send. Separately, if overall sending quality across the platform rises toward the level where mailbox providers act, campaigns sending to acquired lists or from sending domains under 30 days old are held before their next batch, then continue on their own once it recovers. Nothing is paused or charged while held, and the campaign page shows the hold. Our team is told the moment a hold starts and can let a specific campaign continue while it lasts; contact support if a held campaign matters to you. Every other safeguard on this page still applies to a campaign let through. For what happens to the individual addresses behind those rates, see [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions). ## Frequency cap An optional organization-level cap limits how often any one person is mailed **across all your campaigns**, with separate 24-hour and 7-day limits. It is **off by default**; turning it on suggests one message per 24 hours and three per 7 days, which you can change. When enabled, recipients already over the limit are **held out of the send** rather than the send being rejected, and the campaign reports how many were held. It is the cheapest protection against the most common self-inflicted deliverability wound: three committees, one shared list, one bad week. A [re-permission campaign](/help/email/bounces-complaints-and-suppressions#winning-people-back-before-the-drop) is exempt, since a message asking whether someone still wants your mail is useless if the frequency cap stops it from arriving. ## Sender requirements scorecard Gmail and Yahoo publish bulk-sender requirements. The scorecard, on the **sender identity** page, checks your domain against them continuously so you find out before a mailbox provider tells you: * SPF passes, DKIM signs every message, and both pass together * A DMARC policy is published, and messages align with it * Messages are properly formatted * Valid forward and reverse DNS, and mail sent over TLS * Spam complaints under 0.10% * Bounce rate under 2% * A physical mailing address is present Where [Google Postmaster Tools](/help/email/google-postmaster-tools) is verified for your domain, Gmail's own verdicts take precedence over our measurements for the categories it covers, since Gmail's opinion of your mail is the one that decides where it lands. ## DMARC progression DMARC tells mailbox providers what to do with mail that fails authentication. Starting at enforcement would bounce your own legitimate mail from any sending service you had forgotten about, so the policy moves in stages: `p=none` → `p=quarantine` at 10% → `p=quarantine` at 100% → `p=reject` Leaving `p=none` requires all of the following over a 30-day window: * **98%** or better aligned pass rate * At least **1,000** reported messages * At least **2** independent reporting sources, each counted by the domain the report was authenticated from; a report that claims to come from a different organization than the one that sent it is discarded Every later step additionally requires **14 consecutive clean days** at the current setting. If a new unaligned sending source appears at 1% or more of your volume, the policy backs off one step rather than dropping straight to `none`. We generate the record; you publish it. The record carries a reporting address where mailbox providers send their aggregate reports, which is what these thresholds are measured from. If you set your domain up before it did, see [Sending domains and DNS](/help/email/sending-domains-and-dns#the-records). If your root domain already has a DMARC record we do not manage, we will not stage an edit to it and the API returns `DMARC_ROOT_DOMAIN_NOT_MANAGED`. Make that change yourself. ## Dedicated sending Most senders should use shared sending, where reputation is pooled and warm from day one. A dedicated managed sending pool is worth it only at sustained high volume, where your own reputation is an asset rather than a liability. Dedicated sending is per sending domain, because sending reputation lives on the domain. Each pool is **\$35.00 per month**, one pool per sending domain, billed to the organization that owns the domain. An organization can turn it on for several of its domains, and each is billed separately. If you send for several clients on several domains, this also keeps one client's list problem from affecting the others' IPs. Turn it on from **Domains**, on the domain's page, in the **Email** section. The domain must be verified (active) first. It is recommended for domains sending roughly 100,000 or more emails a week on a steady schedule; below that, shared sending usually delivers better. Warm-up usually takes **up to about six weeks**, and the pace depends on how much you send to each mailbox provider. The domain's campaigns keep sending through shared IPs until warm-up ends, then switch automatically. Plan it well ahead of an election deadline, not during one. Dedicated IPs need steady sending afterwards to stay healthy. Turning it off stops billing at the end of the current month, with no mid-month refund, and the domain goes back to shared sending. Turning it on again later starts a new pool and a new warm-up. A domain with dedicated sending on cannot be removed until you turn it off. If the monthly renewal cannot be charged before the grace period ends, the pool is released, the domain returns to shared sending, and your organization is notified with how to turn it back on. Three conditions you may hit: `DOMAIN_NOT_ACTIVE` means the domain is not verified yet, `POOL_ALREADY_ACTIVE` means the domain already has a pool and the request did nothing, and `POOL_CAPACITY_EXHAUSTED` means the capacity cap has been reached and you should contact support. Two conditions you may hit: `POOL_ALREADY_ACTIVE` means your organization already has one and the request did nothing, and `POOL_CAPACITY_EXHAUSTED` means the capacity cap has been reached and you should contact support. ## Tracking Tracking is not optional and does not need configuring. On every send: * **Every link is rewritten** to a tracked URL on your link domain. That includes bare URLs you pasted into the text without making them links. * **An open pixel is added**, an invisible one-pixel image that loads when the message is displayed. * **A view-in-browser link** is available, which renders the message as a web page for recipients whose client mangles it. The browser version does not count as an open, though its links are still tracked. ### Opens are approximate Take open rates as a trend, not a count. Two things distort them in opposite directions, and neither is fixable by any sender: * **Apple Mail Privacy Protection loads the pixel for every message**, whether or not the recipient looked at it, which inflates opens. * **Recipients who never load images never register an open**, even after reading and acting on the message, which deflates them. The platform filters what it can identify: known privacy proxies including Apple's and Gmail's image proxy, known bots, prefetching clients, and opens that arrive implausibly fast after the send. A filtered open is **discarded**: it is not counted and does not appear in your reports. A filtered click is kept and marked as automated, so link reports can still separate machine traffic from human traffic, but it is not counted either. A human open or click counts as engagement. So does an open seen through Gmail's or Yahoo's image proxy, even though that open is not counted in your reports. Engagement updates the contact's last-engaged date on every list in your organization, which is what resets the [sunset policy](/help/email/bounces-complaints-and-suppressions#the-sunset-policy) clock. Apple's proxy and other automated opens do not count. **Clicks are the number to trust.** A click is a deliberate act that no proxy performs on the recipient's behalf. Where open rate and click rate disagree, believe the click rate, and use **click-to-open** with the same caution you would apply to any ratio with a soft denominator. ## Reporting Each campaign has one page, and that page is its report. Open it from the campaign's name or **Report** on the Campaigns dashboard. The top of the page carries the same actions as the dashboard row, anything holding the campaign back (waiting for approval, paused, warming up), and **Campaign details**: the sender, subject, preview text, lists, and schedule. Details stay open until the campaign starts sending, and the results below them appear once it does. The report opens on tiles covering **sent, delivered, opened, clicked, click-to-open, bounced, complaints, unsubscribed, and cost**, with the corresponding rates. Below them: | Section | What it shows | | - | - | | **Hourly chart** | Sends and engagement over time, which is how you see a send being throttled or a spike of complaints. | | **ISP breakdown** | Performance split by mailbox provider. Gmail behaving very differently from everyone else is the classic early warning. | | **Device breakdown** | Derived from clicks, so it reflects people who acted rather than everyone who was mailed. | | **Link clicks** | Per-link click totals, so you can see which call to action actually worked. | | **Bounce and error reasons** | Grouped by type and reason, which is where an authentication problem or a blocklisting shows up as a pattern rather than a mystery. | | **Recipients** | A per-recipient drill-down, filterable by status, for answering "did this specific person get it". | **CSV export** builds the full recipient-level file in the background and gives you a download link valid for seven days. Figures on the page are cached for 60 seconds. Test sends and seed addresses are excluded from every number, though they are still billed, because they are your traffic rather than your audience's. Seed addresses are the inboxes you list under **Email settings**, up to 25. Every campaign also goes to them, sent with the first batch, so your own team can see where it lands. A seed address that unsubscribed, bounced, or complained is not sent to. They are not part of the audience count and never fire webhooks. **Compare campaigns** puts up to four campaigns side by side, which is the supported way to evaluate a change in subject line, sender, or creative. # Compliance and link tagging Source: https://docs.politicalcomms.com/help/email/compliance-and-link-tagging CAN-SPAM footers, paid-for-by disclaimers, one-click unsubscribe, forget this address, and how donation links are tagged for WinRed and Anedot. ## What goes in every footer Two things are attached to every message automatically, from the sender identity rather than the campaign, so they cannot be forgotten on a particular send. If your template does not already include them, they are **appended for you** rather than sent without: **A physical mailing address.** CAN-SPAM requires a valid postal address in every commercial message. It lives on the sender identity. **A paid-for-by disclaimer.** Political email carries the same attribution expectations as other political communication. Set the disclaimer text on the sender identity, and mark whether the message is authorized by the candidate. If you edit a sender identity in a way that removes a required physical address or disclaimer, the identity is **paused rather than allowed to keep sending**. The write succeeds and sending stops, which is the safe direction: a paused identity is a problem you notice, while non-compliant mail is one you find out about later. Requirements vary by jurisdiction and by whether the sender is a candidate committee, a party committee, or an independent group. We supply the mechanism; confirm the exact wording with your counsel or compliance advisor. ## Unsubscribes Every message carries a working unsubscribe, in two forms: **One-click unsubscribe.** The RFC 8058 `List-Unsubscribe` headers are on every message, so the mailbox provider's own unsubscribe button works. This is now a Gmail and Yahoo bulk-sender requirement, not an optional nicety. A recipient who uses it is suppressed immediately, with no confirmation page and no chance to mail them again. **A hosted preferences page.** The footer link opens a page where the recipient can unsubscribe and give a reason. Unsubscribes are honored synchronously. There is no batch window during which a recipient who just opted out can still receive a queued message. A provider retrying a one-click POST does not produce a second unsubscribe event: the deduplication key is the message, and a recipient unsubscribes from one send exactly once. ## Where an unsubscribe applies An unsubscribe applies at the scope the recipient chose on the hosted page (the sender they heard from, or that sender's whole sending domain) or, for a one-click or mailto unsubscribe, the sender of the message they acted on. Unsubscribes exist at three levels, organization, sender, and sending domain; the organization level is written by you, never by a recipient. See [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions). ## Authentication Three mechanisms prove your mail is really yours, and all three are set up by the DNS records you publish when you add a domain: | Mechanism | What it proves | Where it comes from | | - | - | - | | **DKIM** | The message was signed by your domain and was not altered in transit. | The three DKIM records. | | **SPF** | The sending server was authorized by your domain. | The bounce host records, which is why that pair matters. | | **DMARC** | The first two line up with the domain in the From address, and what to do when they do not. | The DMARC record, or your existing policy. | Together these satisfy the bulk-sender requirements Gmail and Yahoo enforce. Your standing against each requirement is on the sender requirements scorecard; see [Campaigns and deliverability](/help/email/campaigns-and-deliverability#sender-requirements-scorecard) and [Sending domains and DNS](/help/email/sending-domains-and-dns). ## Campaign Verify for email (Gmail's Verified Sender Program) Gmail runs a program that can show a verified indicator beside messages from participating senders. Political senders generally qualify through Campaign Verify, the same authorization used for 10DLC texting. Two things to know: * **Campaign Verify accepts committee sending domains for the program from September 8, 2026.** We prepare the submission with you (eligibility from your existing Campaign Verify record, the exact sending address, and the pre-checks Google requires); the one step that has to happen in Campaign Verify's own portal is yours. * **Google publishes no automated status feed for it**, so the status shown on your sender identity is recorded by our team rather than fetched. If you are enrolled and it is not reflected, tell support. * **It is never a condition of sending.** It affects how a message may be displayed, not whether it is delivered. A sender with no Verified Sender status sends exactly as well as one with it. ## Forget this address A deletion request is different from an unsubscribe. Unsubscribing keeps the row so it can keep blocking mail; forgetting erases the address itself. Forgetting is a support-assisted operation: send the request to support with the email address and, if the person also receives texts, their phone number. Both are erased in one pass, and the two are handled in a specific order that is worth understanding: 1. **A platform-wide block is written first.** The email address goes on the platform's global unsubscribe list and the phone number on its global opt-out list, so both stay blocked permanently. This happens before anything is erased, so there is no window in which the person is both forgotten and reachable. An existing block is never removed or rewritten by this process. 2. **Then the person is erased everywhere else.** In records that must survive for accounting and reporting, such as sent messages and click records, the email address is replaced with a one-way hash and the message content is erased. In list membership and contact profiles, the email row is deleted outright and the texting contact is removed from the list. Anything still queued to send is skipped. The replacement is a one-way digest, so the address cannot be recovered from it. This is irreversible. ## Link tagging for WinRed and Anedot Campaigns that link out to a WinRed or Anedot donation page get their links tagged automatically, so the committee can attribute the gift in their own WinRed or Anedot portal. Political Comms does not track or report donation amounts: fundraising totals live in the committee's donation platform, not here. Each campaign gets a **refcode**: `e-` followed by eight characters. When a donation link points at WinRed or Anedot, we append, without ever overwriting a parameter you set yourself: | Parameter | Value | | - | - | | `refcode` | The campaign's refcode | | `source_code` | Your source code, defaulting to the refcode | | `email` | The recipient's address, so the donate form is prefilled | | `utm_source` | `email` | | `utm_medium` | The campaign's UTM medium | | `utm_campaign` | The campaign's refcode | UTM parameters are added when `append_utm` is on. If you already put a `refcode` on a link, yours wins. From there, attribution happens entirely inside WinRed or Anedot: they match the refcode, source code, and UTM parameters against the gift and report it in their own dashboard. Political Comms hands off the tagging and stops there. # Campaign Verify for email Source: https://docs.politicalcomms.com/help/email/gmail-verified-sender-program Google's Verified Sender Program through Campaign Verify: what it does, who is eligible, what we check before you submit, and the portal steps. ## What it is Google's Verified Sender Program gives a 527 committee reliable delivery to personal Gmail inboxes once its sending domain is verified through Campaign Verify and its 14-day spam rate stays under 0.3%. That is Google's own framing: consistent inbox placement at Gmail, not a visible badge on the mail itself. Being in the program is never required to send. It improves Gmail delivery for registered committees, and it does not change anything else about your sending. ## Who is eligible Your committee needs a **Verified** Campaign Verify identity request, an active sending domain, and a sender identity on that domain. The program works at the root domain, so every subdomain of a verified root benefits, which is why one identity being verified can cover its siblings on the same domain. ## What we check before you submit Submitting burns one of Campaign Verify's three attempts on the request, so the platform runs nine checks first and only shows the submit action once the blocking ones pass. | Check | What it confirms | Blocking | | - | - | - | | Campaign Verify verified | Your CV identity request is in **Verified** status | Yes | | Domain active | The sending domain is active on the platform | Yes | | Authentication | SPF and DKIM are signed by the sending domain | Yes | | Postmaster verified | The root domain is verified in Google Postmaster Tools | Yes | | Website match | The sending domain's root matches or redirects to the website on your CV identity request | Yes | | Registrar expiry | The domain's registration does not expire before your CV request does | Yes | | Root unique on platform | No other organization is submitting the same root | No | | One address per request | Your CV request does not already carry a submitted address this cycle | No | | Sending history | The identity has a recent record of sending to Gmail | No | A failed non-blocking check shows as a warning you can acknowledge; a failed blocking check keeps the submit action hidden until it is fixed. ### Organizations with several committees If your organization holds Campaign Verify verifications for more than one committee (an agency with a verification per client, for example), the sender's domain decides which verification the checks use: the one whose website is the sender's root domain, or the site that root domain redirects to. Submit the address on that committee's verification in the Campaign Verify portal. If none of your verifications lists the sender's domain, the checks say so; send from the committee's website domain, or update the website on the committee's verification. When a verification expires, only the addresses submitted on it expire. ## The exact address Campaign Verify verifies the **root domain** and then passes the **full address you submit**, subdomain included, on to Google. The root has to match or redirect to the committee website on file with your Campaign Verify identity request. The platform shows you the exact address to enter, including the subdomain, so there is nothing to retype or guess. ## Steps in the Campaign Verify portal > [!NOTE] > > Steps written from Campaign Verify's published guidance and confirmed against > the live portal after September 8, 2026. **1. Sign in** Sign in to Campaign Verify at app.campaignverify.org with the account that holds your committee's identity verification. **2. Open the verified request** Open the verification request whose status is Verified. Only a current, verified identity request can carry a sender email address. **3. Find Verified Email Senders** Find the Verified Email Senders section of that request. **4. Enter the exact address** Enter the sender address exactly as shown on the sender page in Political Comms, including the subdomain. Campaign Verify verifies the root domain and passes the full address to Gmail. **5. Submit** Submit. Campaign Verify checks the domain in under a minute and shows the result in the portal. **6. Mark it submitted** Return to the sender page and mark the address as submitted so we can watch for Gmail's confirmation. A few things to keep in mind before you submit: * You get three submission attempts per verification request, and one address change after approval. Check the address before you submit. * Approved addresses reach Gmail overnight. Gmail activates the program within one to two business days, and we confirm it from Google Postmaster Tools. * The address expires with your Campaign Verify identity verification. A new identity verification and a new address submission renew it. * Being verified is never required to send email. It improves Gmail delivery for registered committees; it does not change anything else. ## After you submit Campaign Verify forwards approved addresses to Google on a nightly feed. Google activates the program within one to two business days of that feed, and we confirm activation from Google Postmaster Tools rather than guessing from the submission alone. | Status | Meaning | | - | - | | **Not eligible** | One or more blocking checks are failing. Fix them to move forward. | | **Eligible** | Blocking checks pass, but the platform has not finished its own verification pass yet. | | **Ready to submit** | All blocking checks pass. Submitting in Campaign Verify is the next step. | | **Submitted** | The address is in Campaign Verify's queue, waiting for Google's confirmation. | | **Verified** | Google confirmed the program is active for this address's root domain. | | **Suspended** | Google paused the program for 7 days after a spam-rate breach. It re-enrolls automatically once the rate recovers. | | **Rejected** | Campaign Verify or Google rejected the submission. Check the note for why. | | **Expired** | The underlying Campaign Verify identity verification lapsed. Renew it and resubmit. | ## Where the status shows * The sender page, in its Campaign Verify for email section. * The domain's page under Email > Domains, as a chip beside each sender on the domain. * The senders list, as a badge on the identity's row. * The sender picker when building a campaign. * **Domains**, as a chip on the domain's page. * Your Campaign Verify page, listing the addresses submitted or verified under that identity request. * Over the API, as `gmail_verified_sender` on `/v1/email/senders` objects. ## Expiry and renewal The address expires when the Campaign Verify identity verification behind it expires. Verifications are valid for two-year election cycles. Requests submitted November 15, 2024 to November 14, 2026 expire January 31, 2027, and requests submitted November 15, 2026 to November 14, 2028 expire January 31, 2029, at 11:59 PM Central Time. We send a reminder 30 days before that date so a renewal, and a resubmission of the address, can happen before the program lapses. ## Suspension Google suspends the program for a domain for 7 days if its 14-day spam rate breaches the 0.3% threshold, then re-enrolls it automatically once the rate recovers. We alert your organization when the reported spam rate reaches 0.2%, ahead of Google's threshold, so there is room to act on list quality before a suspension happens. See [Google Postmaster Tools](/help/email/google-postmaster-tools#spam-rate-alerts). # Google Postmaster Tools Source: https://docs.politicalcomms.com/help/email/google-postmaster-tools 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 is usually the largest single slice of a political email list, and it is the only mailbox provider that will tell you what it thinks of your mail. Google Postmaster Tools is that channel. The platform connects your domain to it for you and shows the numbers next to everything else about the domain, so you do not have to run a separate Google account or remember to go look. ## What you have to do One thing: **publish a TXT record.** It appears in your record set on the domain's page under **Domains** alongside the DKIM and MAIL FROM records, as a `google-site-verification=` value on your **root** domain (not the sending subdomain, because Postmaster works at the organizational domain level). Everything else is automatic: **1. We register the domain** The platform's own Google account registers your domain in Postmaster Tools and asks Google for an ownership token. **2. The token appears in your record set** The Postmaster row shows no value until Google issues the token. Once it appears, publish it at your root domain. **3. We ask Google to verify** The platform re-checks with Google every 10 minutes for about five hours. Our own DNS lookup seeing the record is not enough: only Google confirming it counts as verified, because only Google can say whether Google accepted it. **4. Numbers arrive nightly** Once verified, a nightly job pulls Gmail's figures for the domain. You never need a Google account, and you never give us access to one. ## Where the numbers show up The Postmaster panel appears in two places: on the **sender identity** page for the identity's domain, and on the domain's page under **Domains** for the domain itself. It shows: | Reading | What it means | | - | - | | **Spam rate** | The share of your Gmail mail that recipients marked as spam. This is the number that matters most. | | **SPF, DKIM, DMARC** | The share of your Gmail mail that passed each authentication check. These should sit at or near 100%. Anything materially lower means some of your mail is not being signed or aligned. | | **Compliance** | Google's own bulk-sender requirement table, requirement by requirement, as Google scores it. | Two things it deliberately does not show: * **Domain and IP reputation are not displayed.** Google's older Postmaster API reported a reputation grade; the current version does not expose one at all. Rather than print a fabricated or stale grade, the panel leaves it out. Spam rate and the compliance table are the live signals. * **A missing number reads "No data yet", never 0%.** A spam rate of zero and a spam rate Google has not reported are very different results, and showing the second as the first would be the most flattering possible lie. ## Why a new sender sees nothing Google only publishes figures for a domain sending **meaningful daily volume to Gmail**. Below that floor it returns no rows at all, so a new domain, a small list, or a domain that has only sent tests will show "No data yet" for a while. There is also a built-in lag. Gmail aggregates a day's traffic well after that day ends, so the platform reads a window ending about two days back. Sending today and checking tonight will show you nothing new; that is the reporting window, not a problem with your domain. > [!NOTE] > > **None of this affects your sending.** Postmaster Tools is a reporting channel, > not a gate. A domain that never verifies, or that Google has no data for, sends > exactly as well as one with a full dashboard. If it is showing "no data", the > answer is usually to keep sending good mail and check back in a week. ## Spam rate alerts Google's published bulk-sender threshold is to keep reported spam **below 0.3%** and never reach it. The platform alerts your organization when your peak reported spam rate reaches **0.2%**, so there is room to act before Gmail does. The alert fires at most once a week per organization, because the condition takes days to move and a daily repeat of the same bad news is not useful. If it fires, the cause is nearly always list quality rather than content: an acquired list with weak consent records, a segment that has not been mailed in a year, or a cadence that got too aggressive. See [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions) and the [sunset policy](/help/email/bounces-complaints-and-suppressions#the-sunset-policy). ## When the domain is already claimed Postmaster lets exactly one Google account own a domain. If someone at your organization, or a former vendor, already registered it, the panel says **Claimed by another account** and gives you the two ways forward: 1. Ask the current owner to add our platform account as an owner of the domain in their Postmaster Tools, or 2. Ask them to delete the domain from their Postmaster Tools so we can register it. Either one unblocks it. In the meantime the domain keeps sending normally; you are only missing the reporting. ## Statuses | Status | Meaning | | - | - | | **Not connected** | Registration has not been started for this domain. | | **Add the TXT record** | Google issued a token. Publish it at your root domain. | | **Verifying** | The record is published and we are waiting on Google to confirm it. | | **Verified** | Confirmed. Gmail's figures are flowing, subject to the volume floor above. | | **Claimed by another account** | Another Google account owns the domain. See above. | | **Verification failed** | Google did not confirm within the retry window. **Try again** restarts it. | This is also where a verified [Campaign Verify for email](/help/email/gmail-verified-sender-program) status is confirmed: Google exposes no program field over its API, so staff read it from this same Postmaster compliance view for the domain. # Lists and address screening Source: https://docs.politicalcomms.com/help/email/lists-and-validation Importing email contacts, recording consent, what is removed at import, send-time address screening, acquired lists, segments, and the sunset policy for unengaged contacts. ## Importing a list Upload a file or sync from WinRed or Anedot. A list has one of four sources: | Source | Where it comes from | | - | - | | `uploaded` | A file you imported | | `segmented` | A segment built from contacts already in the platform | | `winred` | Synced from WinRed | | `anedot` | Synced from Anedot | A list is `processing` while the import runs and `ready` when it is done. You cannot send to a list that is not `ready`; the API returns `409 EMAIL_LIST_NOT_READY`. ### Where the uploader lives Every file you upload goes through one page: **Assets > File Uploads**. Choose who owns the upload under **Upload to**, then drop the file. A CSV or TXT file becomes a list; there is no upload type to pick. On the setup card, choose **Audience** under **What is this?**, then choose the email column (pre-filled from the file) and, if the file also has phone numbers, the phone column. The file you upload *is* the list, named after the file unless you rename it, so there is no list to create first. Every other column is matched for you: the standard fields a header names, and every other column as a merge field named from its header. Skip a column you do not want or rename a merge field. The emails belong to the whole organization the list is uploaded to. The card shows one checkbox, **This list was purchased or rented**, which is unchecked by default. Check it for a purchased or rented list; it is then sent more gradually. **One list holds phone numbers and emails.** A file with both columns becomes one list with both, and every list is on one page, **Assets > Lists**. A list card shows its phone numbers and, when it has emails, an Emails section with the total, sendable, unsubscribed, and bounced counts and the quality grade; the list's page shows both. Deleting a list removes its phone numbers and its emails. Two lists can share a name. A campaign combines lists by attaching several of them, exactly as a texting project attaches lists, so there is no reason to import two files into one list. The old **Email > Lists** links still work and open the same list on **Assets > Lists**, so existing bookmarks are fine. ### Importing over the API `POST /v1/contact-lists/import` is the one list import, for phone numbers, emails, or both. Give it an HTTPS URL to a CSV you host, a `list_name`, and the column that holds the email address; it fetches, checks, and commits the file as a new list. ```json theme={null} { "source_url": "https://files.example.com/exports/august-donors.csv", "list_name": "August donors", "email_column": "Email Address", "consent": { "source": "donation_form", "note": "Donate page opt-in checkbox" } } ``` Add `phone_column` to bring in phone numbers in the same list. `email_domain_id` scopes the emails to one sending domain; omitting it leaves the list available to every campaign. `acquired` is optional and defaults to `false`; `true` declares a purchased or rented list, which is sent more gradually. `consent` is optional. It is allowed only for an audience import with an `email_column`; sent with any other combination it returns `400`. Omit it and no consent record is stored. When you send it, `source` is one of `donation_form`, `petition`, `signup_form`, `event`, `purchased`, `rented`, or `other`, and `note` is optional text up to 1000 characters. Unknown keys inside `consent` or `merge_tags` return `400`; unknown top-level fields in the request body are ignored. Name the email column yourself: the API does not guess it. A column that is not in the file returns `400 VALIDATION_ERROR` with `details.headers` listing the headers it read, so the retry can name the right one. Columns other than the ones you chose become merge fields automatically. If you send `merge_tags`, phone numbers map only the columns you name, while emails map the named columns and every other column by its default name. Custom field names for emails must start with a lowercase letter and use only lowercase letters, digits, and underscores, at most 64 characters. Every refusal happens before anything is stored. The response is `202` with the list's `list_id` and an `email_import`. The import runs in the background; poll `GET /v1/email/lists/{list_id}` (the same id) until `status` is `ready` or `failed`, with its counts and `removed_at_upload`. `POST /v1/email/lists/import` was removed. To move a call over: send `name` as `list_name`, the `mapping` entry whose value is `email` as `email_column`, and the other `mapping` entries as `merge_tags`; `email_domain_id` and `acquired` carry over unchanged, and `consent` is optional. See [Import List](/api-reference/introduction) for every field. ### What import removes and holds back Every import, from the uploader or the API, applies the same checks: * **Malformed addresses** are rejected and reported. This includes Gmail addresses Gmail could never have issued: a Gmail username is 6 to 30 letters, digits and dots, so `abc@gmail.com` or `jane_doe@gmail.com` is removed as malformed. * **Likely typos in the domain** are skipped, not corrected. A row whose domain is a known misspelling of a major mailbox provider, such as `gmial.com`, is counted in the import summary as "Likely typo in the domain". Fix the address in your file and import it again. * **Role addresses** such as `info@`, `admin@`, and `sales@` are always removed. They reach a shared inbox rather than a person and complain at a far higher rate than personal addresses, so there is no option to keep them. * **Disposable addresses** from throwaway-mailbox services are removed. The list we check covers several thousand such domains. * **Yahoo-run mailboxes** are removed from every list: Yahoo, AOL, AT\&T, Verizon, Cox, Frontier and the other domains Yahoo hosts, detected by the domain's mail servers so a provider that moves to Yahoo is covered. Recipients at those providers report political email as spam many times more often than anyone else, and one shared sending reputation carries every customer. The import summary counts them; the same rule applies to contacts added over the API and to donor-platform syncs. There is no option to keep them. * **High-complaint providers** are removed too. When the mailboxes at one provider report our email as spam at an unusually high rate, we remove that provider's addresses from every upload and never send to them. Today that is windstream.net. Existing lists were cleaned, sends already queued to those addresses are skipped, and the list's "removed at upload" breakdown shows them. There is no option to keep them. Everything removed before it joined the list is counted on the list itself: the lists page shows "removed at upload" with the breakdown by reason (Yahoo/AOL first), and the list's detail page has the same figure as a tile. Over the API the list object carries it as `removed_at_upload`. * **Addresses that cannot receive mail**, such as a domain with no mail server, and addresses that already bounced or complained on this platform, are removed, as are duplicate rows in the same file. * **Addresses currently held by screening** are imported but held back, and the import summary reports them as `screened`. See [Address screening at send time](#address-screening-at-send-time). Unsubscribes, bounces, and complaints stay in force: re-importing a file does not bring back anyone who unsubscribed, bounced, or complained. ### Donor syncs and segments Two of the four sources are worth calling out because they are not files: **WinRed and Anedot syncs** build an email list from your donor records automatically, so people who give keep arriving on the list without anyone exporting a CSV. Consent comes from the donation form itself, which is the cleanest provenance an email list can have. Create one from **Assets > Lists > New Dynamic List**; a feed is one list, holding its donors' phone numbers and emails, and the list's page shows the connection details and settings. The same picker offers **Recent openers** and **Recent clickers**: lists of everyone who opened or clicked a campaign in a window you choose, refreshed nightly. A refund can park a donor off the list, and a later gift brings them back; retention works the same way. These lists are managed through the connection rather than deleted, so the Delete action is not offered on them. **Segments** are lists built from contacts already in the platform, using rules rather than a file. Engagement rules are the useful ones: everyone who opened in the last 30 days, everyone who clicked a particular campaign, everyone who has not engaged in 90 days. Giving rules read your synced donations: total given, recurring, gave recently, number of gifts, any single gift above an amount, and the donation source (refcode, source code, UTM parameters, page name). Giving is counted net of refunds: a refunded or charged-back gift does not count toward a total or a gift count, and a gift that arrives through both a webhook and a scheduled report is counted once. A random split rule takes a stable slice of a list, so two segments with 0-50 and 50-100 never overlap; that is how you run two campaigns against halves of one list. Because a segment is defined by its rules, it reflects the current state of your contacts each time you use it rather than a snapshot from the day you built it, and it can refresh nightly. ## Consent attestation Every list requires a consent attestation when you create it: a short statement of **how** the people on it agreed to hear from you, plus an optional note. This is not a checkbox to click past. It is the record you will want if a complaint is ever escalated, and the honest answer determines what happens next. A list from your own donate-page opt-in behaves differently from a list you bought. ## Acquired lists If a list came from anywhere other than your own sign-up flow, set its `acquired` field. Doing so is in your interest, not against it: an acquired list that is not declared is far more likely to trip a deliverability breaker mid-send and pause your campaign. An acquired list is not blocked from sending. Declaring it has one consequence: **warm-up runs on half steps.** The daily ceiling is halved at every stage of the [warm-up ramp](/help/email/campaigns-and-deliverability#warm-up), so a list with less certain provenance reaches mailbox providers more slowly. ## List quality score When an import finishes, the list gets a quality grade: **Good**, **Fair** or **Bad**. It is built from what the import measured and from our own history with the addresses: | Signal | Fair at | Bad at | | - | - | - | | Addresses removed as undeliverable (no mail server, typo, bad syntax, throwaway) | 2% | 5% | | Addresses that already bounced or complained on this platform | 1% | 3% | | Of the addresses mailed here at least twice before, the share that never opened or clicked | 70% | 90% | | Role mailboxes such as info@ or office@ | 20% | never | | Addresses with long number strings | 10% | 25% | | One organization domain holding the list | 20% | 50% | The grade is the worst of these. Lists synced from WinRed or Anedot get the same checks; they have no upload step, so they are graded on their addresses and history alone, and re-graded weekly as new donors sync in. Lists under 500 rows are not graded, and segments are not scored, since each is built from graded lists. * **Good**: sends normally. * **Fair**: sends at the slower pace used for acquired lists while the domain is warming up, and the campaign checklist shows a warning. * **Bad**: sends at the slower pace used for acquired lists, with a warning on the campaign checklist. Nothing to approve. The list page shows the grade and each signal. Sending first to people who signed up or engaged recently is the fastest way to protect a sending domain when a list scores below Good. One more figure is shown without affecting the grade: the share of sendable addresses **this platform has never delivered to**. Nothing at upload can tell whether such a mailbox still exists; only a delivery can, and on a list of appended or purchased addresses that share is where the bounces live. Those addresses send after every address with a delivery behind it, and the bounce breaker judges them on their own (see [campaigns and deliverability](/help/email/campaigns-and-deliverability#deliverability-breakers)). The campaign checklist repeats the count when a quarter or more of a selected list is unproven. ## Address screening at send time There is no separate cleaning step and no charge for one. Every campaign email is screened as it is sent, using the strictest setting of the mail provider's automatic validation. An address it rates as likely undeliverable is not sent to. What happens to a screened address: * The message is recorded with status `suppressed` and reason `auto_validation`. * It is **not counted as a bounce**, so it does not count toward your bounce rate or the [deliverability breakers](/help/email/campaigns-and-deliverability#deliverability-breakers), and it does not fire the `email.bounced` webhook. * The address is **held out of all sends on the platform for 90 days**, for every organization. After 90 days it is checked again on its next send. * The campaign report shows the total as **Screened as invalid**. * You are billed the normal per-recipient email rate for it, the same as a bounce, because the message was handed to the mail provider. Screening is a safeguard, not a guarantee. It does not confirm that a mailbox exists at the large providers, so an address that has never been seen before and is dead can still bounce once. A permanent bounce from a bad address stops it being mailed for good; see [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions). A campaign sends to every subscribed contact on its lists, except addresses that unsubscribed, bounced, or complained, and anyone on the campaign's suppression lists. There is no recipient policy to choose. ### Downloading a list **Download** on the list page saves the file straight away, the same as a texting contact list. Every list offers two files, and an uploaded list a third: * **Current list**: the columns you imported, named as you mapped them and in the order they arrived, followed by `email`, `status`, and `status_reason`, showing each contact as it stands now. A contact the platform will no longer mail, for example an address mailbox providers reported as not existing, reads `suppressed` with the reason. * **Unmailed addresses**: the sendable contacts this platform has never delivered to, in the same columns. This is the file to run through an address verification service when a campaign pauses on its unproven tail; upload the result as a new list and edit the campaign's list. * **Original upload**: the file exactly as you uploaded it. A list synced from a donation platform has no uploaded file, so **Download** saves the current list. ## Contact statuses | Status | Meaning | | - | - | | `subscribed` | Sendable. | | `unsubscribed` | Opted out. Never sent to again. | | `bounced` | Permanently bounced. | | `complained` | Marked a message as spam. Never sent to again. | | `invalid` | Not a usable address. | | `sunset` | Dropped by the sunset policy. | | `suppressed` | In downloads only: still on the list, but unsubscribed, bounced, or complained elsewhere in your account, so it is never sent to. `status_reason` says why. | Only `subscribed` contacts are mailed. The rest are excluded automatically, and none of them can be restored by re-importing the same file. ## Removing contacts Removing an address **unsubscribes it rather than deleting the row**, because the row carries the bounce and complaint history that keeps it unmailed after your next import. To erase an address entirely, use [forget this address](/help/email/compliance-and-link-tagging#forget-this-address). ## Unsubscribes, bounces, and the sunset policy Unsubscribes, bounces, complaints, and the 90-day hold and 180-day sunset all work the same way regardless of which list an address is on, so they have their own page: [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions). The short version: an address that bounces permanently or complains is never mailed again, automatically, unsubscribes are honored immediately, and contacts who have not engaged in 90 days stop being mailed before they can damage your reputation. Opening or clicking one of your emails counts as engagement and starts that clock over. ## Bulk contact upsert over the API `POST /v1/email/lists/{id}/contacts` takes up to 1,000 contacts per call and returns a per-row outcome, so one bad address does not cost you the batch: ```json theme={null} { "written": 2, "accepted": 2, "rejected": 1, "duplicates": 1, "results": [ { "index": 0, "email": "a@example.com", "status": "accepted", "reason": null }, { "index": 1, "email": "nope", "status": "rejected", "reason": "invalid_email" }, { "index": 2, "email": "a@example.com", "status": "duplicate", "reason": "duplicate_in_request" } ] } ``` Fix and resend only the rows that came back `rejected`. # Email Overview Source: https://docs.politicalcomms.com/help/email/overview What the Political Comms email product does, what it deliberately does not do, and how sending gets set up. ## What it does Email sits alongside texting in the same account, on the same wallet, with the same organizations, permissions, and reporting. You get: * **Sending domains.** Prove a domain you own by publishing DNS records, then send from it. * **Sender identities.** A From address on a verified domain, carrying the physical mailing address and paid-for-by disclaimer that go in every footer. * **Lists.** Uploaded, segmented, or synced from WinRed and Anedot, each with a recorded consent attestation. One list holds phone numbers and emails, so a file with both columns is one list on **Assets > Lists** that both texting and email can use. Every campaign email is screened at send time, at no extra charge, and addresses likely to be undeliverable are not sent to. * **Unsubscribes and bounces.** Compliance records held at the organization, sender identity, or sending domain, applied automatically to every send. * **Campaigns.** Compose, test, schedule, send, and report, with warm-up limits and deliverability breakers applied for you. * **Templates, drafted for you if you want.** A reusable design library, plus [Draft with Lincoln](/help/email/campaigns-and-deliverability#draft-with-lincoln): describe the email and the platform's AI agent writes the design, \$3.00 per draft, charged only when one comes back. * **Link tagging.** Donation links to WinRed and Anedot are tagged with a refcode, source code, and UTM parameters, so the committee can attribute the gift in their own portal. ## What it deliberately does not do Knowing the boundaries up front saves a wasted afternoon: * **There is no inbox.** We do not receive your replies. They go to the `reply_to` address you configure, in whatever mailbox you already use, and there is no inbound email webhook. The only mail the platform receives itself is unsubscribe-by-email requests and DMARC reports. * **There is no A/B testing.** One campaign is one message to one audience. * **We never write your DNS.** Every record is published by you, in your own zone. See [Sending domains and DNS](/help/email/sending-domains-and-dns). * **There is no open-tracking webhook.** Open rates appear in reports, but `email.opened` is not an event you can subscribe to: a tracking pixel is approximate and, at campaign volume, would be by far the noisiest event we could send. ## How setup goes **1. Add a sending domain** Register the domain and publish the DNS records we generate. Verification is usually minutes once the records propagate. **2. Create a sender identity** Pick the From address and name, and fill in the physical mailing address and disclaimer. An identity missing either is paused rather than allowed to send non-compliant mail. **3. Build a list** Import contacts. If the list was purchased or rented rather than collected by you, say so: acquired lists warm up at half the normal daily ceiling. **4. Send a test, then schedule** Test sends are real messages to addresses you name, with **\[TEST]** in the subject and sample personalization, and every campaign requires one before it can be submitted or scheduled. After a campaign has gone out, the same dialog can send the final email instead, for someone the list missed. In the builder, choose **Save and continue**, send the test from the campaign page, then choose **Start** on the campaign page or the Campaigns dashboard. Start begins right away by default, or you can pick a later time. Only the first step needs someone with DNS access; everything after it happens in the app. The one thing to plan ahead for is **warm-up**. A brand new domain starts at 500 messages a day and climbs from there, so a large send tied to a deadline means starting the domain well before the deadline, not the week of. See [Campaigns and deliverability](/help/email/campaigns-and-deliverability#warm-up). ## What it costs Email sending is \*\*$3.00 per 1,000 emails** ($0.003 each), lower with volume. Address screening at send time is included. A Lincoln email draft is **$3.00**, charged only when a draft comes back ready. The optional dedicated IP pool add-on is **$35.00 per month per sending domain**. Sending domains, sender identities, and hosted unsubscribe pages are free. Full-service email, where our team sets up your sending domain and builds and sends every campaign, is **$0.01 per email** plus a **$1,000 one-time setup**. There is no monthly fee. Charges appear in your ledger under the **Email** family, alongside your texting usage on the same wallet, so there is one balance and one invoice rather than two. Lincoln drafts are billed under the **AI** family, since that is what they are. **Sub-organization charges roll up to the parent.** When a sub-organization sends, every organization above it in the hierarchy is charged at its own price, exactly as texting works today. A funded sub-organization is still blocked if an organization above it cannot cover its share, so fund the organization that actually ran short. See [Billing](/help/billing). An address held back by [send-time screening](/help/email/lists-and-validation#address-screening-at-send-time) is billed at the same per-recipient rate, the same as a bounce, because the message was handed to the mail provider. Test sends and seed addresses are real sends and are billed at the same per-recipient rate. Seed addresses are the inboxes you list under **Email settings** (up to 25): every campaign also goes to them, with its first batch, so you can see where your mail lands. A seed address that unsubscribed, bounced, or complained is not sent to. They are excluded from campaign statistics and never fire webhooks, because they are our traffic rather than your audience's. ## Over the API Everything above is available programmatically under `/v1/email`: domains, senders, lists, unsubscribes and bounces (`/v1/email/suppressions`), campaigns, and templates. Lists are imported with `POST /v1/contact-lists/import`, the one import for phone numbers and emails. Five outbound webhook events cover the results: `email.delivered`, `email.bounced`, `email.complained`, `email.unsubscribed`, and `email.clicked`. Request and response shapes, authentication, and error codes are in the [API reference](/api-reference/introduction). These help pages cover the product; the reference covers the contract. ## Where to go next > [card] [Sending domains and DNS](/help/email/sending-domains-and-dns) > > The records to publish and how verification is confirmed. > [card] [Lists and address screening](/help/email/lists-and-validation) > > Importing, consent, and send-time screening. > [card] [Campaigns and deliverability](/help/email/campaigns-and-deliverability) > > Sender identities, the checklist, warm-up, tracking, and reporting. > [card] [Bounces, complaints, and unsubscribes](/help/email/bounces-complaints-and-suppressions) > > What happens to an address that bounces, complains, or opts out. > [card] [Compliance and link tagging](/help/email/compliance-and-link-tagging) > > Footers, unsubscribes, and tagging donation links for WinRed and Anedot. > [card] [Google Postmaster Tools](/help/email/google-postmaster-tools) > > Gmail's own view of your sending, and why new senders see no data. > [card] [Campaign Verify for email](/help/email/gmail-verified-sender-program) > > Reliable Gmail inbox delivery for verified 527 committees, and the Campaign Verify steps to get there. # Sending Domains and DNS Source: https://docs.politicalcomms.com/help/email/sending-domains-and-dns Adding a domain, the two ways to publish its email DNS records, how each one is confirmed, and drift detection. Before you can send a single email you have to prove you own the domain you want to send from. That proof is a set of DNS records you publish in your own zone. This page is the whole of it: what to add, where, and how to tell when it worked. ## Two ways to publish We never write records in your zone, and we never ask for your registrar credentials. Your DNS is the control plane for your entire online presence, and handing a vendor write access to it is a bad trade. There are two ways to get the records in place without doing that: * **Nameserver records, for a subdomain.** When you send from a subdomain such as `mail.candidate.com`, the dialog offers this first. Add the nameserver records once, at your DNS provider, and we handle every record for that host, now and when keys rotate. Your root domain, your website and your mailboxes stay exactly where they are. `_dmarc.` and the Postmaster record live on your root, so those stay yours to add; each is marked required or optional beside it. * **Adding each record yourself.** A root domain always works this way, because moving a root's nameservers would move your website and mail with it. On a subdomain, choose **I would rather add the records myself** to see the same table. Both paths are confirmed the same way, and this is the one part of setup that needs someone with access to your DNS provider. Everything after it happens in the app. ## Adding a domain Every domain is added on the **Domains** page in the sidebar, which has one row per root domain showing its App, Tracking and Email state and what to do next. Open a domain to see each host's DNS records and actions. Click **Add domain** and you type your root domain **once**: **1. Enter your root domain** `candidate.com`, not a subdomain. This is the organizational domain everything else hangs off. A pasted `www.candidate.com` is read as `candidate.com`: `www` is your website's address, and mail is sent as `name@candidate.com`, never `name@www.candidate.com`. **2. Pick what it is for** Tick any combination of the three uses. **Email** is the sending domain. **Link tracking** is the host your click and unsubscribe links use. **App** is a branded dashboard hostname. Most people adding email want email and link tracking together, so the links in your mail carry your domain rather than ours. **3. Accept or edit the subdomains** Each use gets a hostname, prefilled and editable: `app.` for the dashboard, `links.` for tracking, and the root itself for email, since that is the domain your From addresses end in. Change the email host to `mail.` or another subdomain if you want campaign mail kept apart from everyday mail. `www` is refused for app and tracking hosts. **4. Publish the records** One table lists every record for every use you picked. For a subdomain sending host that means its nameserver records, or every record if you choose to add them yourself. Add them at your DNS provider and the page tracks them as they land. Before it generates anything the dialog runs a **pre-flight check** against the host you are creating. It names your DNS provider, warns about a conflicting SPF record, and refuses to continue while there is a hard conflict such as a CNAME on an apex you also need other records at. This is much cheaper to find out now than after a failed send. ### Use a subdomain Send from `mail.candidate.com`, not from `candidate.com` itself. A subdomain keeps campaign sending reputation separate from the domain your staff email from, so a bad list cannot damage your day-to-day mail. It is the default the dialog suggests, and it is the right one for almost everyone. ## The records If you added nameserver records, we publish the ones on your sending domain and only the DMARC and Postmaster rows below are yours. Otherwise publish all of them. There are seven, or eight if we generate a DMARC record for you. | Record | Type | Host | Value | | - | - | - | - | | DKIM key 1 | `CNAME` | `._domainkey.` | A signing host on our sending infrastructure | | DKIM key 2 | `CNAME` | `._domainkey.` | A signing host on our sending infrastructure | | DKIM key 3 | `CNAME` | `._domainkey.` | A signing host on our sending infrastructure | | Bounce host | `MX` | `bounce.` | Our feedback host, priority `10` | | Bounce SPF | `TXT` | `bounce.` | An SPF record authorizing our sending infrastructure | | DMARC | `TXT` | `_dmarc.` | `v=DMARC1; p=none; adkim=r; aspf=r` with a reporting address | | Domain verification | `TXT` | `_sender-verification.` | `sender-verification=` followed by a value unique to your organization | | Postmaster ownership | `TXT` | `` | `google-site-verification=...` | Seven things worth knowing about that table: * **The Host column shows each name relative to your domain**, with the domain greyed out after it, and the copy button copies only that part: `_sender-verification.mail`, or `@` for a record on the domain itself. That is what nearly every DNS editor's Host field wants, because it appends your domain to whatever you type. If the pre-flight recognizes a provider that wants the full name instead, the copy button gives you the full name. * **The domain verification record proves your organization controls the domain.** The value is unique to your organization, so it is the part nobody else can publish for you. Publish it even if the other records already show as verified. The domain stays **Verifying** until we see it. * **The bounce host is always `bounce.` under your sending domain.** For `mail.candidate.com` it is `bounce.mail.candidate.com`. That pair of records is what gives you SPF **alignment**: DKIM alone will authenticate your mail, but publishing both is what satisfies the bulk-sender requirements at Gmail and Yahoo. * **The DMARC record is omitted entirely if your root domain already publishes one.** We will not ask you to add a second `_dmarc` record, because two of them is a permanent error that breaks the policy you already have. Your existing policy is inherited and satisfies alignment on its own. See [DMARC progression](/help/email/campaigns-and-deliverability#dmarc) for moving an existing policy forward. * **The DMARC record includes a reporting address.** Mailbox providers send their aggregate reports there, and the reports are what fill the DMARC page and let the policy move forward. If you set up your domain before the record carried one, add the reporting address shown in the domain's DMARC panel to your DMARC record as a `rua=mailto:` tag; reports start arriving once it is published. * **DMARC and Postmaster records go on the ROOT domain**, not the sending subdomain. Everything else goes on the sending subdomain. This is the single most common place to get it wrong. * **The Postmaster record has no value at first.** It stays blank until Google issues a token, usually within minutes. Publish it once the value appears. It is optional: nothing about your sending depends on it, and it only unlocks reporting. See [Google Postmaster Tools](/help/email/google-postmaster-tools). ## How each record is confirmed A record is not done because we saw it once. Seeing a record in DNS proves it resolves; it does not prove the service that needs it has accepted it. So every record has a **confirming signal** beyond our own lookup, and the capability it belongs to turns on only when that signal fires: | Record | Confirmed by | | - | - | | The three DKIM CNAMEs | Our sending infrastructure reporting DKIM as verified | | The bounce MX and SPF pair | Our sending infrastructure reporting the bounce domain as verified | | DMARC | Our own DNS lookup, since nothing else consumes it | | Domain verification | Our own DNS lookup, since the value is specific to your organization | | Postmaster ownership | Google confirming the token | The practical effect: a DKIM record that resolves perfectly but has not yet been accepted upstream shows as **Verifying**, not Active. That is not a bug, and the usual fix is to wait a few minutes. ### Per-record status Each row in the table carries its own state, so you can see exactly which record is holding things up rather than staring at one domain-level "pending": | State | Meaning | | - | - | | **Not started** | Nothing seen yet. | | **Pending** | We are looking and have not found it. | | **Verifying** | Found in DNS, waiting on the confirming signal. | | **Active** | Confirmed. Done. | | **Changed** | Was working, and no longer matches. See drift below. | | **Failed** | Verification was abandoned. | ### Verify now **Verify now** on the domain's row re-checks immediately rather than waiting for the next scheduled poll. It works in **every** state, which is the useful part: on a pending domain it pushes verification forward, and on an active domain it re-checks a record that may have been removed, so a broken record surfaces on demand instead of silently breaking your links. Use it after publishing records rather than refreshing the page repeatedly. If you hit it many times in a few minutes you may be rate limited; wait a moment and try again. ## Drift detection DNS records get deleted. A zone gets migrated, a provider gets changed, someone tidying up removes a CNAME they did not recognize. Without detection, the first you would hear of it is a campaign that stopped authenticating. Active domains are re-checked on a schedule, and a record that no longer matches is flagged as **Changed**, with its capability downgraded until it is fixed. Drift is declared in two cases, deliberately not one: * **Immediately**, when your zone is serving a **different value**. Someone edited the record, which is not ambiguous. * **On the second consecutive miss**, when the record is simply not found. A single lookup failure is usually a resolver hiccup or mid-propagation, not a deleted record, and flapping a healthy domain to broken and back helps nobody. The counter resets the moment the record is seen again. ## If a domain's reputation is flagged Pre-flight warns when reputation services flag a domain. It is a warning, never a block: you can still add the domain. Mail and links on a flagged domain are more likely to be filtered, so check the site for compromised or unwanted content, ask for a review, or choose another domain. You can look a domain up yourself at [Cisco Talos](https://talosintelligence.com/reputation_center/). ## Bare domain redirect A domain bought here can send visitors of its bare name, such as `candidate.com`, to one `https://` address: open **Domains**, open the domain, then use **Bare domain**. Setup takes about 20 minutes. With no address set, nothing is served there and no record is written. Links stay on their subdomain either way, and a domain you manage yourself is not affected. ## When verification stalls In rough order of how often each one turns out to be the cause: 1. **The record went in the wrong zone.** Added at the root when it belonged on the sending subdomain, or the reverse. DMARC and Postmaster go on the root; DKIM and the bounce pair go on the sending subdomain. 2. **The registrar appended the domain to an already-complete host name**, producing `x._domainkey.mail.candidate.com.candidate.com`. Many DNS UIs add the zone for you. The Host copy button already gives you only the part before your domain; if you typed the full name instead, replace it. 3. **A proxy is on.** A record set to "proxied" rather than "DNS only" is rewritten in the answer, so what we see is not what you published. 4. **The nameserver records are incomplete.** Add every nameserver shown, at the sending subdomain, as `NS` records. A nameserver record on the root domain moves the wrong thing. 5. **It has not propagated yet.** Usually minutes, occasionally longer if the old record had a long TTL. ## Domain statuses | Status | Meaning | | - | - | | **Pending records** | Records generated; publish them. | | **Verifying** | Records found, waiting on confirming signals. | | **Active** | Confirmed. The domain can carry sender identities and send. | | **Failed** | Verification was abandoned. Delete the domain and re-add it to start over. | | **Suspended** | Sending has been stopped on this domain. Contact support. | ## Using a domain that already has email You can send from your main domain or from a subdomain, including a domain that already has mailboxes (Google Workspace, Microsoft 365) or is already set up for sending somewhere else. * **Your existing email is not affected.** Nothing on this page changes where the domain's own mail is delivered, and none of it changes the SPF record you already publish. Every record we ask for sits on a subdomain of your sending domain (`bounce.`, `_sender-verification.`, and the DKIM hosts), apart from the optional DMARC and Postmaster records on the root. * **A subdomain is still the usual recommendation.** `mail.candidate.com` keeps campaign sending reputation separate from the domain your staff email from. * **An existing bounce record is recognized.** If the bounce record already exists and already authorizes this platform, it is reported as already in place and you have nothing to change. ## Sharing a domain More than one organization can send from the same domain, for example an agency and its client. Each organization publishes its own domain verification record at the same host, and a domain can hold several of them side by side. Your organization can send only once its own record is seen, so one organization verifying a domain never verifies it for another. ## Deleting a domain A domain with live sender identities on it cannot be deleted; the request returns `409 CONFLICT`. Remove or move the identities first. This is deliberate: deleting the domain out from under an active identity would break sending mid-campaign rather than at the moment you asked for it. Removing a domain stops your organization's campaigns from using it. It never changes your DNS or your mailboxes, and it never removes sending setup that another organization on the same domain still relies on. Your domain verification record can be deleted once the domain is removed. Leave the DKIM and bounce records in place if anyone else sends from this domain: they are shared, and deleting them stops that sending too. ## Over the API Domains are read-only on the API: you add one in the dashboard under **Domains**; open the domain to see the DNS records to publish. Publish them, then poll the domain until `status` is `active`. ```bash theme={null} curl https://api.politicalcomms.com/v1/email/domains/{id} \ -H "X-API-Key: pc_live_..." ``` The response carries `dns_records` and `status`. Full response shapes are in the [API reference](/api-reference/introduction). ## What comes next Once the domain is active, create a [sender identity](/help/email/campaigns-and-deliverability#sender-identities) on it. A domain by itself cannot send; the identity is the From address, and it carries the physical address and disclaimer that go in every footer. # Getting Started Source: https://docs.politicalcomms.com/help/getting-started What the platform does, how 10DLC works, what you need to register, and how fast you can launch your first campaign. ## What is this platform and how does it work? This is a peer-to-peer (P2P) texting platform designed for political campaigns, nonprofits, and organizations. It enables you to send individual text messages to large groups while maintaining authentic two-way conversations. Unlike automated bulk messaging, each message is sent with human oversight, allowing for personalized engagement and real-time data collection. ## How quickly can I get started with my first campaign? Most organizations can launch their first campaign within 2 to 3 business days. Brand registration is instant, Campaign Verify typically completes in \~2 hours on business days, and campaign approval takes 2 business days (faster if expedited). Once approved, you can create and launch campaigns immediately. ## What is 10DLC registration and why do I need it? 10DLC (10-Digit Long Code) registration is required by mobile carriers to send high-volume text messages. Each candidate or campaign needs its own brand registered with The Campaign Registry. Consulting firms managing multiple candidates will register a separate brand for each client. Political organizations must also obtain a Campaign Verify token (\$95 per candidate) to prove their identity and prevent impersonation. The process per brand: 1. Setup Brand 2. Vet with Campaign Verify 3. Create Campaign 4. Add Phone Number 5. Start Sending ## What information do I need to register my organization? You'll need: 1. Your legal organization name 2. EIN/Tax ID number 3. Physical business address 4. FEC or state election filing records 5. Campaign Verify token 6. Active website with privacy policy and terms 7. Sample message scripts Political committees registered with the FEC or state election authorities are eligible for expedited verification. ## Do I have to finish account setup before I can send? Not immediately. New organizations get a **14-day grace window** to complete two required steps at `/onboarding`: the business profile (legal name, EIN, address, and related details) and funding (a saved payment method, a credit limit, or funds added at any point; once satisfied it stays satisfied even if the balance is spent down). During the window, and for anything already set up, everything works normally. After the window, if either step is still incomplete, the platform blocks creating new brands, campaigns, phone numbers, email domains, and projects until you finish onboarding. Nothing already running is affected: existing sends, schedules, and conversations keep going. See [Step 1: Account Setup](/onboarding/account-setup) for the full detail, including how the business profile prefills the 10DLC brand and toll-free verification forms. ## Can I test the platform before committing? Yes. Once your account is set up, you can test your campaigns internally before sending to your full contact list. Create a test project, add your team members' phone numbers, and send test messages to verify everything works correctly. Testing is included with your account at no additional cost. ## Where do I go next? > [card] [Ready to set up?](/onboarding/overview) > > The 5-step onboarding guide walks you through account setup, 10DLC registration, contact upload, project creation, and monitoring. # Organizations and memberships Source: https://docs.politicalcomms.com/help/organizations-and-memberships Belong to more than one organization, switch between them, invite existing accounts, and manage ownership. ## One login, many organizations Your account is not tied to a single organization. The same login can belong to several: a consultant working with two campaigns, a reseller's staff member helping a client organization, or someone who was invited to a second organization after they were already active in their first. Each organization you belong to is a separate **membership** with its own role and its own brand access. Your permissions in one organization come only from your membership there. Being an owner in one organization never gives you elevated access in another; each membership stands on its own. If you only ever use one organization, nothing here changes for you. Existing accounts keep their current organization as their default and only organization until someone invites them elsewhere. ## Switching organizations If you belong to more than one organization, the account menu in the top right, under your name and email, lists them. Pick one to reload the app in that organization. Everything on screen after you switch, projects, contacts, billing, branding, and users, belongs to the organization you switched to. The dashboard never blends data from two organizations at once. The platform remembers your last-used organization per device sign-in, so the next time you log in on that device, you land back where you left off. ## My Organizations Your Profile page has a **My Organizations** section (`/profile#organizations`) that lists every membership you hold: * A role badge for each organization. * **Current** marks the organization you're viewing right now. * **Default** marks your home organization: where you land when you sign in for the first time on a device, and the one you can't leave. * A **Make default** button on every other organization, to move that marker. * A **Switch** button to jump to that organization directly from the list. * A **Leave** action for memberships you no longer need. ### Leaving an organization Leaving removes your membership and access to that organization. Owners can leave too; the organization simply has no owner until one is assigned. One situation stops you, with a plain explanation instead of a silent failure: it's your default organization. Click **Make default** on a different organization first, then leave. ## Adding existing accounts On the Users page, anyone with the **Manage members** permission can add people to the organization in two ways. **Invite existing user** is for someone who already has a Political Comms login somewhere else on the platform. Enter their email and pick a role. They're added right away, with nothing to accept: they get an email and an in-app notification, and the next time they sign in, your organization is in their organization switcher. If they don't want it, they can leave it from their Profile page. You can also just create a new user the normal way. If the email you enter already has an account anywhere on the platform, that account is added to your organization the same way, instead of the signup failing with an "email already in use" error. The password you typed is not applied to their existing account: they keep signing in with their own password, or use **Forgot password**. Either way, the roles available to assign are your organization's roles at or below your own level. The **Owner** role is never assigned this way; it only moves through **Transfer ownership** (see below). ### Activating and deactivating members **Deactivate** on the Users page turns off a person's access to your organization only, including the owner's. Their login and any other organizations they belong to are not affected, and **Activate** turns it back on. Someone who belongs to at least one working organization can always sign in; they land in the organization they used last. A person's name, email, phone, password and two-factor settings belong to their account, which they may share with other organizations. You can change those only when you manage every organization the person is active in (a deactivated membership no longer counts). Otherwise the Users page shows **Reset link** in place of **Password**: it emails the person the same link **Forgot password** sends, and they choose the new password themselves. The link expires in 30 minutes. If a person's own organization is still waiting for approval, they can still work in yours: they sign in, land in your organization, and see their pending one in the organization switcher. ### The cross-agency rule There's one limit on who can be added across organizations: a person can be added to an organization in a different top-level hierarchy than one they already belong to only if they hold a manager-or-higher role in the top-level organization of a hierarchy they're already part of. In plain terms: an ordinary agent or viewer at one agency's client organization can't be pulled into a completely unrelated agency's tree just because someone there knows their email. If the rule isn't met, the add is refused with a message that the user belongs to another organization's hierarchy and can't be added there. This is what keeps one reseller's client staff from ending up inside a different reseller's organizations. The rule doesn't apply within your own hierarchy: parent and sibling organizations under the same top-level agency can freely add each other's people. ## Transfer ownership An organization has at most one owner, and can have none for a while (for example after its owner is deactivated or leaves); admins of a parent organization and platform staff can still manage it. On the Users page, **Transfer ownership** moves the Owner role from you to another member of the organization in a single step: they become the owner, and your role changes to the one the transfer specifies. Use it to hand an organization to someone before you step away. ## Suspending sub-organizations An admin of a parent organization can suspend and reinstate its own sub-organizations. A suspension applied by Political Comms staff can only be lifted by staff. You can only create a new organization under one you manage. ## Working with a sub-organization's assets Asset pages show only the organization you are working in: 10DLC brands and campaigns, the Media library, Lists, Short Codes, and Campaign Verify submissions. A parent organization's owner or admin does not see a sub-organization's rows there. To work with a sub-organization's assets, use **View As** in the header to view as a user in that sub-organization. The Projects dashboard and **Email > Campaigns** still list work across your sub-organizations. Turn the **Include sub-organizations** switch in the Filters popover off to see only your own; it is on by default and remembered for you. Opening a sub-organization's project from the dashboard, including editing it, works as before. **Billing > Subscriptions**, the Ledger's sub-organization spend views, Users, Organizations, and Data Exports also still cover your sub-organizations. ## View As and platform staff Platform staff (Political Comms super-admins) and agency admins using **View As** to see the dashboard as one of their users now pick both the person and the organization when that person belongs to more than one. This matters more now that a single account can hold memberships across several organizations. The organization you pick determines which role and brand access View As inherits. Platform staff status itself is a global account flag set by Political Comms, not a role you can grant to someone through Users or invitations. Platform staff now start **View As** from the Political Comms staff portal through a one-time handoff link rather than from inside your dashboard; you see no difference in how a staff member viewing your account appears. # Platform Features Source: https://docs.politicalcomms.com/help/platform-features Throughput, MMS, personalization, two-way conversations, team permissions, and reporting. ## How many messages can I send per hour? Our platform is built to handle 100,000+ messages per hour with proven production stability. Projects launch instantly (sub-second), and messages are processed with automatic error recovery and smart retries. For most campaigns, sending speed depends on your team size and workflow rather than platform limitations. ## Can I send from more than one phone number? Yes. A project can send across up to 49 phone numbers instead of one. New conversations are spread across the project's numbers, and once a recipient has been texted from a number, every later message in that conversation comes from the same number - a stable sender that carriers and recipients recognize. This works identically for 10DLC and toll-free numbers. ## Can I send from a toll-free number? Yes. Toll-free is a full sending channel alongside 10DLC: purchase a toll-free number, complete the carrier verification form (savable as a draft), and send once the carrier marks it verified. Toll-free projects skip brand and campaign registration entirely. Contact lists, media files, and opt-out lists can be scoped to a toll-free registration the same way they can be scoped to a brand. ## When can messages be sent? Each project has one sending window, worked out from your recipients' area codes. If more than half of them are in one time zone, messages send between 8 AM and 10 PM in that zone. If no time zone has a majority, such as a nationwide list, the window opens at 8 AM Eastern and closes at 10 PM Pacific. Contacts are not held individually for their own local time, so on a nationwide list a recipient on the West Coast can be texted as early as 5 AM their time and one on the East Coast as late as 1 AM their time. Scheduling or starting a send outside the window is blocked with a clear message, and a project still sending at the close is automatically paused (with a notification) so you can resume it when the window opens. Replies in two-way conversations are not held. The schedule modal shows the detected window up front. ## Can I send pictures and videos with my messages? Yes. We support full MMS messaging including images, videos, and audio files. Upload media to your Media Library once and reuse it across multiple campaigns. Videos are supported up to 1080p HD quality, and all media is stored securely with authenticated access. Each message can include text, media, links, and personalization. ## How does message personalization work? Use merge fields to personalize each message with recipient-specific information. Insert `{{firstName}}`, `{{city}}`, or any custom contact field into your message templates. For example: `"Hi {{firstName}}, there's a rally in {{city}} tomorrow!"` The platform automatically replaces these fields with actual contact data when sending. ## Can recipients reply to my messages? Absolutely. Two-way conversations are a core feature. All replies are threaded by conversation, and you can respond directly from the platform. Create quick reply templates to speed up common responses. Every conversation is tracked with full history, allowing your team to maintain context and provide personalized engagement. ## How do I manage multiple team members and permissions? Add unlimited team members with no extra cost. Assign role-based permissions to control what each person can access: **Admin**, **Manager**, **Agent**, or **Viewer**. * **Admins** have full control. * **Managers** can create campaigns. * **Agents** can send and reply to messages. * **Viewers** can only see reports. Set permissions at the organization level or per-project. The same login can belong to more than one organization, each with its own role and brand access. See [Organizations and memberships](/help/organizations-and-memberships) for switching between organizations, inviting an account that already exists elsewhere on the platform, and transferring ownership. ## What analytics and reporting are available? Real-time analytics dashboard shows: messages sent/delivered/failed, reply rates, opt-out rates, link click tracking, engagement metrics, and campaign performance. Export detailed reports in CSV format, including a Responses CSV that lists every reply on a project with the message it was replying to. Track performance across projects, campaigns, and team members. All data includes timestamps and correlation IDs for complete auditability. ### Responses report (CSV) The Downloads menu on a project report includes a **Responses (CSV)** export: one row per inbound reply, with the time it arrived, the phone number, the reply itself, the message it was replying to, the contact's list fields, and whether the conversation has opted out. Survey projects also get the question and the answer it matched. Opt-out replies such as STOP, UNSUBSCRIBE, "remove me", "wrong number", or a reply telling you to go away are left out, so the file matches what the platform actually did; other replies from a contact who later opted out are kept. The export is built in the background and appears in the Downloads list when it is ready, and it is included in Download All (ZIP) for projects still inside the 180-day window. For older projects, use the Data Export instead. ### Tracking Export (CSV) Projects with link tracking on get a **Tracking Export (CSV)** in the Downloads menu: one row per link click, with the time of the click, the phone number of the recipient whose link was clicked, the destination, the tracking link, the device, browser and operating system, the referring page when the browser sent one, whether it was the first click from that device, and whether it likely came from someone the link was forwarded to, followed by the contact's list fields. Clicks from link previews, carrier scanners and bots, and clicks on test sends, are left out, so the file matches the click totals on the report. The export is built in the background and appears in the Downloads list when it is ready. It is included in Download All (ZIP) and in report emails for projects still inside the 180-day window. ### Data Export (CSV) The **Data Export (CSV)** on a project report is one row per recipient in the project's audience: the contact's list fields, the number that sent to them, and every message in the conversation with its disposition (Delivered, Failed, Sent, Received), link clicks, and any error reason. Recipients who were never sent a message because the project was paused, stopped, or is still sending are included with **Not sent** in the Message 1 Disposition column, so the file's row count matches Total Recipients minus Ineligible on the report. An export taken while a project is still sending is a snapshot of that moment. Download All (ZIP) includes the same file. ### Data Exports (Parquet to your bucket) For continuous delivery into a warehouse, **Admin > Data Exports** writes message, project, opt-out and click data as Parquet files into an S3-compatible bucket you own, hourly, daily or on demand. Setup, file layout and every column: [Data exports to your S3 bucket](/help/data-exports). ## How does AI help with replies and surveys? Three ways, all optional: * **Linc reply drafts.** Turn on AI responses for a project and Linc drafts replies to inbound messages. You can give each project a campaign goal (turnout, donations, RSVPs, volunteering) and extra context (poll hours, donation link, event details), and drafts steer toward your goal using only facts you provided. * **AI survey analysis.** Enable "Use AI to analyze responses" on a survey and free-form replies that don't exactly match an answer option are classified to the option they clearly express, following that option's branching. Only replies that fail exact matching are analyzed. * **Linc support assistant.** Ask Linc questions about your own account - delivery totals, list status, registration status, phone inventory, billing history - and it answers from your data. Billing questions are limited to owner, admin, and manager roles, and Linc never sees individual contacts, phone numbers, message bodies, or free-text survey responses. # Sending speed and carrier limits Source: https://docs.politicalcomms.com/help/sending-speed 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. ## How fast can I send? The platform sends as fast as each carrier accepts messages. Most carriers take everything you send at full speed. A few set limits of their own, and those are listed below. For the platform's overall sending capacity, see [Platform features](/help/platform-features). ## What are the limits for each sender type? | Sender type | Limit | | - | - | | 10DLC to AT\&T | A per-minute limit set for each registered campaign by the carrier registry, counted in message parts. A text that fits in one part (up to 160 standard characters, fewer with emoji or special characters) counts once, and a longer text that splits into 2 or 3 parts counts 2 or 3 times. A picture message counts once against a separate picture message limit. Commonly 4,500 text message parts or 2,400 picture messages per minute for political campaigns, and lower for some campaign types and vetting scores. | | 10DLC to T-Mobile | A daily limit per brand, for brands that have one on file. Past it, T-Mobile recipients keep sending at a reduced rate while the platform watches delivery receipts. Political brands verified through Campaign Verify do not have one today. | | 10DLC to Verizon and other carriers | No published per-campaign limit. | | Toll-free | About 20 messages per second per number. | | Short code | About 1,000 messages per second per number, with no per-minute carrier limit. | The carriers set these numbers, and they can change. ## What happens when my send reaches the AT\&T limit? Recipients on other carriers keep sending at full speed. AT\&T recipients are sent right away as well, and the carrier queue delivers them at the limit, usually within about an hour of sending. The project is not paused and there is nothing you need to do: it finishes by itself. ## What happens when my brand reaches its T-Mobile daily limit? The daily limit is a speed limit, not a stop. Past it, T-Mobile recipients (and recipients whose carrier is not known) keep sending at a reduced rate, about 300 message parts per minute for each campaign. Once about 300 of those messages have been delivered with fewer than 5% failing, the rate rises to about 3,000 parts per minute. Recipients on other carriers are never slowed. If you analyze the list first, only T-Mobile recipients are affected. If T-Mobile starts rejecting messages over the limit, the platform stops sending to T-Mobile for the rest of the day (the limit resets at midnight Pacific) and the project pauses once only T-Mobile recipients remain. Rejected messages are still billed. To wait for the reset, start the project again the next morning. To try T-Mobile again right away, start it again now; it pauses again if T-Mobile is still rejecting. ## How long will AT\&T take? Multiply the number of AT\&T recipients by the number of parts in your text, then divide by the per-minute limit. The estimate in the Start dialog already accounts for your message length, and for any AT\&T messages your campaign already has waiting. The platform sends AT\&T recipients right away, so the project finishes sending quickly. Delivery to AT\&T phones follows the limit, and in practice AT\&T recipients usually receive the message within about an hour of sending. For example, suppose you send to a 1,000,000 recipient audience and about a third are on AT\&T. That is roughly 330,000 AT\&T recipients. With a one-part text and a limit of 4,500 per minute, they take about 73 minutes. With a two-part text, the same audience uses 660,000 parts and takes about 147 minutes. A text that fits in one part reaches AT\&T recipients up to three times faster than a three-part text. ## What is the sending window and how does it affect AT\&T? Each project has one sending window, worked out from your audience's area codes rather than from the time zone you schedule in. If more than half of your recipients are in one time zone, messages send between 8:00 AM and 10:00 PM in that zone. If no time zone has a majority, the window opens at 8:00 AM Eastern and closes at 10:00 PM Pacific. Before you start a project, the Start dialog shows about when the last AT\&T recipient will be reached. If the sending window will close first, it warns you and shows how many recipients will wait. Recipients not reached by the close wait until you start the project again the next morning. In the last 90 minutes of the sending window, the platform hands over only as many AT\&T messages as AT\&T can deliver before the window closes, so AT\&T messages do not arrive after it closes. The rest wait and go out when you start the project again in the next window. ## How can I send faster? * **Keep your text within one part where you can.** This is the cheapest option. The message editor shows the character count, and a notice tells you when a text runs to more than one message part. * **Start earlier in the day.** A project started before the last 90 minutes of the window sends all of its recipients right away, so nothing waits until the next morning. * **Use a short code.** A short code has no per-minute carrier limit. Provisioning takes roughly 8 to 12 weeks. For current pricing, [contact support](/help/technical-support). * **Add a 10DLC campaign.** Each campaign has its own AT\&T limit, but carriers can reject a campaign that duplicates an existing one. [Contact support](/help/technical-support) and we will check whether a second campaign is appropriate for your use case. ## Can I check this through the API? Yes. `GET /campaigns/{id}/throughput` and `GET /projects/{id}/throughput` return the carrier limits and estimates. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). # Sharing phone numbers with sub-organizations Source: https://docs.politicalcomms.com/help/shared-phone-numbers 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. An agency or parent organization often registers the 10DLC brand and campaign, the toll-free verification, or the short code, while a sub-organization does the sending. Number sharing lets the parent grant a sub-organization the use of one specific number, without moving anything and without exposing the registration behind it. ## What a share is A share is one phone number granted to one organization under yours, with a nickname you choose. Whatever sits behind the number rides along automatically: the 10DLC campaign and brand, the toll-free verification, or the short code profile. Nothing else is shared: not the brand, not the campaign, not the other numbers on them. The organization you share with sees the nickname and the digits. It never sees your brand name, campaign name, registration details, business profile, or provider identifiers. On its side the number simply appears under **Text > Shared With You**, in the project form under **Shared numbers**, and as an owner it can upload contact lists, media, and opt-out lists to. ## What stays with you * **Billing.** You keep paying the registration and monthly number fees. The sub-organization pays the per-message usage for what it sends, from its own balance, exactly as it would on its own numbers. * **Control.** The sub-organization cannot edit, release, or delete the number, cannot buy more numbers into your campaign or verification, and cannot share the number onward. * **Your assets.** Your contact lists, media, and opt-out lists never become visible to the sub-organization. It uploads its own under the nickname, or uses its organization-wide lists and media. ## Opt-outs apply to the number Carriers treat STOP per sending number, and so does the platform. When a contact replies STOP to a message sent from a shared number, that contact is opted out of the number for you **and** for every organization you share it with, whichever project the reply came in on. START reverses it everywhere. Each organization keeps its own **Replied Opt-Outs** and **Tagged Opt-Outs** lists for the share (labeled by the nickname), and every project sending from the number is suppressed by all of them. This is the one compliance implication of sharing, and the share dialog states it. ## Sharing a number 1. Open the number on **Text > 10DLC** (campaign view), **Text > Toll Free**, or **Text > Short Code**. 2. Choose **Share**, pick an organization under yours, and give the share a nickname. The nickname is what the sub-organization sees, and it must be unique among the numbers you share with that organization. 3. The same dialog lists every organization the number is shared with, lets you rename a share, and lets you revoke one. Sharing requires the **provisioning.manage** permission. Only organizations directly or indirectly under yours can be chosen. ## Using a shared number In the project form a **Sender** choice appears once your organization has at least one shared number: **My numbers** or **Shared numbers**. Pick the shared number by its nickname; the channel and campaign or verification are filled in from the share. A project uses either your own numbers or shared numbers, never a mix, and every shared number on one project must come from the same campaign or verification. Projects on a shared number show the nickname where your own projects show the brand and campaign, and carry a **Shared** badge. ## Revoking a share Revoking a share, or releasing the number, immediately pauses every scheduled or running project the sub-organization has on that number, with the reason shown on the project. Drafts keep their settings until edited. The sub-organization is notified, picks a different number, and starts the project again; a revoked number cannot be reselected. Its opt-out lists for the share are kept. ## On the API `GET /v1/phone-numbers` includes shared numbers for the organizations the key can access, with `shared: true` and `nickname`; on those rows the owner's names and `brand_id` are null. Projects created through the API on shared numbers pass the share's `campaign_id` (or `toll_free_verification_id`) with the shared `phone_number_ids`, and their `brand_name` and `campaign_name` read back as the nickname. # Technical Support Source: https://docs.politicalcomms.com/help/technical-support Supported devices, delivery troubleshooting, API integration, contact imports, error handling, and where to learn more. ## What devices can I use to send messages? Access the platform from any device with a web browser: desktop computers (Mac/PC), laptops, tablets (iPad/Android), or smartphones (iOS/Android). For best experience on desktop, we recommend Chrome, Firefox, Safari, or Edge (latest versions). The interface is fully responsive and optimized for all screen sizes. ## Why are some of my messages not delivering? Common reasons: 1. Invalid phone number format 2. Landline number (use carrier lookup to filter) 3. Number is disconnected 4. Carrier filtering due to spam patterns 5. Insufficient balance Check message status in your campaign dashboard for specific error codes. Contact support if you see pattern failures, we can investigate with carriers. ## Can I integrate the platform with other tools? Yes. We provide a comprehensive REST API and real-time webhooks for: message delivery status, inbound message notifications, contact management, campaign creation, and reporting data. Integration documentation is available in the [API Reference](/api-reference/introduction). Common integrations include CRMs, voter databases, and custom workflow tools. Contact support for integration assistance. ## How do I import my contact lists? Upload a CSV at **Assets > File Uploads**. Each file needs a phone number column (10-digit format), an email column, or both: one list holds phone numbers and emails together. Optional fields: `firstName`, `lastName`, `city`, `state`, `zip`, and unlimited custom fields. Our system validates phone numbers, detects duplicates, and optionally runs carrier lookup to filter landlines. Maximum file size: 1M rows per upload. Contacts are stored at the organization level and can be used across multiple projects. ## What if I encounter an error or bug? If you encounter errors: 1. Check your internet connection 2. Refresh the page and try again 3. Check for browser console errors (F12) 4. Verify your account permissions 5. Check the [system status page](https://app.politicalcomms.com/status) for known issues If problems persist, contact support with: error message, steps to reproduce, browser/device info, and account details. We typically respond within 1 business day. ## How can I learn more about advanced features? Explore our documentation: 1. [Onboarding Guide](/onboarding/overview) for step-by-step setup 2. [Help Center](/help/getting-started) for common questions and best practices 3. [Compliance Guide](/compliance/overview) for regulatory guidelines 4. [API Documentation](/api-reference/introduction) for integration details For personalized training or questions, contact your account manager or [support@politicalcomms.com](mailto:support@politicalcomms.com). # Welcome to Political Comms Source: https://docs.politicalcomms.com/introduction Enterprise-grade P2P texting for political campaigns, PACs, parties, and nonprofits. Documentation, compliance guidance, and API reference. Political Comms is a peer-to-peer (P2P) texting platform built for political campaigns, PACs, party committees, and nonprofits. Send individually-initiated messages to large lists at scale, maintain authentic two-way conversations, and stay compliant with TCPA, FCC, CTIA, and 10DLC rules - all in one place. > [card] [Get started in 2-3 days](/onboarding/overview) > > Register your brand, get verified with Campaign Verify, set up your first campaign, and start sending. > [card] [Help Center](/help/getting-started) > > Common questions, best practices, billing, and technical support. > [card] [Compliance Guide](/compliance/overview) > > TCPA, FCC political messaging rules, CTIA principles, The Campaign Registry, and Campaign Verify. > [card] [API Reference](/api-reference/introduction) > > REST API for organizations, brands, campaigns, projects, contacts, media, analytics, and billing. Plus real-time webhooks. ## What makes Political Comms different > [accordion] Built for political messaging at scale > > 100,000+ messages per hour with sub-second project launches. Proven production stability at 1M+ messages/hour sustained and 5M/hour burst capacity. Automatic error recovery and smart retries handle carrier hiccups so you don't have to. > [accordion] Compliance-first architecture > > STOP / UNSUBSCRIBE / QUIT keywords are processed automatically within seconds. Opt-out lists are maintained per brand and globally. Quiet-hours enforcement is built in: each project sends only inside one window (8 AM – 10 PM in the time zone of most recipients, or 8 AM Eastern to 10 PM Pacific when no zone holds a majority). Campaign Verify and 10DLC registration are part of the standard onboarding flow. > [accordion] Two-way conversations, threaded automatically > > Every reply is threaded by conversation with full history. Use quick-reply templates to scale agent response times. Conversations are tracked across team members so context never gets lost. > [accordion] Real-time analytics and webhooks > > Live delivery, reply, opt-out, and link-click metrics. Webhooks fire on every event (`message.sent`, `message.delivered`, `message.failed`, `message.replied`, `link.clicked`) so you can stream data into your CRM, warehouse, or alerting stack. ## Quick links * **New here?** Start with the [5-step onboarding guide](/onboarding/overview). * **Setting up 10DLC?** See [The Campaign Registry](/compliance/campaign-registry) and [Campaign Verify](/compliance/campaign-verify). * **Integrating programmatically?** Jump to the [API introduction](/api-reference/introduction) and [authentication](/api-reference/authentication). * **Have a compliance question?** Browse the full [compliance guide](/compliance/overview) or skim the [compliance checklist](/compliance/checklist). > [!NOTE] > > **Need direct help?** Email [support@politicalcomms.com](mailto:support@politicalcomms.com) or sign in to your [dashboard](https://app.politicalcomms.com) to file a support ticket. Real-time platform status lives at the [status page](https://app.politicalcomms.com/status). # Privacy Policy Source: https://docs.politicalcomms.com/legal/privacy Political Comms' privacy practices for the data we collect, how we use it, and your choices. Last modified: May 13, 2026 ## Introduction Political Comms ("Company" or "We") respects your privacy and is committed to protecting it through our compliance with this policy. This policy describes the types of information we may collect from you or that you may provide when you visit the website and use our software and related apps and updates and appendages (our "Software") and our practices for collecting, using, maintaining, protecting, and disclosing that information. This policy applies to information we collect: * On this Software. * In email, text, and other electronic messages between you and us. * When you interact with our advertising and applications on third-party websites, software, and services, if those applications or advertising include links to this policy. It does not apply to information collected by: * Us offline or through any other means, including on any other Software operated by Company or any third party (including our affiliates and subsidiaries); or * Any third party, including through any application or content (including advertising) that may link to or be accessible from or on the Software. Please read this policy carefully to understand our policies and practices regarding your information and how we will treat it. IF YOU DO NOT AGREE WITH OUR POLICIES AND PRACTICES, YOUR CHOICE IS NOT TO USE OUR SOFTWARE. BY ACCESSING OR USING THIS SOFTWARE, YOU AGREE TO THIS PRIVACY POLICY. This policy may change from time to time. Your continued use of this Software after we make changes is deemed to be acceptance of those changes, so please check the policy periodically for updates. ## Minors Our Software is not intended for anyone under 18 years of age. Anyone under the age of 18 is underage. No one underage may use the software or provide any information to or on the Software. We do not knowingly collect personal information from minors. If you are under 18, do not use or provide any information on this Software or through any of its features, register on the Software, make any purchases through the Software, use any of the interactive or publication feature of this Software, or provide any information about yourself to us, including your name, address, telephone number, email address, or any screen name or user name you may use. If we learn we have collected or received personal information from a minor, without verification of parental consent, we will delete that information. If you believe we might have any information from or about a minor, please contact us using the contact information given below. ## Information We Collect About You and How We Collect It We collect several types of information from and about users of our Software, including information: * By which you may be personally identified, such as name, postal address, e-mail address, telephone number, employer identification number, social security number or any other identifier by which you may be contacted online or offline ("personal information"); * That is about you but individually does not identify you, such as statistical and other information related to your use of the Software; and * About your internet connection, the equipment you use to access our Software, and usage details. We collect this information: * Directly from you when you provide it to us. * Automatically as you navigate through the site or use our Software. Information collected automatically may include usage details, IP addresses, and information collected through cookies, web beacons, and other tracking technologies. ## Information You Provide to Us The information we collect on or through our Software may include: * Information that you provide by filling in forms on our Software. This includes information provided at the time of registering to use our Software, subscribing to our service, posting material, or requesting further services. We may also ask you for information when you enter a promotion sponsored by us, and when you report a problem with our Software. * Records and copies of your correspondence (including email addresses), if you contact us. * Your responses to surveys that we might ask you to complete for research purposes. * Details of transactions you carry out through our Software and of the fulfillment of your orders. You may be required to provide financial information before using our Software. You also may provide information to be published or displayed (hereinafter, "posted") on public areas of the Software, or transmitted to other users of the Software or third parties (collectively, "User Contributions"). Your User Contributions are posted on and transmitted to others at your own risk. Please be aware that no security measures are perfect or impenetrable. Additionally, we cannot control the actions of other users of the Software with whom you share your account, with whom you may choose to share your User Contributions, and third-parties with whom you share User Contributions. Therefore, we cannot and do not guarantee that your User Contributions will not be viewed by unauthorized persons. ## Information We Collect Through Automatic Data Collection Technologies As you navigate through and interact with our Software, we may use automatic data collection technologies to collect certain information about your equipment, browsing actions, and patterns, including: * Details of your visits to our Software, including traffic data, location data, logs, and other communication data and the resources that you access and use on the Software. * Information about your computer and internet connection, including your IP address, operating system, and browser type. The information we collect automatically may include personal information, or we may maintain it or associate it with personal information we collect in other ways or receive from third parties. It helps us to improve our Software and to deliver a better and more personalized service, including by enabling us to: * Estimate our audience size and usage patterns. * Store information about your preferences, allowing us to customize our Software according to your individual interests. * Speed up your searches. * Recognize you when you return to our Software. The technologies we use for this automatic data collection may include: * **Cookies (or browser cookies).** A cookie is a small file placed on the hard drive of your computer. You may refuse to accept browser cookies by activating the appropriate setting on your browser. However, if you select this setting you may be unable to access certain parts of our Software. Unless you have adjusted your browser setting so that it will refuse cookies, our system will issue cookies when you direct your browser to our Software. * **Flash Cookies.** Certain features of our Software may use local stored objects (or Flash cookies) to collect and store information about your preferences and navigation to, from, and on our Software. Flash cookies are not managed by the same browser settings as are used for browser cookies. * **Web Beacons.** Pages of our Software and our e-mails may contain small electronic files known as web beacons (also referred to as clear gifs, pixel tags, and single-pixel gifs) that permit the Company, for example, to count users who have visited those pages or opened an email and for other related Software statistics (for example, recording the popularity of certain Software content and verifying system and server integrity). ## How We Use Your Information We use information that we collect about you or that you provide to us, including any personal information: * To present our Software and its contents to you. * To provide you with information, products, or services that you request from us. * To fulfill any other purpose for which you provide it. * To provide you with notices about your account, including balances, expiration, and renewal notices. * To carry out our obligations and enforce our rights arising from any contracts entered into between you and us, including for billing and collection. * To notify you about changes to our Software or any products or services we offer or provide through it. * To allow you to participate in interactive features on our Software. * To develop and improve automated systems, including machine learning models, that help optimize message delivery, timing, and engagement across our platform. * To generate insights, scores, and analytics based on messaging activity and engagement patterns, which may be used to enhance services provided to you and other clients of the platform. * To analyze usage patterns across the platform to improve service quality, data accuracy, and effectiveness for all clients. * To contact you about services that may be of interest to you. * In any other way we may describe when you provide the information. * For any other purpose with your consent. ## Disclosure of Your Information We may disclose aggregated information about our users, and information that does not identify any individual, without restriction. We may disclose personal information that we collect, or you provide as described in this privacy policy: * To our subsidiaries and affiliates. * To contractors, service providers, and other third parties we use to support our business. * To a buyer or other successor in the event of a merger, divestiture, restructuring, reorganization, dissolution, or other sale or transfer of some or all of the Company's assets, whether as a going concern or as part of bankruptcy, liquidation, or similar proceeding, in which personal information held by us about our Software users is among the assets transferred. * To fulfill the purpose for which you provide it. * For any other purpose disclosed by us when you provide the information. We may also disclose your personal information: * To comply with any court order, law, or legal process, including to respond to any government or regulatory request. * To enforce or apply our terms of use, client agreement, and other agreements, including for billing and collection purposes. * If we believe disclosure is necessary or appropriate to protect the rights, property, or safety of the Company, our customers, or others. This includes exchanging information with other companies and organizations for the purposes of fraud protection and credit risk reduction. We may share, disclose, or otherwise make available certain information, including phone numbers, messaging activity, engagement metrics, and related data, with trusted partners, data providers, and service providers for purposes such as data validation, matching, enrichment, analytics, audience insights, and improving the performance and effectiveness of our services and the services of our partners. These partners are contractually obligated to handle such information in accordance with applicable privacy laws. We may engage in commercial relationships with data partners that involve the exchange of data, insights, and services to enhance data quality, accuracy, platform performance, and the services available to our clients and partners. Such exchanges may include phone-number-level data and associated engagement or activity metrics. Insights, scores, and analytics derived from platform activity may also be made available to other users of our Software as part of the services we provide. In certain cases, such data sharing practices may be considered "sharing" under applicable privacy laws. ## Legal Disclosures and Law Enforcement We may transfer and disclose any and all information about you (including IP address), to third parties to comply with a legal obligation. Pursuant to requests by law enforcement agencies, or other governmental or quasi-governmental agencies, we may also disclose all information about you, as well as use device identifiers to identify users, and may do so in cooperation with copyright owners, internet service providers, wireless service providers or law enforcement agencies, in our discretion. Such disclosures may be carried out without notice to you. ## Choices About How We Use and Disclose Your Information We strive to provide you with choices regarding the personal information you provide to us. If you disable or refuse cookies, please note that some parts of this site may then be inaccessible or not function properly. We do not control third parties' collection or use of your information to serve interest-based advertising. However, these third parties may provide you with ways to choose not to have your information collected or used in this way. You can opt out of receiving targeted ads from members of the Network Advertising Initiative ("NAI") on the NAI's Software. ## Accessing and Correcting Your Information You can review and change your personal information by logging into the Software and visiting your account profile page. You may also send us an email at the address given below to request access to, correct, or delete any personal information that you have provided to us. We may not be able to delete your personal information except by also deleting your user account. We may not accommodate a request to change information if we believe the change would violate any law or legal requirement or cause the information to be incorrect. If you delete your User Contributions from the Software, copies of your User Contributions may remain viewable in cached and archived pages or might have been copied or stored by other Software users. Proper access and use of information provided on the Software, including User Contributions, is governed by our terms of use agreement. ## Your California Privacy Rights If you are a California resident, California law may provide you with additional rights regarding our use of your personal information. ## Data Security We have implemented measures designed to secure your personal information from accidental loss and from unauthorized access, use, alteration, and disclosure. The safety and security of your information also depends on you. Where we have given you (or where you have chosen) a password for access to certain parts of our Software, you are responsible for keeping this password confidential. We ask you not to share your password with anyone. We urge you to be careful about giving out information in public areas of the Software. The information you share with the public may not be retracted. Unfortunately, the transmission of information via the internet is not completely secure. Although we do our best to protect your personal information, we cannot guarantee the security of your personal information transmitted to our Software. Any transmission of personal information is at your own risk. We are not responsible for circumvention of any privacy settings or security measures contained on the Software. ## Changes to Our Privacy Policy It is our policy to post any changes we make to our privacy policy on this page on the Software home page. If we make material changes to how we treat our users' personal information, we will notify you. The date the privacy policy was last revised is identified at the top of the page. You are responsible for ensuring we have an up-to-date active and deliverable email address for you, and for periodically visiting our Software and this privacy policy to check for any changes. ## Contact Information To ask questions, gain information, provide feedback, or comment about this privacy policy and our privacy practices, contact us at: [support@politicalcomms.com](mailto:support@politicalcomms.com). # Terms of Use Source: https://docs.politicalcomms.com/legal/terms Terms of Use governing access to and use of the Political Comms platform. Last Modified: November 7, 2026 ## Acceptance of the Terms of Use These terms of use are entered into by and between the Software user ("you," or "your") and Political Comms ("Company," "we," "our," or "us"). The following terms and conditions, together with any documents they expressly incorporate by reference (collectively, "Terms of Use"), govern your access to and use of our website and related links, the software and related apps and updates and appendages; and all other technological and online systems provided by us and used by you, including any content, functionality, and services offered therefrom (the "Software"), whether as a guest or a registered user. PLEASE READ THE TERMS OF USE CAREFULLY BEFORE YOU START TO USE THE SOFTWARE. BY USING THE SOFTWARE OR BY CLICKING TO ACCEPT OR AGREE TO THE TERMS OF USE WHEN THIS OPTION IS MADE AVAILABLE TO YOU, YOU ACCEPT AND AGREE TO BE BOUND AND ABIDE BY THESE TERMS OF USE AND OUR PRIVACY POLICY, FOUND ON OUR WEBSITE, AND INCORPORATED HEREIN BY REFERENCE. IF YOU DO NOT WANT TO AGREE TO THESE TERMS OF USE OR THE PRIVACY POLICY, YOU MUST NOT ACCESS OR USE THE SOFTWARE. This Software is offered and available to users who are 18 years of age or older, and reside in the United States or any of its territories or possessions. By using this Software, you represent and warrant that you and your employees, agents, volunteers, independent contractors, members, shareholders, officers, licensees, lessees, and affiliated organizations ("Affiliated Persons"), who will be using the Software, are of legal age to form a binding contract with the Company and meet all of the foregoing eligibility requirements. If you do not meet all of these requirements, you must not access or use the Software. If you license or in any way re-lease this Software to other users (Second Level Users), you are responsible for the Second Level Users' adherence to these Terms of Use. You must require the Second Level Users to agree to be bound by your Terms of Use Agreement. Your Terms of Use Agreement must mirror this Terms of Use Agreement, except you may add your necessary identification information. ## Changes to the Terms of Use We may revise and update this Terms of Use Agreement from time to time in our sole discretion. All changes are effective immediately when we post them, and apply to all access to and use of the Software thereafter. However, any changes to the dispute resolution provisions set out in Governing Law and Jurisdiction will not apply to any disputes for which the parties have actual notice on or before the date the change is posted on the Software. Your continued use of the Software following the posting of revised Terms of Use means that you accept and agree to the changes. You are expected to check this page each time you access this Software so you are aware of any changes, as they are binding on you. ## Accessing the Software and Account Security We reserve the right to withdraw or amend this Software, and any service or material we provide on the Software, in our sole discretion without notice. We will not be liable if for any reason all or any part of the Software is unavailable at any time or for any period. From time to time, we may restrict access to some parts of the Software, or the entire Software, to users, including registered users. You are responsible for both: * Making all arrangements necessary for you to have access to the Software. * Ensuring that all persons who access the Software through your internet connection are aware of these Terms of Use and comply with them. To access the Software or some of the resources it offers, you may be asked to provide certain registration details or other information. It is a condition of your use of the Software that all the information you provide on the Software is correct, current, and complete. You agree that all information you provide to register with this Software or otherwise, including, but not limited to, through the use of any interactive features on the Software, is governed by our Privacy Policy, and you consent to all actions we take with respect to your information consistent with our Privacy Policy. If you choose, or are provided with, a user name, password, or any other piece of information as part of our security procedures, you must treat such information as confidential, and you must not disclose it to any other person or entity. You also acknowledge that your account is personal to you and agree not to provide any other person with access to this Software or portions of it using your user name, password, or other security information. You agree to notify us immediately of any unauthorized access to or use of your user name or password or any other breach of security. You also agree to ensure that you exit from your account at the end of each session. You should use particular caution when accessing your account from a public or shared computer so that others are not able to view or record your password or other personal information. We have the right to disable any user name, password, or other identifier, whether chosen by you or provided by us, at any time in our sole discretion for any or no reason, including if, in our opinion, you have violated any provision of this Terms of Use Agreement, the Privacy Policy, or any Client Agreement entered into by you. The fee for accessing and using the Software are published in the Software and in the Client Agreement (if applicable), and you agree to pay such fees immediately upon request from us and as outlined in any Client Agreement (if applicable). All fees are nonrefundable. In the event that you, for whatever reason, are late in making payments, all late payments shall bear interest at the lesser of the rate of 1.5% per month or the highest rate permissible under applicable law, calculated daily and compounded monthly. You shall also pay a onetime late payment penalty of 20% of all late balances, and you shall reimburse us for all costs incurred in collecting any late payments, and we may suspend the delivery of any access to the Software once a payment is late. You authorize us to keep your credit card information on file, and to charge your credit card for any amounts owed. You are responsible for all types of taxes, and governmental fees charged on your use of the Software. ## Intellectual Property Rights The Software and its entire contents, features, and functionality (including but not limited to all information, software, text, displays, images, video, and audio, and the design, selection, and arrangement thereof) are owned by the Company, its licensors, or other providers of such material and are protected by United States and international copyright, trademark, patent, trade secret, and other intellectual property or proprietary rights laws. These Terms of Use permit you to use the Software for your personal, non-commercial use only, unless you receive our written permission to do otherwise. You must not reproduce, distribute, modify, duplicate, create derivative works of, publicly display, publicly perform, republish, download, store, or transmit any of the material on our Software, except as follows: * Your computer may temporarily store copies of such materials in RAM incidental to your accessing and viewing those materials. * You may store files that are automatically cached by your Web browser for display enhancement purposes. * You may print, or download, one copy of a reasonable number of pages of the Software for your own personal, non-commercial use and not for further reproduction, publication, or distribution. * If we provide desktop, mobile, or other applications for download, you may download a single copy to your computer or mobile device solely for your own personal, non-commercial use, provided you agree to be bound by our end user license agreement for such applications. * If we provide places for you to store content in connection to the use of the Software, you may take such actions as are allowed by such features. * If you license or re-license the use of the Software, under the permission of the Company, you may provide such intellectual property as is necessary to provide the licensee with the use of the Software. You must not: * Modify copies of any materials from this site, except as provided herein. * Use any illustrations, photographs, video or audio sequences, or any graphics separately from the accompanying text. * Delete or alter any copyright, trademark, or other proprietary rights notices from copies of materials from this site. * Duplicate or recreate the Software in any way. You must not access or use for any commercial purposes any part of the Software or any services or materials available through the Software, except as outlined herein. If you wish to make any use of material on the Software other than that set out in this section, please address your request to the email provided below. If you print, copy, modify, download, or otherwise use or provide any other person with access to any part of the Software in breach of the Terms of Use, your right to use the Software will stop immediately and you must, at our option, return or destroy any copies of the materials you have made. No right, title, or interest in or to the Software or any content on the Software is transferred to you, and all rights not expressly granted are reserved by the Company. Any use of the Software not expressly permitted by these Terms of Use is a breach of these Terms of Use and may violate copyright, trademark, and other laws. If any change, alteration, or improvement of the Software ("Software Improvement") are made due to your review, insight, complaints, use of the Software, or any other actions (whether created directly or indirectly by you) all such Software improvement shall be the sole property of the Company. You transfer and assign all rights you may have in any such Software Improvement to the Company, and waive all rights to the works, and agree that the use of the Software as contemplated herein constitutes just consideration. ## Trademarks The Company name, design, and logo, and all related names, logos, product and service names, designs, and slogans are trademarks of the Company or its affiliates or licensors, whether it has been filed with the USPTO or not. You must not use such marks without the prior written permission of the Company. All other names, logos, product and service names, designs, and slogans on this Software are the trademarks of their respective owners. ## Prohibited Uses You may use the Software only for lawful purposes and in accordance with these Terms of Use. You agree not to use the Software: * In any illegal, improper or inappropriate way, including violating any applicable federal, state, local, or international laws, regulations, rules, treaties, and ordinances, including but not limited to the Communications Act, the Telephone Consumer Protection Act, the Fair Political Practices Commission, the Do-Not-Call Implementation Act, and the CAN-SPAM Act all as amended (or any similar or analogous anti-spam, data protection, or privacy legislation in any other jurisdiction), and the rules and regulations of the Federal Communications Commission, and Federal Trade Commission, including, without limitation, any laws regarding the export of data or software to and from the US or other countries ("Laws"). * To transmit, or direct the transmission of, any advertising, marketing or other messaging if Administrator has not obtained the consent, if and only to the extent consent is required by law, from the recipient. * In any manner that violates industry standards and/or any third-party obligations for which use of the Software would cause breach. * For the purpose of exploiting, harming, or attempting to exploit or harm minors in any way by exposing them to inappropriate content, asking for personally identifiable information, or otherwise. * To send, knowingly receive, upload, download, use, or re-use any material that does not comply with the Content Standards set out in these Terms of Use. * To transmit, or procure the sending of, any advertising or promotional material, including any "junk mail," "chain letter," "spam," or any other similar solicitation without the strict obedience to all Laws governing such transmission or procurement. * To impersonate or attempt to impersonate the Company, a Company employee, another user, or any other person or entity, without written consent of that person or entity. * To engage in any other conduct that restricts or inhibits anyone's use or enjoyment of the Software, or which, as determined by us, may harm the Company or users of the Software, or expose them to liability. Additionally, you agree not to: * Use the Software in any manner that could disable, overburden, damage, or impair the Software or interfere with any other party's use of the Software, including their ability to engage in real time activities through the Software. * Use any robot, spider, or other automatic device, process, or means to access the Software for any purpose, including monitoring or copying any of the material on the Software. * Use any manual process to monitor or copy any of the material on the Software, or for any other purpose not expressly authorized in these Terms of Use, without our prior written consent. * Use any device, software, or routine that interferes with the proper working of the Software. * Introduce any viruses, Trojan horses, worms, logic bombs, or other material that is malicious or technologically harmful. * Attempt to gain unauthorized access to, interfere with, damage, or disrupt any parts of the Software, the server on which the Software is stored, or any server, computer, or database connected to the Software. * Attack the Software via a denial-of-service attack or a distributed denial-of-service attack. * Use the Software to harvest or otherwise collect information about others from users, including email addresses or phone numbers, without their consent to provide such information. * Duplicate or reverse engineer the Software. * Otherwise attempt to interfere with the proper working of the Software. * Use Company's information or trade secrets to compete against the Company, or cause others to do so. If you are not exempt from the United States national do-not-call registry, you must refrain from making any phone calls or sending any text messages to any residential telephone subscriber, whose phone number is listed on a national or state do-not-call registry, and you must check all state and federal do-not-call registries prior to starting any calling campaign, to remove any listed numbers from campaign, and to recheck registries at least every 30 days, and you may not call or text protected phone lines such as emergency or toll-free lines, or lines serving hospitals or similar facilities, unless made with the called party's prior express consent. ## User Contributions The Software may contain interactive or distribution features (collectively, "Interactive Services") that allow users to post, submit, send, publish, display, or transmit to other users or other persons (hereinafter, "post") content or materials (collectively, "User Contributions") on or through the Software. All User Contributions must comply with the Content Standards set out in this Terms of Use Agreement. Any User Contribution you post will be considered non-confidential and non-proprietary. By providing any User Contribution on the Software, you grant us the right to retract, remove, use, reproduce, modify, perform, display, distribute, and otherwise disclose to third parties any such material for any purpose. You represent and warrant that: * You own or control all rights in and to the User Contributions and have the right to grant the license granted above to us. * All of your User Contributions do and will comply with these Terms of Use. You understand and acknowledge that you are responsible for any User Contributions you submit or contribute, and you, not the Company, have full responsibility for such content, including its legality, reliability, accuracy, and appropriateness. We are not responsible or liable to any third party for the content or accuracy of any User Contributions posted by you or any other user of the Software. ## Monitoring and Enforcement; Termination We have the right to: * Remove or refuse to post or transmit any User Contributions for any or no reason in our sole discretion. * Take any action with respect to any User Contribution that we deem necessary or appropriate in our sole discretion, including if we believe that such User Contribution violates the Terms of Use, including the Content Standards, infringes any intellectual property right or other right of any person or entity, threatens the personal safety of users of the Software or the public, or could create liability for the Company. * Disclose your identity or other information about you to any third party who claims that material posted by you violates their rights, including their intellectual property rights or their right to privacy, or to any government or quasi-governmental organization as part of any investigation they may be conducting. * Take appropriate legal action, including without limitation, referral to law enforcement, for any illegal or unauthorized use of the Software. * Terminate or suspend your access to all or part of the Software for any or no reason, including without limitation, any violation of these Terms of Use. Without limiting the foregoing, we have the right to cooperate fully with any law enforcement authorities or court order requesting or directing us to disclose the identity or other information of anyone posting any materials on or through the Software. YOU WAIVE AND HOLD HARMLESS THE COMPANY AND ITS AFFILIATES, LICENSEES, AND SERVICE PROVIDERS FROM ANY CLAIMS RESULTING FROM ANY ACTION TAKEN BY US DURING, OR TAKEN AS A CONSEQUENCE OF, INVESTIGATIONS BY EITHER US OR LAW ENFORCEMENT AUTHORITIES. However, we may not undertake to review all material before it is posted or transmitted on the Software, and cannot ensure prompt removal of objectionable material after it has been posted. Accordingly, we assume no liability for any action or inaction regarding transmissions, communications, or content provided by any user or third party. We have no liability or responsibility to anyone for performance or nonperformance of the activities described in this section. ## Content Standards These content standards apply to any and all User Contributions and use of Interactive Services. User Contributions must in their entirety comply with all applicable Laws. Without limiting the foregoing, User Contributions must not: * Contain any material that is defamatory, obscene, indecent, abusive, offensive, harassing, violent, hateful, inflammatory, or otherwise objectionable. * Promote sexually explicit or pornographic material, violence, or discrimination based on race, sex, religion, nationality, disability, sexual orientation, or age. * Infringe any patent, trademark, trade secret, copyright, or other intellectual property or other rights of any other person. * Violate the legal rights (including the rights of publicity and privacy) of others or contain any material that could give rise to any civil or criminal liability under applicable laws or regulations or that otherwise may be in conflict with these Terms of Use, our Privacy Policy, and any Client Agreement. * Be likely to deceive any person. * Promote any illegal activity, or advocate, promote, invite, or assist any unlawful act. * Cause annoyance, inconvenience, or needless anxiety or be likely to upset, embarrass, alarm, or annoy any other person. * Impersonate any person, or misrepresent your identity or affiliation with any person or organization. * Involve commercial activities or sales, such as contests, sweepstakes, and other sales promotions, barter, or advertising. * Give the impression that they emanate from or are endorsed by us or any other person or entity, if this is not the case. ## Copyright Infringement If you believe that any User Contributions violate your copyright, please send us a notice of copyright infringement. It is normally the policy of the Company to terminate the user accounts of repeat infringers. ## Reliance on Information Posted The information presented on or through the Software is made available solely for general information purposes. We do not warrant the accuracy, completeness, or usefulness of this information. Any reliance you place on such information is strictly at your own risk. We disclaim all liability and responsibility arising from any reliance placed on such materials by you or any other visitor to the Software, or by anyone who may be informed of any of its contents. This Software may include content provided by third parties, including materials provided by other users, and third-party licensors, syndicators, aggregators, and/or reporting services. All statements and/or opinions expressed in these materials, and all responses to questions and other content, other than the content provided by the Company, are solely the opinions and the responsibility of the person or entity providing those materials. These materials do not necessarily reflect the opinion of the Company. We are not responsible, or liable to you or any third party, for the content or accuracy of any materials provided by any third parties. ## Changes to the Software We may update the content on this Software from time to time, but its content is not necessarily complete or up-to-date. Any of the material on the Software may be out of date at any given time, and we are under no obligation to update such material. ## Information About You and Your Visits to the Software All information we collect on this Software is subject to our Privacy Policy. By using the Software, you consent to all actions taken by us with respect to your information in compliance with the Privacy Policy. The Software may use automated systems, including machine learning models, to analyze usage patterns and generate engagement insights. Data collected through the Software, including messaging activity and engagement metrics, may be shared with data partners or made available to other users of the Software in accordance with our Privacy Policy. ## Online Purchases and Other Terms and Conditions All purchases through our Software are governed by our Client Agreement, which are hereby incorporated into these Terms of Use. Additional terms and conditions may also apply to specific portions, services, or features of the Software. All such additional terms and conditions are hereby incorporated by this reference into these Terms of Use. ## Domain Services These Domain Services terms apply when you buy a domain name through the Software, or when we manage a domain name for your organization. They are part of these Terms of Use. **Ownership.** The organization that buys a domain is its owner and is listed as its registrant. You confirm that your organization's legal name, address and contact details are accurate, and you will keep them current. You authorize us to use our email address as the contact email on the registration and to receive and act on registrar notices for you. **We manage your domain.** We act as your agent to register, renew and manage the domain, its DNS and its settings, and we are listed as its administrative and technical contact. You authorize us to do so while the domain is under our management. The Software does not give you direct control of these settings. To change, transfer or cancel anything, contact [support@politicalcomms.com](mailto:support@politicalcomms.com) and we will handle it. **Price and renewal.** Before you buy, we show the registrar's price plus a yearly domain hosting fee. App and link tracking setup fees are separate. Domains renew every year. We charge your wallet about 30 days before the domain expires, at the price at that time. If your account belongs to a parent account, each organization in that hierarchy is also charged, as with other services. **Refunds.** Domain purchases and renewals are non-refundable once the registrar has processed them. If a registration or renewal is never processed, we refund the charge. **If you do not pay, or you turn off renewal.** If a renewal charge fails, we will notify you and retry during a grace period. If it remains unpaid, or you turn off renewal, the domain will not renew. It stops working when its paid term ends, including links you have already sent and any email using it. Someone else may then be able to register it. **Your responsibilities.** You are responsible for how the domain is used, including everything sent from it, linked through it or hosted on it. You represent that you have the right to use the name, that your use does not infringe anyone's rights, and that it complies with applicable law and with the Prohibited Uses and Content Standards in these Terms of Use. Your indemnification obligations under these Terms of Use include claims arising from your domain, such as trademark and domain name disputes. **Complaints and takedowns.** We may suspend, redirect or cancel a domain under our management without refund if we receive a court order or other legal process, a decision from a domain dispute proceeding, a credible complaint, or a registrar or registry instruction, or if we reasonably believe it is being used in violation of these Terms of Use. We do not have to decide who is right before acting. We will try to notify you first when we reasonably can. The registrar and registry have their own rights to suspend or cancel domains. **Transferring a domain away.** To move a domain to another registrar or provider, contact [support@politicalcomms.com](mailto:support@politicalcomms.com). We will give you what the transfer needs within 5 calendar days of your request. Registrar and registry rules may delay a transfer, including holds of up to 60 days after a domain is registered, transferred or changes owner. You pay any registrar transfer fees. Once a domain leaves our management, it is no longer connected to the Software. **Registrar and registry rules.** Domains are registered through an ICANN-accredited registrar, which you can find using the [ICANN lookup tool](https://lookup.icann.org). Your use of a domain is subject to the registrar's and registry's rules and to ICANN policies, including the [Uniform Domain-Name Dispute-Resolution Policy](https://www.icann.org/resources/pages/policy-2012-02-25-en). ICANN publishes [information for registrants](https://www.icann.org/resources/pages/educational-2012-02-25-en) and the [Registrants' Benefits and Responsibilities](https://www.icann.org/resources/pages/benefits-2013-09-16-en). **Your information and privacy.** We share your organization's contact details with the registrar and registry to register the domain, and you consent to that. WHOIS privacy is on where the ending allows it. Some endings do not allow it: for example, `.us` publishes contact details, and some endings display the company name. You agree to respond to our requests about your domain so we can meet registrar deadlines. Information about you or your domain may be shared with the registrar, registry or a dispute provider, or as required by law. **DNS.** We manage the DNS records needed for the uses you choose. We do not guarantee that a particular domain will be available, or that it will be free of third-party claims or carrier or inbox filtering. **End of service.** If your account closes or we stop offering domain services, we will give you a reasonable chance to transfer your paid domains before the paid term ends. ## Linking to the Software You may link to our homepage, provided you do so in a way that is fair and legal and does not damage our reputation or take advantage of it, but you must not establish a link in such a way as to suggest any form of association, approval, or endorsement on our part. The Software from which you are linking, or on which you make certain content accessible, must comply in all respects with the Content Standards set out in these Terms of Use. You agree to cooperate with us in causing any unauthorized framing or linking immediately to stop. We reserve the right to withdraw linking permission without notice. ## Links from the Software If the Software contains links to other sites and resources provided by third parties, these links are provided for your convenience only. This includes links contained in advertisements, including banner advertisements and sponsored links, if any. We have no control over the contents of those sites or resources, and accept no responsibility for them or for any loss or damage that may arise from your use of them. If you decide to access any of the third-party websites linked to this Software, you do so entirely at your own risk and subject to the terms and conditions of use for such websites. ## Geographic Restrictions The owner of the Software is based in the State of Texas in the United States. We provide this Software for use only by persons located in the United States. We make no claims that the Software or any of its content is accessible or appropriate outside of the United States. Access to the Software may not be legal by certain persons or in certain countries. If you access the Software from outside the United States, you do so on your own initiative and are responsible for compliance with local laws. ## Confidential Information Except as directed by law, you shall not use, divulge, furnish, publish, or disseminate or make accessible to anyone any confidential intellectual property, trade secrets, third-party confidential information, confidential information, proprietary information, secret information, or other sensitive or proprietary information of ours, outside your use of the information in lawfully using the Software. ## Disclaimer of Warranties You understand that we cannot and do not guarantee or warrant that files available for downloading from the internet or the Software will be free of viruses or other destructive code. You are responsible for implementing sufficient procedures and checkpoints to satisfy your particular requirements for anti-virus protection and accuracy of data input and output, and for maintaining a means external to our site for any reconstruction of any lost data. TO THE FULLEST EXTENT PROVIDED BY LAW, WE WILL NOT BE LIABLE FOR ANY LOSS OR DAMAGE CAUSED BY A DISTRIBUTED DENIAL-OF-SERVICE ATTACK, VIRUSES, OR OTHER TECHNOLOGICALLY HARMFUL MATERIAL THAT MAY INFECT YOUR COMPUTER EQUIPMENT, COMPUTER PROGRAMS, DATA, OR OTHER PROPRIETARY MATERIAL DUE TO YOUR USE OF THE SOFTWARE OR ANY SERVICES OR ITEMS OBTAINED THROUGH THE SOFTWARE OR TO YOUR DOWNLOADING OF ANY MATERIAL POSTED ON IT, OR ON ANY SOFTWARE LINKED TO IT. YOUR USE OF THE SOFTWARE, ITS CONTENT, AND ANY SERVICES OR ITEMS OBTAINED THROUGH THE SOFTWARE IS AT YOUR OWN RISK. THE SOFTWARE, ITS CONTENT, AND ANY SERVICES OR ITEMS OBTAINED THROUGH THE SOFTWARE ARE PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS. TO THE FULLEST EXTENT PROVIDED BY LAW, THE COMPANY HEREBY DISCLAIMS ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, STATUTORY, OR OTHERWISE, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR PARTICULAR PURPOSE AND ALL WARRANTIES ARISING FROM COURSE OF DEALING, USAGE, OR TRADE PRACTICE. NEITHER THE COMPANY NOR ANYONE ASSOCIATED WITH THE COMPANY REPRESENTS OR WARRANTS THAT THE SOFTWARE, ITS CONTENT, OR ANY SERVICES OR ITEMS OBTAINED THROUGH THE SOFTWARE WILL BE ACCURATE, RELIABLE, ERROR-FREE, OR UNINTERRUPTED, OR THAT THE SOFTWARE OR ANY SERVICES OR ITEMS OBTAINED THROUGH THE SOFTWARE WILL OTHERWISE MEET YOUR NEEDS OR EXPECTATIONS. YOU ARE FULLY RESPONSIBLE FOR DETERMINING WHETHER YOUR USE OF THE SOFTWARE IS APPROPRIATE FOR YOU, AS WE DO NOT GUARANTY ANY RESULTS FROM THE USE OF THE SOFTWARE. WE MAKE NO REPRESENTATIONS THAT THE SOFTWARE AND THE USE THEREOF COMPLY WITH ANY LAWS. YOU ARE FULLY RESPONSIBLE FOR DETERMINING WHETHER YOUR USE OF THE SOFTWARE COMPLIES WITH ALL LAWS, AND BY USING THE SERVICES YOU WARRANT THAT YOU HAVE DETERMINED THAT YOU ARE AND WILL BE IN COMPLIANCE WITH ALL LAWS. ## Limitation on Liability TO THE FULLEST EXTENT PROVIDED BY LAW, IN NO EVENT WILL WE BE LIABLE TO YOU FOR DAMAGES OF ANY KIND, UNDER ANY LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH YOUR USE, OR INABILITY TO USE, THE SOFTWARE, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO, PERSONAL INJURY, PAIN AND SUFFERING, EMOTIONAL DISTRESS, LOSS OF REVENUE, LOSS OF PROFITS, LOSS OF BUSINESS OR ANTICIPATED SAVINGS, LOSS OF USE, LOSS OF GOODWILL, LOSS OF DATA, LOSS OF CAMPAIGN, AND WHETHER CAUSED BY TORT (INCLUDING NEGLIGENCE), BREACH OF CONTRACT, OR OTHERWISE, EVEN IF FORESEEABLE. WITHOUT LIMITING THE ABOVE PROVISION, IN NO EVENT WILL THE COLLECTIVE LIABILITY OF THE COMPANY AND ITS SUBSIDIARIES AND AFFILIATES, AND THEIR LICENSORS, SERVICE PROVIDERS, EMPLOYEES, AGENTS, OFFICERS, AND DIRECTORS, TO ANY PARTY (REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT, TORT, OR OTHERWISE) EXCEED THE AMOUNT YOU HAVE PAID TO THE COMPANY FOR THE USE OF THE SOFTWARE IN THE LAST 3 MONTHS BEFORE THE INCIDENT OUT OF WHICH LIABILITY AROSE. THE FOREGOING DOES NOT AFFECT ANY LIABILITY THAT CANNOT BE EXCLUDED OR LIMITED UNDER APPLICABLE LAW. ## Indemnification You agree to defend, indemnify, and hold harmless the Company, its affiliates, licensors, and service providers, and its and their respective officers, directors, employees, contractors, agents, licensors, suppliers, successors, and assigns ("Indemnified Parties"), from and against any claims, liabilities, damages, judgments, awards, losses, costs, expenses, or fees, including attorneys' fees ("Claims"), arising out of or relating to your use of the Software, violation of this Terms of Use Agreement, violation of the Privacy Policy, and violation of any Client Agreement ("Cause of Action") whether claimed by you, the government, or any other third-party ("Claiming Party"). By way of inclusion, and not exclusion, and to remove all doubt, you agree to defend, indemnify, and hold harmless the Indemnified Parties from and against any Claims brought by any Claiming Party, which Claims arise out of your User Contributions' violating the Content Standards outlined herein, or your violation of any Laws, including but not limited to violations of any new Laws or new interpretations of any existing Laws which may arise. Upon written notice from us, you shall pay all reasonable attorney fees, and other legal costs in advance to cover any and all representation necessary to defend us from any Claims. Upon written notice from us, you shall pay all Claims when payment is due to any Claiming Party. ## Arbitration ALL CASES AND CONTROVERSIES ARISING OUT OF OR RELATED TO THIS TERMS OF USE AGREEMENT WILL BE FINALLY RESOLVED EXCLUSIVELY BY CONFIDENTIAL BINDING ARBITRATION ADMINISTERED BY THE AMERICAN ARBITRATION ASSOCIATION IN ACCORDANCE WITH THE UNITED STATES ARBITRATION ACT AND CONDUCTED IN AUSTIN, TEXAS IN ACCORDANCE WITH THE AAA COMMERCIAL ARBITRATION RULES, INCLUDING, WHERE APPLICABLE, ITS RULES ON EXPEDITED PROCEDURES. THE PARTIES MAY BRING AN ACTION TO ENFORCE ANY AWARD GRANTED UNDER THIS SECTION IN ANY COURT HAVING JURISDICTION. THE PREVAILING PARTY SHALL PAY THE OTHER PARTIES' ATTORNEY FEES AND ARBITRATION COSTS. ## Governing Law and Jurisdiction All matters relating to the Software and these Terms of Use, and any dispute or claim arising therefrom or related thereto in each case, including non-contractual disputes or claims, shall be governed by and construed in accordance with the internal laws of the State of TEXAS without giving effect to any choice or conflict of law provision or rule whether of the State of TEXAS or any other jurisdiction. Without limiting the obligation to arbitrate claims provided hereunder, any legal suit, action, or proceeding arising out of, or related to, these Terms of Use or the Software shall be instituted exclusively in the courts located in Austin, Texas. You waive any and all objections to the exercise of jurisdiction over you by such courts and to venue in such courts. WITHOUT LIMITING THE OBLIGATION TO ARBITRATE CLAIMS PROVIDED HEREUNDER, CLIENT AGREES TO WAIVE ALL RIGHTS TO A JURY TRIAL. ## Waiver and Severability No waiver by the Company of any term or condition set out in these Terms of Use shall be deemed a further or continuing waiver of such term or condition or a waiver of any other term or condition, and any failure of the Company to assert a right or provision under these Terms of Use shall not constitute a waiver of such right or provision. If any provision of these Terms of Use is held by a court or other tribunal of competent jurisdiction to be invalid, illegal, or unenforceable for any reason, such provision shall be eliminated or limited to the minimum extent such that the remaining provisions of the Terms of Use will continue in full force and effect. This Agreement benefits solely the Parties to this Agreement and no third-party. ## Entire Agreement The Terms of Use Agreement, our Privacy Policy, and any Client Agreement constitute the sole and entire agreement between you and us regarding the Software and supersede all prior and contemporaneous understandings, agreements, representations, and warranties, both written and oral, regarding the Software. ## Counterparts This Terms of Use Agreement may be executed in counterparts, each of which is deemed an original, but all of which together are deemed to be one and the same agreement. A signed copy of this Terms of Use Agreement delivered by facsimile, email, or other means of electronic transmission is deemed to have the same legal effect as delivery of an original signed copy, and an electronic signature shall have the same effect as an original signature. ## Your Notices, Comments, and Concerns This Software is operated by Political Comms, at the address first given above. All notices of copyright infringement claims should be sent by email to: [support@politicalcomms.com](mailto:support@politicalcomms.com). All notices of violations of our Content Standards should be sent to: [support@politicalcomms.com](mailto:support@politicalcomms.com). All other feedback, comments, requests for technical support, and other communications relating to the Software should be directed to: [support@politicalcomms.com](mailto:support@politicalcomms.com). All notice requirements to be sent to you are considered delivered if sent by any method for which we have your contact information: in person, address, email address, etc. # Step 2: 10DLC Brand & Campaign Registration Source: https://docs.politicalcomms.com/onboarding/10dlc-registration Register each brand with The Campaign Registry, vet with Campaign Verify, create campaigns, and provision phone numbers. > [!NOTE] > > **Estimated time:** 2–3 business days per brand ## Overview Complete 10DLC registration for each candidate/campaign through a 5-step process: **Setup Brand → Vet with Campaign Verify → Create Campaign → Add Phone Number → Start Sending**. Consulting firms will complete this process for each client. Individual candidates register once. Most brands are ready to send within 2–3 business days. > [!NOTE] > > **10DLC Registration Pricing (per brand)** > > | Item | Cost | Notes | > | - | - | - | > | Brand Registration | **\$4.50** | One-time, instant | > | Campaign Verify Token | **\$95.00** | One-time, valid for the current two-year election cycle | > | First Campaign | **\$30.00** | Covers the first 3 months | > | Ongoing Campaign Fee | **\$10.00 / month** | Per campaign, after initial 3 months | > | **Total Initial Setup** | **\$129.50** | Per brand | > > Consulting firms managing multiple candidates multiply these costs by the number of brands (one brand per candidate). Phone numbers are billed separately based on your pricing tier. > [!NOTE] > > **Email Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Email sending | **\$3.00 / 1,000 emails** | \$0.003 per recipient. Lower with volume. | > | Full-service email sending | **\$0.01 per email** | Our team builds and sends every campaign. Lower with volume. No monthly fee. | > | Full-service email setup | **\$1,000 one-time** | Domain authentication, DNS records, warm-up, and list import. | > | Sending domains | **Free** | Unlimited domains and From addresses. | > | Hosted unsubscribe and preferences | **Free** | Included with every send. | > | Dedicated IP pool add-on | **\$35.00 / month per sending domain** | Optional dedicated managed sending IP pool for one sending domain. Warm-up usually takes up to about six weeks, depending on your volume. | > | AI email draft (Lincoln) | **\$3.00 per draft** | AI-drafted email template from a prompt, images and brand colors. | > > Test sends are real sends and are billed at the same per-recipient rate. Email charges appear in the ledger under the Email family and roll up through the organization hierarchy like texting. > [!NOTE] > > **Domain Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Domain registration | **Registrar's price** | One year. Prices vary by ending, shown before you buy. Non-refundable once registered; refunded if registration never happens. | > | Domain hosting fee | **\$6.00 / year** | Flat. Covers the DNS records we write and keep current for the domain. | > | App or link-tracking host setup | **Normal setup fee** | One per host. | > > Charged from your wallet at purchase and renewed yearly, 30 days before the domain expires. Dashboard only. ## Tasks to complete **1. Setup Brand (\$4.50 per brand)** Register each candidate/campaign as a separate brand with The Campaign Registry. Provide the candidate's legal name, EIN/Tax ID, physical address, and active website, or click **"Use organization business profile"** on the brand form to prefill these fields from **Admin > Organization > Business profile** and edit only what's different for this client. Consulting firms register one brand per client. **Brand registration is instant.** Registering many brands at once? Use **Import CSV** on the 10DLC page: download the template, fill one row per brand (legal name, EIN, contact, address, website, and an optional internal note of up to 100 characters), match the columns and pick the entity type and use case on the next screen, and every row is checked and priced before any brand is created. **2. Vet Brand with Campaign Verify (\$95 per brand)** Each brand needs verification. You have two paths: * **Already have a Campaign Verify token?** Create the brand from it. On the 10DLC page, open **Create Brand** and choose **From Campaign Verify token**, paste the token, and review the brand that will be created: the committee's name, EIN, address, contact name, email and phone are filled in from the Campaign Verify record (and the website, when the committee gave Campaign Verify one) and every field can be edited. When you submit, the brand is registered and the token is applied as its vetting as soon as the registrar finishes creating the brand, usually within a minute or two; until then the brand page shows the vetting as pending. Token-created brands are always non-profit political brands. A token can also be applied to a brand you registered earlier, from the 10DLC page or the brand's page, including a brand whose identity The Campaign Registry could not verify on its own: that is exactly what the token is for. * **Don't have one yet?** Submit the verification request directly inside Political Comms. Our Campaign Verify integration handles the FEC or state election filing record submission for you, no need to visit CampaignVerify.org separately. Verification typically completes in **\~2 hours on business days**. Each token is valid for **1 year** and is specific to that candidate. **3. Create Campaign ($30 for 3 months, then $10/month per campaign)** Register campaigns under each brand (e.g., "GOTV 2024", "Fundraising"). A single brand can have multiple campaigns. Include sample message scripts and description. Campaigns typically **approve in 2 business days** (faster if expedited). **4. Add Phone Number** Provision phone numbers and assign to approved campaigns. Phone number costs vary by pricing tier. Numbers ready immediately once campaign approves. **5. Start Sending** Once approved, start sending messages immediately. Repeat this process for each additional candidate/client you manage. **Total setup time: 2–3 business days per brand.** ## Campaign statuses The 10DLC page shows where each campaign stands: | Status | What it means | | - | - | | Draft | Saved but never submitted. You can finish it or discard it. | | Submitted | Sent for registration, waiting to be picked up. | | Pending | Under review. Approval typically takes about 2 business days. | | Active | Approved and ready to carry traffic. | | Rejected | Needs changes. Edit the campaign and resubmit. | | Failed | Registration did not complete. | | Expired | The registration has lapsed and billing stops. Register a new campaign to keep sending. Its numbers are held for 30 days and can be moved to the new campaign from the 10DLC page. | | Suspended | Suspended by the registrar or a carrier. It cannot send or be used on a project until the suspension is lifted. | Phone numbers show their own state: **Pending** (waiting on its campaign), **Active** (ready to send), or **Parked** (held after its campaign expired; move it to a campaign to use it again). To stop paying for a campaign or number, use **Billing > Subscriptions** (see [Billing](/help/billing)). ## Pro tips > [!TIP] > > * **Consulting firms:** Register each candidate as a separate brand. > * **Individual candidates:** Register one brand for your campaign. > * Each brand can have multiple campaigns underneath it. > * Brand registration is **instant** - no waiting. > * Campaign Verify typically completes in **\~2 hours on business days**. > * Campaign approval can be **expedited** if needed. > * If a brand fails registration, the brand page shows the failure reasons in plain language and lets you **edit and resubmit free of charge** - only brand-new registrations are billed. > * Enable the **"10DLC campaign rejected" notification** (Admin, then Notifications) to hear about a rejection at any stage the moment it happens. ## Next step While waiting for campaign approval, you can set up contact lists and draft messages. Repeat this process for each candidate/client you manage. Learn more in the [Compliance section](/compliance/campaign-registry). > [card] [Step 3: Upload & Organize Contacts](/onboarding/contacts) > > Import voter lists, run carrier lookup, and segment for targeted messaging. # Step 1: Account Setup & Organization Profile Source: https://docs.politicalcomms.com/onboarding/account-setup Confirm your organization profile, add funding, and turn on auto-recharge from the /onboarding page - typically 5-10 minutes. > [!NOTE] > > **Estimated time:** 5-10 minutes ## Overview When your organization becomes active, you land on **`/onboarding`**, a checklist built from your live account status: three steps for most organizations, two for a sub-organization whose funding is managed by its agency. The same checklist stays reachable any time from the dashboard until every step is done. **1. Business profile** **Required.** Your organization's name, entity type, industry vertical, organization address, and account contact. Most of it is already filled in from registration; you typically add the entity type and vertical. Legal name (if it differs from the organization name), DBA, EIN, and website are optional. **2. Funding** **Required.** A saved payment method, a credit limit, or funds added to your wallet at any point satisfies this step, and it stays satisfied even if the balance is later spent to zero. If your organization is a sub-organization of an agency that manages your billing, you cannot save a card: the step names the agency, and their team adds balance for you from **Admin > Organizations**. That counts. **3. Auto-recharge** **Recommended, never required.** Turn on auto-recharge so a low balance doesn't interrupt a send. See [Billing & Auto-Recharge](/help/billing) for how thresholds and recharge amounts work. This step does not appear for sub-organizations whose billing is managed by their agency; there is no card to recharge from. ## The organization profile powers prefill Everything in the business profile is the organization record on **Admin > Organization > General** and can be reused instead of retyped. The 10DLC brand form and the toll-free verification form each carry a **"Use organization business profile"** button that prefills the name, address, contact, and EIN and website when you have entered them. You can still edit the prefilled fields per brand or per verification if a particular registration needs different details (for example, a consulting firm registering a client under its own legal name). ## The 14-day grace window A new organization gets **14 days** from the day it becomes active to finish the business profile and funding steps (existing organizations at the time this requirement shipped got 14 days from the deploy date). During the window, everything works normally regardless of onboarding status. **After the window**, if the business profile or funding step is still incomplete, the platform blocks creating new things until you finish onboarding: * 10DLC brands and campaigns * Toll-free verifications * Phone number purchases * Email sending domains and sender identities * New projects, project copies, and new email campaigns or campaign duplicates (dashboard and the public API alike, including `POST /v1/projects`, `POST /v1/projects/{id}/copy`, and `POST /v1/email/campaigns`) Nothing that is already running is touched. Scheduled and in-flight sends, existing phone numbers, chat, and conversations all keep working; nothing is paused, suspended, or removed. The block only stops you from starting something new. A blocked request returns `403` with a machine-readable code: ```json theme={null} { "error": "Complete your account setup to continue", "code": "ONBOARDING_INCOMPLETE", "details": { "missingSteps": ["profile", "funding"], "onboardingUrl": "/onboarding" } } ``` See [`ONBOARDING_INCOMPLETE`](/api-reference/errors#common-error-codes) in the error reference. The auto-recharge step never gates anything - it's a recommendation, not a requirement. Owners and admins get reminder emails on **day 7** and **day 12** of the grace window if profile or funding is still outstanding, so there's warning before anything is blocked. When a sub-organization's funding is managed by its agency, the agency's owners and admins get the same reminder naming the sub-organizations that still need funds. ## No identity verification vendor Onboarding does not add an identity verification step of its own. The identity checks you already know stay exactly as they are: TCR brand vetting, Campaign Verify, and toll-free verification. The business profile just gives those forms a single place to pull accurate details from instead of retyping them each time. ## Tasks to complete **1. Complete the business profile** From **`/onboarding`** (or **Admin > Organization > General**), confirm the organization name, address, and account contact carried over from registration, then choose the entity type and industry vertical. Add the legal name if it differs from the organization name, a DBA, your EIN/Tax ID, and website if you have them. **2. Add funding** Add a payment method under **Billing > Payment Methods**, or add wallet balance directly. Sub-organizations whose billing is managed by an agency ask the agency to add balance; the wizard names who that is. **3. Turn on auto-recharge (recommended)** Set a minimum balance threshold and recharge amount so campaigns don't stall waiting on a manual top-up. **4. Add team members** Invite team members with appropriate roles: **Admin** (full control), **Manager** (create campaigns), **Agent** (send messages), or **Viewer** (read-only access). If someone already has a Political Comms account elsewhere, use "Invite existing user" instead of creating a new one; entering an email that already exists on the platform does the same thing instead of failing. Either way they're added right away, with nothing to accept; they just sign in as usual. See [Organizations and memberships](/help/organizations-and-memberships) for details. **5. Configure settings** Set your timezone, notification preferences, and branding options (logo, colors) if available for your tier. ## Pro tips > [!TIP] > > * Use your **official campaign/organization name** exactly as it appears on FEC or state election filings, both in the business profile and later on the brand form. > * The organization address should be the one on your IRS or FEC filings; carrier registrations are prefilled from it. > * Finish the profile first: the brand and toll-free verification forms' "Use organization business profile" button saves you from retyping the same details. > * Add multiple team members early to distribute workload efficiently. ## Next step > [card] [Step 2: 10DLC Brand & Campaign Registration](/onboarding/10dlc-registration) > > Once your profile is complete, you're ready to start 10DLC registration. # Step 3: Upload & Organize Contacts Source: https://docs.politicalcomms.com/onboarding/contacts Import lists of phone numbers and emails via CSV, validate with carrier lookup, segment for targeting, and manage do-not-contact lists. > [!NOTE] > > **Estimated time:** 15–30 minutes ## Overview Import your lists and organize them for targeted messaging. One list can hold phone numbers, emails, or both, and every list is on one page: **Assets > Lists**. Each list card shows its phone numbers and, when it has emails, an Emails section with the total, sendable, unsubscribed, and bounced counts and a quality grade. Deleting a list removes its phone numbers and its emails. Use carrier lookup to validate numbers and filter out landlines. ## Tasks to complete **1. Prepare Your Contact List (CSV)** Format as CSV with a phone number column (10-digit format), an email column, or both, and any other columns you want to use as merge tags, such as first name, last name, city, state, and zip. Use a clear header on every column. One list holds phone numbers and emails together, so there is no need to split a file by channel. **2. Upload Contacts** Navigate to **Assets > File Uploads**. Under **Upload to**, choose who owns the files (a brand, a registration, a short code, a shared number, or Global), then drop up to 10 files at once. Files are sorted for you: CSV and TXT files become lists, images and videos go to the media library, and a mixed drop is fine. Your list files share one setup card. Under **What is this?**, choose **Audience** (people to send to) or **Do not contact** once for the batch. For each file, choose the phone column, the email column, or both; they are pre-filled from the file, and L2 and Aristotle voter files have their cell phone column found for you. The emails belong to the whole organization the list is uploaded to. For an audience with an email column, one unchecked checkbox, **This list was purchased or rented**, marks a purchased or rented list, which is sent more gradually. By default every other column becomes a merge tag automatically; you can choose which columns to map instead (see [Merge tags from your columns](#merge-tags-from-your-columns)). Maximum 1 million rows per upload. Phone number format is checked automatically. **3. Run Carrier Lookup (Recommended)** Enable carrier lookup during import to identify landlines, validate numbers, and detect carrier information. Prevents wasted sends to landlines. A list cannot be used on a project until its analysis finishes. **4. Create Contact Segments** Organize contacts into groups based on location, voter data, or custom fields for targeted campaigns. **5. Manage Opt-Outs** STOP replies are recorded automatically and applied to every send. To add your own do-not-contact file, upload it and choose **Do not contact**: its phone numbers become an opt-out list and its emails are recorded as unsubscribes in the background (minutes for a large file). Both show under **Assets > Lists > Do not contact**. ## Pro tips > [!TIP] > > * Always run **carrier lookup** to filter landlines before sending - it saves money. > * Keep opt-out lists clean - never message opted-out contacts. > * Use **custom fields** to store voter data, polling responses, or donation history. > * Segment contacts **before** creating projects for better targeting. > * Raising money on WinRed? Create a **WinRed list** under **Assets > Lists** and paste the generated webhook URL into WinRed's integration settings - donors and leads flow into the list automatically, with donor details available as merge tags. A WinRed or Anedot feed is one list: its donors' phone numbers and emails are on the same list. > * Use the **By Area Code** segment operation to carve a list geographically, and **org-wide segments** ("All brands" / "All projects") to build audiences like "everyone who clicked a link in any project." ## Merge tags from your columns When you upload a list, **Map all columns automatically** is selected, and every column except the phone and email columns becomes a merge tag. * A column whose header matches a standard field gets the standard tag. Standard fields are first name, last name, address, address line 2, city, state, and zip. Common aliases match too, such as "First", "FName", and "Zip Code". A first name column gets `{first_name}`. * Every other column gets a tag named after its header, in lowercase with underscores. `SURVEY_LINK` becomes `{survey_link}` and `Donor Tier` becomes `{donor_tier}`. * A header that starts with a digit gets a `field_` prefix, so `2024 Vote` becomes `{field_2024_vote}`. * A name that would repeat gets a numeric suffix, such as `_2`. To decide for yourself, select **Choose which columns to map**. Only the columns you map get a merge tag. If you map none, all columns are mapped automatically. The list's page has a **Fields** section that shows each column and its merge tag. Select **Edit fields** to rename a tag, switch a column to a standard tag, or remove a tag. This works for uploaded lists and segments. This applies to lists created from now on. Lists you uploaded earlier are unchanged. Do not contact uploads have no merge tags. Importing through the API? See `merge_tags` on [Import List](/api-reference/introduction). Reading a list through the API returns its available merge tags. ## Segment and split by carrier In the Segment Builder, the **By Carrier** operation groups a list by mobile carrier: AT\&T, Verizon, T-Mobile, Other carriers, and Unknown, each with its contact count. It combines with the other operations, so you can, for example, keep one area code and only Verizon numbers. On an analyzed list's page, the **Split by carrier** card creates one new list for each carrier you select. The new lists keep the source list's analysis, so there is no second analysis charge. A list that has not been analyzed shows all of its contacts under Unknown; run carrier lookup first to get real groups. ## Next step > [card] [Step 4: Create Your First Messaging Project](/onboarding/first-project) > > With contacts organized, you're ready to create your first messaging project. # Step 4: Create Your First Messaging Project Source: https://docs.politicalcomms.com/onboarding/first-project Build a project, compose your message with personalization, add media, set up quick replies, send tests, and queue for sending. > [!NOTE] > > **Estimated time:** 20–30 minutes ## Overview Projects are individual messaging campaigns with specific goals (GOTV, fundraising, event invites, etc.). Create your first project, compose messages, and test before sending. ## Tasks to complete **1. Create New Project** Navigate to **Projects → Create New**. Enter project name, description, and select your target contact segment. **2. Compose Your Message** Write your initial message. Use merge fields like `{{firstName}}` and `{{city}}` for personalization. Keep it conversational and include sender identification. **3. Add Media (Optional)** Upload images, videos, or audio to your Media Library and attach to messages for higher engagement (MMS). **4. Set Up Quick Replies** Create template responses for common questions or replies. Speeds up two-way conversations. **5. Send Test Messages** Add team phone numbers to a test segment and send trial messages. Verify formatting, personalization, and media rendering. **6. Schedule or Queue for Sending** Choose to send immediately or schedule for specific date/time. Messages queue for agent sending (P2P requires human initiation). ## Pro tips > [!TIP] > > * Keep first messages **short and conversational** with a clear call-to-action. > * Include sender identification: `"This is [Name] with [Campaign]..."`. > * The platform appends the `"STOP=END"` opt-out footer automatically (and warns if you type your own opt-out language), so you don't need to include it yourself. Broadcast projects can disable the footer in the composer or via `opt_out_footer_enabled` on the API; only do this if your message carries its own compliant opt-out language. > * Test messages on **multiple devices** (iPhone, Android) before full send. > * **Start small** - send to 100–500 contacts first, refine based on responses. ## Next step > [card] [Step 5: Monitor, Engage, and Optimize](/onboarding/monitoring) > > After launching your project, monitor responses and engagement in real-time. # Step 5: Monitor, Engage, and Optimize Source: https://docs.politicalcomms.com/onboarding/monitoring Track delivery, respond to replies, manage opt-outs, analyze performance, and iterate on what works. > [!NOTE] > > **Estimated time:** Ongoing ## Overview Once messages are sending, actively monitor delivery rates, respond to replies, and optimize based on engagement. Use analytics to improve future campaigns. ## Tasks to complete **1. Monitor Real-Time Dashboard** Watch delivery status, reply rates, opt-outs, and message performance on the project dashboard. Identify issues quickly. **2. Respond to Replies** Use the **Conversations** view to see threaded replies. Respond personally or use quick reply templates. Track conversation history. **3. Handle Opt-Outs** System automatically processes STOP keywords. Review opt-out list daily and never re-contact opted-out numbers. **4. Analyze Performance** Review delivery rates, response rates, link clicks, and engagement metrics. Export reports for team review. **5. Iterate and Improve** Learn from each campaign. Test different message styles, sending times, and personalization strategies. Refine based on data. ## Pro tips > [!TIP] > > * Respond to replies **within 30 minutes** for best engagement. > * Track which messages get the best response rates and **replicate**. > * Monitor opt-out rates - if **>2%**, review message content and targeting. > * Use **click tracking** to measure call-to-action effectiveness. > * Document what works for future campaigns (templates, timing, segments). ## You're fully operational > [!TIP] > > You're now fully operational! Continue refining your campaigns and exploring advanced features. > [card] [Browse the Help Center](/help/getting-started) > > Deep dives on features, billing, and best practices. > [card] [Integrate with the API](/api-reference/introduction) > > Stream events, manage projects programmatically, and pull analytics. # Onboarding Guide Source: https://docs.politicalcomms.com/onboarding/overview Get up and running in 2-3 business days. Five sequential steps from account setup to sending your first message. This guide walks you through every step you need to take to go from "just signed up" to "sending your first compliant campaign" - typically in **2–3 business days**. > [card] 2–3 days > > Typical end-to-end setup time per brand. > [card] 5 steps > > Account setup → 10DLC → Contacts → First project → Monitoring. > [card] \$129.50 > > Per-brand initial setup cost ($4.50 + $95 + \$30 first 3 months). > [!NOTE] > > **10DLC Registration Pricing (per brand)** > > | Item | Cost | Notes | > | - | - | - | > | Brand Registration | **\$4.50** | One-time, instant | > | Campaign Verify Token | **\$95.00** | One-time, valid for the current two-year election cycle | > | First Campaign | **\$30.00** | Covers the first 3 months | > | Ongoing Campaign Fee | **\$10.00 / month** | Per campaign, after initial 3 months | > | **Total Initial Setup** | **\$129.50** | Per brand | > > Consulting firms managing multiple candidates multiply these costs by the number of brands (one brand per candidate). Phone numbers are billed separately based on your pricing tier. > [!NOTE] > > **Email Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Email sending | **\$3.00 / 1,000 emails** | \$0.003 per recipient. Lower with volume. | > | Full-service email sending | **\$0.01 per email** | Our team builds and sends every campaign. Lower with volume. No monthly fee. | > | Full-service email setup | **\$1,000 one-time** | Domain authentication, DNS records, warm-up, and list import. | > | Sending domains | **Free** | Unlimited domains and From addresses. | > | Hosted unsubscribe and preferences | **Free** | Included with every send. | > | Dedicated IP pool add-on | **\$35.00 / month per sending domain** | Optional dedicated managed sending IP pool for one sending domain. Warm-up usually takes up to about six weeks, depending on your volume. | > | AI email draft (Lincoln) | **\$3.00 per draft** | AI-drafted email template from a prompt, images and brand colors. | > > Test sends are real sends and are billed at the same per-recipient rate. Email charges appear in the ledger under the Email family and roll up through the organization hierarchy like texting. > [!NOTE] > > **Domain Pricing** > > | Item | Cost | Notes | > | - | - | - | > | Domain registration | **Registrar's price** | One year. Prices vary by ending, shown before you buy. Non-refundable once registered; refunded if registration never happens. | > | Domain hosting fee | **\$6.00 / year** | Flat. Covers the DNS records we write and keep current for the domain. | > | App or link-tracking host setup | **Normal setup fee** | One per host. | > > Charged from your wallet at purchase and renewed yearly, 30 days before the domain expires. Dashboard only. ## The five steps **1. Account Setup & Organization Profile** Complete the required business profile and funding steps on `/onboarding`, invite teammates with role-based permissions, set your timezone and notification preferences, and turn on optional auto-recharge. **Estimated time: 10–15 minutes.** [Walk through Step 1 →](/onboarding/account-setup) **2. 10DLC Brand & Campaign Registration** Register each candidate/campaign as a brand with The Campaign Registry, vet with Campaign Verify, create your first campaign under that brand, and provision phone numbers. **Estimated time: 2–3 business days per brand.** [Walk through Step 2 →](/onboarding/10dlc-registration) **3. Upload & Organize Contacts** Import voter lists via CSV, run carrier lookup to filter landlines, create segments for targeted messaging, and clean up opt-out lists. **Estimated time: 15–30 minutes.** [Walk through Step 3 →](/onboarding/contacts) **4. Create Your First Messaging Project** Build a project, compose with personalization merge fields, add MMS media if desired, set up quick replies, run test sends, and queue for delivery. **Estimated time: 20–30 minutes.** [Walk through Step 4 →](/onboarding/first-project) **5. Monitor, Engage, and Optimize** Watch live delivery and reply metrics, respond to conversations, manage opt-outs, analyze performance, and iterate on what works. **Estimated time: Ongoing.** [Walk through Step 5 →](/onboarding/monitoring) ## Other resources > [card] [Help Center & FAQ](/help/getting-started) > > Common questions and best practices. > [card] [Compliance Guide](/compliance/overview) > > TCPA, CTIA, 10DLC, and Campaign Verify in depth. > [card] [API Reference](/api-reference/introduction) > > REST endpoints, webhooks, and authentication.