Email Marketing

Overview

The email marketing system in TanStack Ship enables you to create, send, and track HTML email campaigns to your user base. Powered by asynchronous queue-based delivery for reliability, it supports both broadcast marketing emails and transactional communications.

As part of the platform, the email module integrates with the billing system for payment receipts, the invitation system for user onboarding, and the analytics dashboard for campaign performance tracking.

Design Flow

The email marketing system orchestrates the complete campaign delivery pipeline, from content creation through queue-based dispatch to delivery tracking:

Core Capabilities

Campaign Creation & Management

The email campaign admin interface provides:

• Rich HTML Editor — Compose emails using a visual editor or raw HTML
• Subject Line & Preview Text — Customizable subject and preheader
• Sender Configuration — From name and email address
• Recipient Selection — All users or segmented groups
• Scheduling — Send immediately or schedule for a specific date/time

Queue-Based Asynchronous Delivery

Emails are sent asynchronously for reliability and performance:

1. Campaign is created in the database with DRAFT status
2. Admin previews and sends the campaign
3. Recipients are enqueued as individual messages
4. A consumer processes each message with retry logic
5. Delivery status is updated after each successful or failed send

This architecture prevents timeouts and ensures delivery completes even if the initial request fails.

Transactional Emails

Beyond marketing campaigns, the system handles automated transactional emails:

• Payment confirmation and digital receipts
• Account verification and password reset links
• Invitation notifications
• Billing alerts, subscription updates, and payment failure notices

Transactional emails are triggered by server-side events and sent through the same delivery system.

Client-side email campaign list example:

import { useQuery } from '@tanstack/react-query'

export function CampaignList() {
  const { data } = useQuery({
    queryKey: ['email-campaigns'],
    queryFn: () =>
      fetch('/api/email-campaigns').then((r) => r.json()) as Promise<
        Array<{
          id: string
          subject: string
          status: string
          sentCount: number
          openRate: number
          createdAt: string
        }>
      >,
  })

  return (
    <div className="rounded-lg border divide-y">
      {data?.map((c) => (
        <div key={c.id} className="flex items-center justify-between p-4">
          <div>
            <p className="font-medium">{c.subject}</p>
            <p className="text-xs text-muted-foreground">
              {c.status} · {c.sentCount} sent · {c.openRate}% open
            </p>
          </div>
        </div>
      ))}
    </div>
  )
}

Design Philosophy

Async Delivery by Default

All email campaigns are sent asynchronously through Cloudflare Queues, never synchronously during HTTP requests. When an admin clicks "send," campaign recipients are immediately enqueued as individual messages and the API returns instantly. A background consumer processes each message with retry logic, updating delivery status as each send completes. This architecture prevents HTTP timeouts, ensures delivery completes even if the Resend API is temporarily unavailable, and allows the system to handle large campaigns (thousands of recipients) without blocking server resources. Unlike Mailchimp or SendGrid's synchronous sending modes — which block the HTTP response until delivery completes and can time out on large campaigns — our queue-based architecture decouples sending from the request lifecycle, enabling reliable delivery at any scale without server-side timeouts.

Reliable at Scale

The queue-based delivery system implements exponential backoff retry for failed deliveries, automatically retrying transient failures (rate limits, network timeouts) while eventually marking persistently failed deliveries. This reliability layer operates independently of the admin interface — campaigns are processed to completion even if the admin who sent them closes their browser. Delivery status is tracked per-recipient, giving administrators complete visibility into campaign performance.

Unified Communication Pipeline

Transactional emails (receipts, notifications, alerts) and marketing campaigns share the same delivery pipeline — same queue infrastructure, same Resend integration, same delivery tracking. This unified approach reduces operational complexity: there's one sending system to monitor, one set of delivery metrics to track, and one configuration (SPF, DKIM, DMARC) to maintain. Transactional emails bypass the campaign workflow and are triggered directly by server-side events.

Best Practices

Email Design for Deliverability

Use plain text alternatives alongside HTML content. Keep HTML structure simple — avoid excessive images and complex layouts that may trigger spam filters.

Segment Before Sending

Always test campaigns on a small segment before sending to all users. The system supports sending to selected user segments for A/B testing.

Monitor Bounce Rates

Regularly review campaign analytics for bounce rates and unsubscribes. High bounce rates indicate list hygiene issues that should be addressed.

FAQ

Which email provider does the system use? The system uses Resend for email delivery. A Resend API key is required for both development and production.

Can I send emails to specific user segments? Yes. The campaign creation interface supports selecting all users or specific user segments for targeted campaigns.

How does the system handle failed email deliveries? The delivery system implements retry logic with exponential backoff for failed deliveries. After exhausting retries, the delivery is marked as failed.

Configuration

Email delivery requires a Resend API key and sender configuration:

RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=updates@yourdomain.com
RESEND_FROM_NAME=Your Product

Queue configuration is required for async email delivery in production.

Integration Points

• User System — Recipient list is sourced from user database records with segmentation support
• Billing — Transactional emails for payment confirmations, receipts, and subscription updates
• Invitation System — Invitation notifications and welcome emails
• Analytics Dashboard — Track email campaign open rates, click rates, and delivery metrics