> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Email Template
> 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.
**Early access.** This endpoint returns `403 EMAIL_EARLY_ACCESS` until the email product reaches general availability. The contract below is stable and safe to build against.
## OpenAPI
````yaml /api-reference/openapi.json post /email/templates
openapi: 3.1.0
info:
title: Political Comms API
summary: >-
Direct-to-carrier political texting API for campaigns, PACs, advocacy
organizations, fundraisers, and elected officials.
description: >-
Public REST API for the Political Comms platform. Surfaces include Projects
(compose, test, schedule, send), Conversations (read inbound threads and
reply inside them), Contact Lists (S3 import and analysis), Media Files,
Organizations and hierarchy, Brands, Campaigns, Tracking Domains, Phone
Numbers, Analytics, and Billing.
Authentication is an API key passed in the `X-API-Key` header. Keys are
generated from the dashboard at Admin → API and are prefixed `pc_live_`. All
POST and PATCH endpoints that mutate state are designed to be safe to retry,
with optional `Idempotency-Key` headers for stronger guarantees. Rate limit
is 100 requests per minute per key (60-second sliding window; write-only
keys 60/min, delete-only keys 30/min; the `X-RateLimit-Limit` header reports
your key's exact limit).
Webhooks emit `message.sent`, `message.delivered`, `message.failed`,
`message.replied`, and `link.clicked` events. Payloads are HMAC-signed;
validate the signature before trusting any payload.
A Model Context Protocol (MCP) server is available at
https://docs.politicalcomms.com/mcp for AI agents that need to search the
documentation programmatically. The developer hub at
https://politicalcomms.com/developers/ has quickstart examples in cURL, raw
HTTP, and Python.
version: 1.4.0
termsOfService: https://politicalcomms.com/terms/
contact:
name: Political Comms Support
email: support@politicalcomms.com
url: https://docs.politicalcomms.com
license:
name: Proprietary
url: https://politicalcomms.com/terms/
x-logo:
url: https://politicalcomms.com/images/brand/pcomms-logo-left-of-text.png
altText: Political Comms
backgroundColor: '#ffffff'
href: https://politicalcomms.com/
x-mcp:
url: https://docs.politicalcomms.com/mcp
discovery_url: https://docs.politicalcomms.com/.well-known/mcp
transport: http
auth: none
tools:
- search_political_comms
- query_docs_filesystem_political_comms
- submit_feedback
servers:
- url: https://api.politicalcomms.com/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Projects
description: Create, edit, test, schedule, and inspect projects.
- name: Conversations
description: >-
Read inbound threads and reply inside them from the same number.
Conversations are created by project sends; the API never starts one.
- name: Phone Numbers
description: List phone numbers across 10DLC campaigns and toll-free verifications.
- name: Toll-Free Verifications
description: >-
List toll-free verifications (carrier registrations) across your
organization hierarchy.
- name: Brands
description: List brands across your organization hierarchy.
- name: 10DLC Campaigns
description: >-
List 10DLC campaigns (carrier registrations) across your organization
hierarchy.
- name: Email Campaigns
description: >-
Create, schedule, and report on email campaigns. Pause, resume, and test
sends are deliverability decisions a human makes while watching a send,
and live in the dashboard. **Early access:** this endpoint answers `403
EMAIL_EARLY_ACCESS` until the email product is generally available.
- name: Email Templates
description: >-
Create and read saved email templates. **Early access:** this endpoint
answers `403 EMAIL_EARLY_ACCESS` until the email product is generally
available.
- name: Email Senders
description: >-
Read the sender identities (From addresses) on your verified domains.
Identities carry the physical mailing address and paid-for-by disclaimer,
so they are created and edited in the dashboard. **Early access:** this
endpoint answers `403 EMAIL_EARLY_ACCESS` until the email product is
generally available.
- name: Email Suppressions
description: >-
Read, add, and lift suppressions in bulk. This is the primitive for
keeping your own opt-out record in sync with ours. **Early access:** this
endpoint answers `403 EMAIL_EARLY_ACCESS` until the email product is
generally available.
- name: Contact Lists
description: List, import, and analyze contact lists.
- name: Email Lists
description: >-
Create email lists, read their contacts, and bulk-upsert or import
addresses. To stop mailing someone use Email Suppressions, which survives
a re-import. **Early access:** this endpoint answers `403
EMAIL_EARLY_ACCESS` until the email product is generally available.
- name: Media Files
description: List, import, and fetch media files.
- name: Sending Domains
description: >-
Read the sending domains in your organization and the DNS records to
publish. Domains are added in the dashboard: DNS is published by hand, so
creation is not part of the API. **Early access:** this endpoint answers
`403 EMAIL_EARLY_ACCESS` until the email product is generally available.
- name: Tracking Domains
description: >-
List active link-tracking domains. Use the returned ids as
`link_tracking_domain_id` on project create/update.
- name: Organizations
description: List descendant organizations and hierarchy.
- name: Billing
description: Usage and billing data across your organization.
- name: Analytics
description: Message statistics and delivery performance.
paths:
/email/templates:
post:
tags:
- Email Templates
summary: Create Email Template
description: >-
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.
**Early access.** This endpoint returns `403 EMAIL_EARLY_ACCESS` until
the email product reaches general availability. The contract below is
stable and safe to build against.
operationId: createEmailTemplate
parameters:
- $ref: '#/components/parameters/IdempotencyKeyHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 255
description:
type: string
maxLength: 2000
content:
type: object
properties:
subject:
type: string
minLength: 1
maxLength: 900
preheader:
type: string
maxLength: 255
html:
type: string
minLength: 1
maxLength: 2097152
text:
type: string
description: >-
Plain-text alternative. Generated from the HTML when
omitted.
maxLength: 512000
required:
- subject
- html
description: >-
The full body. On update this object replaces the stored
content rather than merging into it.
additionalProperties: false
required:
- name
- content
additionalProperties: false
example:
name: Fall fundraising
description: Evergreen ask, brand colors
content:
subject: Can you chip in before Friday?
preheader: Every gift is matched through midnight.
html: >-
Hi {first_name|Friend}
Chip in
today.
responses:
'201':
description: Template created.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
allOf:
- $ref: '#/components/schemas/EmailTemplate'
- type: object
properties:
lint:
$ref: '#/components/schemas/EmailTemplateLint'
required:
- success
- data
additionalProperties: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
IdempotencyKeyHeader:
name: Idempotency-Key
in: header
required: false
schema:
type: string
minLength: 16
maxLength: 200
description: >-
Optional idempotency key: a unique string of 16-200 printable ASCII
characters (a UUID is recommended). Retrying the write with the same key
within 24 hours returns the stored response of the first call with an
`X-Idempotent-Replayed: true` response header instead of executing it
again. Reusing a key with a different request body returns `422`
(`IDEMPOTENCY_MISMATCH`); a duplicate sent while the first call is still
running returns `409` with a `Retry-After` header. Keys are scoped per
endpoint and organization.
schemas:
EmailTemplate:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
maxLength: 255
description:
type:
- string
- 'null'
maxLength: 2000
content:
$ref: '#/components/schemas/EmailTemplateContent'
thumbnail_url:
type:
- string
- 'null'
description: Preview image rendered by a background job. Null until it has run.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- name
- content
description: A reusable email design in the organization's template library.
additionalProperties: true
EmailTemplateLint:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
warnings:
type: array
items:
type: object
additionalProperties: true
description: >-
Content lint result returned alongside every template write. A template
with lint errors saves, but a campaign using it will not schedule, so
read this on the write rather than discovering it at schedule time.
Warnings do not block.
additionalProperties: true
EmailTemplateContent:
type: object
properties:
subject:
type:
- string
- 'null'
maxLength: 900
preheader:
type:
- string
- 'null'
maxLength: 255
html:
type:
- string
- 'null'
maxLength: 2097152
text:
type:
- string
- 'null'
description: Plain-text alternative. Generated from the HTML when omitted.
maxLength: 512000
editor:
type: string
enum:
- html
- document
description: >-
`html` for a template imported or hand-written as HTML; `document`
for one built in the dashboard's document editor. Both are returned
as rendered HTML here. This surface only accepts HTML content on
create. Updating the `content` of a `document` template returns `409
CONFLICT` with `details.reason` set to `TEMPLATE_IS_DOCUMENT`: edit
it in the dashboard, or convert it to an HTML template first.
description: The renderable body of a template.
additionalProperties: true
ErrorResponse:
type: object
properties:
error:
type: string
description: Human-readable error message.
code:
type: string
description: >-
Machine-readable error code, e.g. VALIDATION_ERROR,
ORG_ACCESS_DENIED, PROJECT_NOT_FOUND.
correlationId:
type: string
description: Request correlation ID; include it in support requests.
details:
type:
- array
- object
description: >-
Present on some errors. An array of field-level issues for
VALIDATION_ERROR; an object for other codes (e.g.
insufficient-balance shortfall).
required:
- error
- code
additionalProperties: true
description: >-
Standard error body produced by the API error handler for 4xx/5xx
responses.
AuthErrorResponse:
type: object
properties:
error:
type: string
description: Short error summary.
message:
type: string
description: Human-readable detail.
required:
- error
- message
additionalProperties: true
description: >-
Error body returned by the API-key authentication layer (401 and
permission 403s).
RateLimitErrorResponse:
type: object
properties:
success:
type: boolean
enum:
- false
error:
type: string
message:
type: string
code:
type: string
enum:
- RATE_LIMIT_EXCEEDED
statusCode:
type: integer
enum:
- 429
retryAfter:
type: integer
description: >-
Seconds until the rate-limit window resets. Also sent as the
Retry-After header.
required:
- success
- error
- code
- statusCode
- retryAfter
additionalProperties: true
responses:
BadRequest:
description: >-
Invalid request (validation failure, malformed parameters, or a request
the resource state does not allow).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Validation failed
code: VALIDATION_ERROR
correlationId: 030bf857-922f-4b82-8fca-c5b0769c1590
details:
- code: invalid_format
format: uuid
path:
- organization_id
message: Invalid UUID
Unauthorized:
description: Missing, malformed, revoked, or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthErrorResponse'
example:
error: API key required
message: Please provide an API key in the X-API-Key header
Forbidden:
description: >-
The API key lacks the required permission scope, or the requested
resource belongs to an organization outside the key's hierarchy.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AuthErrorResponse'
- $ref: '#/components/schemas/ErrorResponse'
examples:
missingScope:
summary: Key lacks the required permission scope
value:
error: Insufficient permissions
message: >-
This API key does not have the required permissions:
public:read
orgAccessDenied:
summary: Resource outside the key's organization hierarchy
value:
error: >-
Access denied: You do not have permission to access this
organization's data
code: ORG_ACCESS_DENIED
correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
NotFound:
description: Resource not found or not visible to this API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Project not found
code: PROJECT_NOT_FOUND
correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
RateLimited:
description: Rate limit exceeded. Check the Retry-After header.
headers:
Retry-After:
description: Seconds until the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitErrorResponse'
example:
success: false
error: Rate limit exceeded
message: Maximum 100 requests per 60 seconds
code: RATE_LIMIT_EXCEEDED
statusCode: 429
retryAfter: 1800
InternalError:
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: An unexpected error occurred. Please try again later.
code: INTERNAL_ERROR
correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
Authenticate every request by passing your API key in the X-API-Key
header. Keys are scoped to your organization hierarchy.
````