Open source · MIT licensed

Email sequences on AWS, managed through AI

mailshot is an open-source framework that puts email sequencing, subscriber management, engagement analytics, and deployment inside Claude Code. Describe what you want, AI handles the rest.

Documentation

$ npx create-mailshot my-project

$ cd my-project && claude

> “Create a 5-part onboarding sequence triggered by customer.created”

✓ Generated sequence config, 5 templates, deploy files

> “Deploy”

✓ Deployed to AWS (us-east-1)

AI-native workflow

The whole lifecycle lives in Claude Code

Generate email content, design sequences, deploy infrastructure, query engagement metrics, optimize performance. mailshot ships with an MCP server and Claude Code skills that give AI full access to your running system.

“Create a 3-part re-engagement sequence for users inactive for 30 days”

Generates TypeScript sequence config, 3 email templates with LiquidJS placeholders, and render script

“Preview the day-3 email for jane@acme.com”

Fetches subscriber profile from DynamoDB, renders template with live data

“Deploy”

Validates types, checks template references, synthesizes CDK, deploys to AWS

“How are open rates on the re-engagement sequence?”

Queries engagement table — 68% delivered, 42% opened, 12% clicked across 340 sends

Sequences as code

AI generates it, you review it

Describe a sequence in natural language. Claude Code generates the typed TypeScript config with triggers, steps, delays, and conditional branches. Drop it in sequences/ — auto-discovered at build time, CDK generates the Step Functions state machine.

Templates work the same way. AI writes the email content, mailshot renders it with LiquidJS at send time. Use React Email, MJML, or raw HTML — anything that produces .html.

Sequence docs

sequences/welcome/sequence.config.ts

import type { SequenceDefinition }
  from "@mailshot/shared";

export default {
  id: "welcome",
  trigger: {
    detailType: "customer.created",
    subscriberMapping: {
      email: "$.detail.email",
      firstName: "$.detail.firstName",
    },
  },
  steps: [
    { type: "send",
      templateKey: "welcome/hello",
      subject: "Welcome aboard" },
    { type: "wait", days: 2 },
    { type: "send",
      templateKey: "welcome/getting-started",
      subject: "Getting started" },
    { type: "wait", days: 3 },
    { type: "choice",
      field: "$.subscriber.attributes.plan",
      branches: [
        { value: "pro", steps: [
          { type: "send",
            templateKey: "welcome/pro-tips",
            subject: "Pro tips" },
        ]},
        { value: "free", steps: [
          { type: "send",
            templateKey: "welcome/upgrade",
            subject: "Ready for more?" },
        ]},
      ],
    },
  ],
} satisfies SequenceDefinition;

What's included

Framework, infrastructure, and tooling

AI generates sequences

Describe a sequence in plain language. Claude Code generates the TypeScript config, email templates, and deploy files.

16-tool MCP server

AI talks directly to your infrastructure. Manage subscribers, query engagement, preview templates, debug issues — all through Claude Code.

4 Claude Code skills

setup-env, create-sequence, validate, deploy. The skills handle generation, validation, CDK synthesis, and deployment.

AI-driven analytics

AI queries your engagement data and gives you recommendations. Opens, clicks, bounces per subscriber, template, or sequence.

Full SES integration

Delivery tracking, open/click events, bounce handling, List-Unsubscribe headers, HMAC-signed unsubscribe URLs.

Automatic suppression

Bounces and complaints suppress subscribers and stop all active Step Functions executions.

Serverless

Step Functions, Lambda, EventBridge, DynamoDB, S3. Pay-per-use on your own AWS account.

Conditional branching

Branch on subscriber attributes, check if emails were sent, evaluate conditions within sequences.

Template agnostic

React Email, MJML, raw HTML. Stores .html in S3 and renders LiquidJS at send time.

MCP Server

16 tools for Claude Code

The MCP server connects Claude Code to your running infrastructure. Manage subscribers, query analytics, preview emails, debug issues.

Subscribers

get
list
update
delete
unsubscribe
resubscribe

Engagement

by subscriber
by template
by sequence

Templates

list in S3
preview with live data
validate Liquid syntax

Suppression

list suppressed
remove suppression

System

failed executions
delivery stats

Full tool reference

Architecture

Managed AWS services, wired together

EventBridge for routing, Step Functions for orchestration, Lambda for execution, DynamoDB for state, S3 for templates, SES for sending. CDK deploys the whole stack.

EventBridge

Event routing

Step Functions

Sequence orchestration

Lambda

5 handler functions

DynamoDB

Subscriber state + events

Template storage

SES

Email delivery + tracking

SNS

Bounce/engagement routing

SSM

Runtime config

Your App → EventBridge → Step Functions → Lambda → SES → Recipient
                                            ↓
                                    S3 (templates)
                                    DynamoDB (state)

Packages

Published to npm

@mailshot/sharedTypes, constants, DynamoDB key helpers

@mailshot/handlersFive Lambda handlers + shared lib modules

@mailshot/cdkCDK infrastructure with modular constructs

@mailshot/mcpMCP server for Claude Code

create-mailshotCLI scaffolder

Describe a sequence. Deploy it.

Scaffold a project, open Claude Code, tell it what emails to send and when. AI generates the config, templates, and deploys to your AWS account.

Quickstart guide