Campaign Management

Create, schedule, and monitor email marketing campaigns with real-time delivery tracking.

Campaign Workflow

1. Create Campaign — Name your campaign and configure basic settings
2. Select Template & Lists — Choose an email template and target contact lists
3. Configure Settings — Set sender address, subject line, and scheduling options
4. Schedule Delivery — Send immediately or schedule for a specific time
5. Monitor Performance — Track delivery, opens, clicks, and bounces in real-time

Creating a Campaign

POST /comm-api/api/campaigns
Content-Type: application/json
X-Tenant-Id: your-tenant-uuid

{
  "name": "Monthly Newsletter",
  "template_id": "uuid",
  "list_ids": ["uuid1", "uuid2"],
  "motor_block_id": "uuid"
}

motor_block_id is the id of a Marketing Motor Block assigned to the active workspace under Comm → Workspaces.

A marketing block is a sender identity for Communications (campaigns, lists, templates). It has no SMTP login and no API key of its own. You send through campaigns in the dashboard, or through the Comms Block API with your account API key and a workspace. For transactional email (receipts, password resets) use a transactional block.

	Comms-managed ("… — Campaigns")	Manual (Create dialog)
Sends via	Comms Block: dashboard campaigns, Comms API (account API key + X-Tenant-Id)	Same
Own SMTP / API key	None	None
Created	Automatically when you pick a sending domain in Comm → Workspaces	By you, then assigned under Comm → Workspaces → Advanced
Editable in Motorical dashboard	No (managed from Comm)	Rename, pause, delete

Sending with a manual marketing block

A manual marketing block (one you created yourself in Motor Blocks) is used for sending through a workspace and your account API key. Comms-managed <domain> — Campaigns blocks are assigned to a workspace automatically, so you can skip the assignment step for those.

1. Create and verify the block in Motor Blocks.
2. Go to Comm → Workspaces → Advanced, assign the block to your workspace, and save.
3. Create a campaign with the block's id as motor_block_id.
4. Schedule the campaign.

Your workspace ID is shown at Comm → Workspaces; see Find your workspace ID. You can get the block id in two ways:

• The dashboard prefills it in the "How to send with this block" example shown under each manual block in Comm → Workspaces → Advanced.
• The Comms API lists the marketing blocks assigned to a workspace:

curl https://motorical.com/comm-api/api/workspaces/current/motor-blocks \
  -H "Authorization: ApiKey ak_live_YOUR_KEY" \
  -H "X-Tenant-Id: YOUR_WORKSPACE_ID"

The response is { "success": true, "data": [ ... ] }. Each item has id, name, type, active, and domain ({ name, verified }, or null when the block has no domain). data is an empty array when nothing is assigned yet. Use the id as motor_block_id.

# 1. Create a campaign that sends from this block
curl -X POST https://motorical.com/comm-api/api/campaigns \
  -H "Authorization: ApiKey ak_live_YOUR_KEY" \
  -H "X-Tenant-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"My campaign","template_id":"TEMPLATE_ID","list_ids":["LIST_ID"],"motor_block_id":"YOUR_MOTOR_BLOCK_ID"}'

# 2. Schedule it (use the campaign id returned by step 1)
curl -X POST https://motorical.com/comm-api/api/campaigns/CAMPAIGN_ID/schedule \
  -H "Authorization: ApiKey ak_live_YOUR_KEY" \
  -H "X-Tenant-Id: YOUR_WORKSPACE_ID"

:::note Which key is which The account key ak_live_... is used for Communications and for token minting. mk_live_... keys are for POST /v1/send only; a marketing block has none. :::

Scheduling

POST /comm-api/api/campaigns/{id}/schedule
X-Tenant-Id: your-tenant-uuid

Smart Scheduling Features

• Timezone handling — Schedule campaigns relative to recipient timezones
• Optimal send times — Choose the best time window for your audience
• Rate-limited sending — Chunked delivery maintains sender reputation

Multi-List Targeting

Send to multiple contact lists with automatic deduplication. If a contact appears in multiple selected lists, they receive the campaign only once.

Managing Campaigns

List Campaigns

GET /comm-api/api/campaigns
X-Tenant-Id: your-tenant-uuid

Use compact=true when you need campaign summaries without large compiled artifacts in the response:

GET /comm-api/api/campaigns?compact=true
X-Tenant-Id: your-tenant-uuid

Compact mode keeps campaign status, schedule, sender settings, latest audience snapshot, and a small latest artifact summary, but omits compiled HTML/text bodies.

Get Campaign Details

GET /comm-api/api/campaigns/{id}
X-Tenant-Id: your-tenant-uuid

Update Campaign Settings

PATCH /comm-api/api/campaigns/{id}/settings
Content-Type: application/json
X-Tenant-Id: your-tenant-uuid

{
  "name": "Updated Name",
  "template_id": "new-template-uuid"
}

Cancel a Campaign

POST /comm-api/api/campaigns/{id}/cancel
X-Tenant-Id: your-tenant-uuid

Delete a Campaign

DELETE /comm-api/api/campaigns/{id}
X-Tenant-Id: your-tenant-uuid

Deleted campaigns are soft-deleted and can be restored from the recycle bin.

Campaign Analytics

GET /comm-api/api/campaigns/{id}/analytics?days=7
X-Tenant-Id: your-tenant-uuid

Click Breakdown

Detailed URL-level click analysis:

GET /comm-api/api/campaigns/{id}/click-breakdown
X-Tenant-Id: your-tenant-uuid

Campaign Events

View delivery events with pagination:

GET /comm-api/api/campaigns/{id}/events?page=1&pageSize=25&status=delivered
X-Tenant-Id: your-tenant-uuid

Track these metrics per campaign:

Metric	Description
Delivery Rate	Percentage of emails successfully delivered
Open Rate	Unique and total email opens
Click Rate	Unique and total link clicks
Bounce Rate	Hard and soft bounce percentage
Unsubscribe Rate	Recipients who opted out

Campaign States

State	Description
draft	Campaign created but not scheduled
scheduled	Campaign queued for future delivery
sending	Campaign currently being delivered
completed	All emails in the campaign have been processed
paused	Campaign delivery temporarily halted
cancelled	Campaign cancelled before completion