Communications Block

The Communications Block is Motorical's marketing / bulk email API — campaigns, segmentation, templates, suppressions, and analytics on top of Motorical sending infrastructure. It provides professional email marketing capabilities while maintaining deliverability, compliance, and security.

:::info Plan Requirement Communications Block requires Business Plan or higher. :::

:::tip Which Motor Block type do I need? Receipts, password resets, one-to-one mail → transactional block (SMTP or POST /v1/send). Newsletters, campaigns, lists → marketing block, sent through Communications.

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. :::

Key Features

Campaign Management

• Contact lists and segmentation
• HTML/text email templates with merge variables
• Smart campaign scheduling with timezone handling
• Real-time delivery tracking

Compliance & Security

• CAN-SPAM compliance with automatic unsubscribe handling
• GDPR data protection (Article 17 & 20)
• CCPA compliance
• Customer-scoped suppressions
• Audit logging and reporting

Module Architecture

Communications Block runs as a separate microservice alongside the Motorical core. It reuses the same delivery engine, reputation stack, and analytics, but keeps marketing traffic isolated from your transactional SMTP flows.

This design lets you adopt marketing features incrementally — you can enable the module for specific domains or Motor Blocks without changing how your core email is delivered.

High-Level Flow

1. You create a campaign in Communications Block (lists + template + schedule)
2. Sender worker writes emails into the shared delivery queue (email_delivery_queue)
3. The Email Delivery Engine and Postfix deliver those emails using the same paths as transactional mail
4. Analytics and reputation services track both marketing and transactional traffic, but policies can be applied per Motor Block

Architecture Components

Motorical Core:

• Backend API, Frontend, SMTP Gateway
• Email Delivery Engine (processes delivery queue for all email types)
• Analytics & Reputation (shared metrics and enforcement engine)

Communications Block Module:

• Comm API (Port 3011) — Campaigns, templates, lists, suppression logic
• Communications DB — Isolated schema for marketing data
• Sender & Stats Workers — Push emails to the queue and process statistics

The module lives in its own repository (github.com/motorical-smtp/communications-block) so it can evolve independently while your core SMTP infrastructure stays stable.

Find your workspace ID

Every Communications API request needs your workspace ID in the X-Tenant-Id header. There are two ways to get it.

In the dashboard. Open Comm → Workspaces. The workspace ID is shown there with a copy button.

Via the API. Call GET https://api.motorical.com/api/comm/tenant with your account API key (ak_live_..., created under Settings → Account API Keys) or a dashboard JWT (Authorization: Bearer ...):

curl https://api.motorical.com/api/comm/tenant \
  -H "Authorization: ApiKey ak_live_YOUR_KEY"

{
  "success": true,
  "data": {
    "tenantId": "3f6c1a2e-0000-0000-0000-000000000000",
    "workspaces": [
      { "id": "3f6c1a2e-0000-0000-0000-000000000000", "name": "Default" }
    ]
  }
}

tenantId is your default workspace. Any other workspaces on the account are listed in workspaces; use the id of the one you want as X-Tenant-Id. Each workspace item carries more fields than shown here; only id and name are needed. Workspaces require the Business plan or higher, with a soft cap of 10 workspaces per account. Accounts below the Business plan get a 403 response with "requiresUpgrade": true from GET /api/comm/tenant.

Getting Started

1. Ensure you have Business Plan or higher
2. Navigate to Communications in your Motorical dashboard
3. Your Communications tenant is automatically created on first access
4. Under Workspaces, pick a verified sending domain — Motorical connects it automatically, no separate Motor Block setup needed
5. Create your first contact list
6. Design an email template
7. Launch your campaign