Skip to main content

Admin Bulk Email Campaign Suite & Template Studio

The Admin Bulk Email Campaign Suite (src/components/feature/admin/bulk-email-tab.tsx) is an enterprise-grade mass communication and template authoring engine. It allows authorized agency administrators to compose, preview, and dispatch rich HTML announcements, commercial policy updates, and newsletters to customer lists.

1. High-Level Campaign Lifecycle​

2. Rich Text Composition & Inline Media Offloading​

2.1 Headless Tiptap Composition​

The email composer integrates Tiptap headless WYSIWYG, supporting headings, bold/italic, bullet lists, numbered lists, blockquotes, hyperlinks, and responsive images.

2.2 Inline Image Offloading Algorithm (extractAndStoreInlineImages)​

Directly embedding multi-megabyte base64 images into email templates bloats MongoDB documents and risks exceeding BSON limits.

  • Interception: When an administrator pastes (Ctrl+V / Cmd+V) or drags an image into the editor, the server action uploadInlineEmailImageAction intercepts the base64 payload.
  • Persistence: The image binary is persisted into the Signature collection.
  • Replacement: The base64 string is replaced with a public streaming URL: /api/signatures/[signatureId].
  • Responsive Email Styles: Automatically styled with max-width: 100% !important; height: auto !important; display: block; to ensure consistent rendering across email clients.

3. Reusable Email Template Studio (EmailTemplate)​

The template studio allows teams to curate a centralized library of branded communications:

  • Attributes: Template name, category (e.g. Commercial Trucking, Personal Auto, Billing, Holiday), subject line, rich HTML body, sign-off text, and designated signature asset.
  • One-Click Application: Selecting a template in the dropdown automatically hydrates the composer with subject, rich HTML body, sign-off text, and auto-selects the associated signature.

4. Audience Management & CSV Recipient Chunking​

The suite supports two methods for populating recipient lists:

  1. Manual Input: Delimiter-separated list (comma, semicolon, or newline).
  2. CSV Upload: Drag-and-drop spreadsheet upload automatically parsed on the client.

Mitigating the 16 MB BSON Document Limit (BulkEmailRecipientChunk)​

For campaigns targeting tens of thousands of subscribers:

  • Recipient items are partitioned into chunk documents (BulkEmailRecipientChunk) of up to 1,000 emails per document.
  • Compound indexing on { campaignId: 1, chunkIndex: 1 } guarantees rapid sequential retrieval during batch execution.

5. Controlled Micro-Batch Dispatch Architecture​

To prevent outgoing rate-limit throttling by upstream mail servers and ISP spam filters:

  • Batch Size: Processed in micro-batches of 5 recipients (BATCH_SIZE = 5).
  • Inter-Batch Delay: A 250ms pause (BATCH_DELAY_MS = 250) is enforced between batches.
  • Transient Failure Isolation: If a single recipient address fails (e.g. invalid syntax, mailbox full), the error is recorded on that specific recipient record in BulkEmailRecipientChunk while the remaining broadcast continues uninterrupted.

6. Campaign File Attachments​

Administrators can attach external documents to outgoing campaigns:

  • Maximum Attachments: Up to 3 files per campaign.
  • Total Size Limit: Capped at 3.0 MB combined binary payload.
  • Permitted MIME Types: .pdf, .docx, .xlsx, .png, .jpg.
  • Storage Strategy: Attachments are passed at dispatch time and are not permanently stored in templates, keeping template documents lightweight.