Marketing Email API

The Marketing Email API manages high-volume marketing and transactional email campaigns through providers including SendGrid, Brevo, AWS SES, and Mailchimp. It handles audience segmentation, SPF/DKIM domain verification, dynamic personalization, and tracking webhooks.

BASE URL: /api/marketing

Endpoints Summary

Method	Path	Description	Access
`GET`	`/api/marketing/campaigns`	List email campaigns with pagination and filters	Marketing / Admin
`POST`	`/api/marketing/campaigns`	Create and schedule a new email campaign	Marketing / Admin
`POST`	`/api/marketing/campaigns/draft`	Save an unfinished email campaign draft	Marketing / Admin
`POST`	`/api/marketing/audience-preview`	Filter and preview target email recipient count	Marketing / Admin
`POST`	`/api/marketing/campaigns/cost-estimate`	Estimate sending costs based on volume	Marketing / Admin
`POST`	`/api/marketing/campaigns/send-test`	Send a test rendering to an internal email	Marketing / Admin
`GET`	`/api/marketing/campaigns/:id`	Fetch email campaign configuration and HTML body	Marketing / Admin
`POST`	`/api/marketing/campaigns/:id/dispatch`	Launch campaign via BullMQ worker queue	Marketing / Admin
`GET`	`/api/marketing/campaigns/:id/analytics`	Open rates, click maps, bounces, and unsubscribes	Marketing / Admin
`GET`	`/api/marketing/campaigns/:id/recipients`	Paginated recipient engagement status log	Marketing / Admin
`POST`	`/api/marketing/recipients/:recipientId/promote`	Convert active email opener to CRM Lead	Marketing / Admin
`DELETE`	`/api/marketing/campaigns/:id`	Delete an email campaign	Marketing / Admin

Team Inbox Message Scheduling

Method	Path	Description	Access
`POST`	`/api/marketing/email/inbox/schedule`	Schedule a 1-on-1 email for future dispatch	Authenticated
`PATCH`	`/api/marketing/email/inbox/reschedule/:id`	Update target scheduled dispatch timestamp	Authenticated
`PATCH`	`/api/marketing/email/inbox/edit/:id`	Edit email subject, body, or scheduled time	Authenticated
`DELETE`	`/api/marketing/email/inbox/cancel/:id`	Cancel a pending scheduled email message	Authenticated
`POST`	`/api/marketing/email/inbox/send-now/:id`	Immediately send a scheduled email ahead of time	Authenticated

Create Email Campaign

POST /api/marketing/campaigns

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Campaign internal title
`subject`	`string`	Yes	Email subject line with optional merge tags
`previewText`	`string`	No	Inbox preview preheader snippet
`fromName`	`string`	Yes	Sender display name (e.g. `BrokerOS Luxury Collection`)
`fromEmail`	`string`	Yes	Verified sender email (e.g. `sales@properties.yourfirm.com`)
`replyTo`	`string`	No	Destination email for direct client replies
`htmlContent`	`string`	Yes	Responsive HTML email body
`projectId`	`string`	No	Target project UUID
`audienceSource`	`string`	Yes	`CRM_LEADS` or `CSV_UPLOAD`
`targetCriteria`	`object`	No	Status, temperature, or budget filters

Request Example

{
  "name": "Emerald Heights - Tower B Official Unveiling",
  "subject": "Exclusive Preview: Luxury 3BHK Homes in Whitefield",
  "previewText": "Private invitation for priority booking this weekend",
  "fromName": "Emerald Heights Sales Team",
  "fromEmail": "sales@emeraldheights.com",
  "replyTo": "concierge@emeraldheights.com",
  "htmlContent": "<html><body><h1>Hello {{firstName}},</h1><p>You are cordially invited...</p></body></html>",
  "projectId": "cm123proj001",
  "audienceSource": "CRM_LEADS",
  "targetCriteria": {
    "leadStatuses": ["CONTACTED", "INTERESTED"],
    "leadTemperatures": ["HOT", "WARM"]
  }
}

Send Test Email

POST /api/marketing/campaigns/send-test

Sends an immediate preview email to your inbox to check layout rendering across desktop and mobile clients (Apple Mail, Gmail, Outlook).

Request Body

{
  "toEmail": "marketing.lead@yourfirm.com",
  "subject": "[TEST PREVIEW] Exclusive Preview: Luxury 3BHK Homes",
  "htmlContent": "<html>...</html>",
  "sampleData": {
    "firstName": "Rahul",
    "project": "Emerald Heights"
  }
}

Dispatch Campaign

POST /api/marketing/campaigns/:id/dispatch

Transitions campaign status to SENDING and delegates email batch processing to apps/workers/src/marketing-email.processor.ts.

Analytics & Engagement

GET /api/marketing/campaigns/:id/analytics

Response Example

{
  "campaignId": "cm123email001",
  "totalSent": 3450,
  "delivered": 3410,
  "bounced": 40,
  "opened": 1420,
  "uniqueOpens": 1180,
  "openRate": "34.6%",
  "clicked": 420,
  "uniqueClicks": 380,
  "clickThroughRate": "11.1%",
  "unsubscribed": 8,
  "spamComplaints": 0
}

System Architecture

API Reference

Marketing Email API

Endpoints Summary

Team Inbox Message Scheduling

Create Email Campaign

Request Body

Request Example

Send Test Email

Request Body

Dispatch Campaign

Analytics & Engagement

Response Example

​Endpoints Summary

​Team Inbox Message Scheduling

​Create Email Campaign

​Request Body

​Request Example

​Send Test Email

​Request Body

​Dispatch Campaign

​Analytics & Engagement

​Response Example

Endpoints Summary

Team Inbox Message Scheduling

Create Email Campaign

Request Body

Request Example

Send Test Email

Request Body

Dispatch Campaign

Analytics & Engagement

Response Example