Communications API Reference

Communications Block endpoints are served from:

https://motorical.com/comm-api/api

Every customer-facing endpoint requires your Communications tenant header:

X-Tenant-Id: your-tenant-uuid

Internal provisioning routes and public tracking link callbacks are intentionally excluded from this reference. They are used by Motorical services and email links, not by customer API integrations.

Lists and Contacts

Method	Endpoint	Purpose
GET	/comm-api/api/lists	List contact lists.
POST	/comm-api/api/lists	Create a list.
POST	/comm-api/api/lists/from-filter	Create a smart list from filters.
DELETE	/comm-api/api/lists/{id}	Delete a list.
DELETE	/comm-api/api/lists	Bulk delete lists.
GET	/comm-api/api/lists/{id}/contacts	List contacts in a list.
POST	/comm-api/api/lists/{id}/contacts	Add contacts to a list.
POST	/comm-api/api/lists/{id}/contacts/import	Import contacts from CSV.
GET	/comm-api/api/lists/{id}/contacts/export	Export contacts from a list.
POST	/comm-api/api/contacts/upsert	Create or update a contact.
DELETE	/comm-api/api/contacts/{id}	Delete a contact.
POST	/comm-api/api/contacts/{id}/unsubscribe	Unsubscribe a contact.
PUT	/comm-api/api/contacts/{id}/resubscribe	Resubscribe a contact.

Templates

Method	Endpoint	Purpose
GET	/comm-api/api/templates	List templates.
POST	/comm-api/api/templates/validate	Validate and preview a template without saving.
POST	/comm-api/api/templates	Create a template.
GET	/comm-api/api/templates/{id}	Get template content.
PATCH	/comm-api/api/templates/{id}	Update a template.
DELETE	/comm-api/api/templates/{id}	Delete a template.
DELETE	/comm-api/api/templates	Bulk delete templates.

Campaigns

Method	Endpoint	Purpose
GET	/comm-api/api/campaigns	List campaigns. Supports compact=true.
POST	/comm-api/api/campaigns	Create a campaign.
GET	/comm-api/api/campaigns/{id}	Get campaign details.
PATCH	/comm-api/api/campaigns/{id}/settings	Update campaign settings and schedule metadata.
POST	/comm-api/api/campaigns/{id}/schedule	Schedule a campaign.
POST	/comm-api/api/campaigns/{id}/cancel	Cancel a campaign.
DELETE	/comm-api/api/campaigns/{id}	Soft-delete a campaign.
GET	/comm-api/api/campaigns/deleted	List deleted campaigns.
PATCH	/comm-api/api/campaigns/{id}/restore	Restore a deleted campaign.
DELETE	/comm-api/api/campaigns/{id}/permanent	Permanently delete a campaign.
DELETE	/comm-api/api/campaigns/cleanup	Cleanup old deleted campaigns.
POST	/comm-api/api/campaigns/{id}/compile	Compile campaign template and audience snapshot.
GET	/comm-api/api/campaigns/{id}/events	List campaign delivery events.
GET	/comm-api/api/campaigns/{id}/stats	Campaign statistics.
GET	/comm-api/api/campaigns/{id}/analytics	Campaign analytics summary.
GET	/comm-api/api/campaigns/{id}/click-breakdown	URL-level click analytics.
GET	/comm-api/api/campaigns/{id}/recipients	Campaign recipient list.
GET	/comm-api/api/campaigns/{id}/clicks	Campaign click events.

Recipients

Method	Endpoint	Purpose
GET	/comm-api/api/recipients	Search recipients across lists/campaigns.
GET	/comm-api/api/recipients/campaigns	Campaign recipient grouping data.
POST	/comm-api/api/recipients/filter	Filter recipients with criteria.
POST	/comm-api/api/recipients/export	Export filtered recipients.
POST	/comm-api/api/recipients/bulk-delete	Soft-delete recipients in bulk.
POST	/comm-api/api/recipients/bulk-move	Move recipients between lists.
POST	/comm-api/api/recipients/restore	Restore recipients in bulk.
GET	/comm-api/api/recipients/deleted	List deleted recipients.
PATCH	/comm-api/api/recipients/{id}/restore	Restore one deleted recipient.
DELETE	/comm-api/api/recipients/{id}/permanent	Permanently delete a recipient.
DELETE	/comm-api/api/recipients/cleanup	Cleanup old deleted recipients.

Suppressions

Method	Endpoint	Purpose
GET	/comm-api/api/suppressions	List suppressions.
POST	/comm-api/api/suppressions	Add a suppression.
DELETE	/comm-api/api/suppressions/{id}	Remove a suppression.
POST	/comm-api/api/suppressions/bulk	Bulk import suppressions.
GET	/comm-api/api/suppressions/stats	Suppression statistics.
POST	/comm-api/api/suppressions/import-bounces	Import bounces into suppressions.

Tracking and Unsubscribe Analytics

Method	Endpoint	Purpose
GET	/comm-api/api/tracking/events	Search tracking events.
GET	/comm-api/api/tracking/export	Export tracking events.
GET	/comm-api/api/tracking/stats	Tracking statistics.
GET	/comm-api/api/unsubscribe-events	List unsubscribe events.
GET	/comm-api/api/unsubscribe-analytics	Unsubscribe analytics.
GET	/comm-api/api/unsubscribe-trends	Unsubscribe trends.

Analytics and Data Controls

Method	Endpoint	Purpose
GET	/comm-api/api/analytics/overview	Communications analytics overview.
GET	/comm-api/api/gdpr/export	GDPR data export for a tenant/contact scope.
GET	/comm-api/api/health	Communications API health check.

Response Shape

Most Communications endpoints return:

{
  "success": true,
  "data": {}
}

Validation failures and authorization errors return:

{
  "success": false,
  "error": "Validation failed"
}