MailOS Campaign Command

The mailos campaign command keeps recurring email work attached to a stable purpose in the folder where that work lives. It saves campaign IDs locally, remembers the active campaign, and wraps the existing mailos send and mailos search commands so you do not have to re-enter --campaign-id.

Campaigns are purposes, not recipient lists. Use mailos groups, --group, or explicit --to, --cc, and --bcc values to select recipients.

Quick Start

# Create a campaign. New campaigns become active immediately.
mailos campaign create "spring-2026" \
  --purpose "Introduce the spring release and follow up with interested teams"

# Preview a campaign email through the normal send implementation.
mailos campaign send \
  --to [email protected] \
  --subject "Spring release" \
  --body "A short introduction" \
  --preview

# List sent messages stamped with the active campaign ID.
mailos campaign show

# Search replies and apply any normal MailOS search filters.
mailos campaign search --type inbox --days 30

Folder Scope and Storage

The registry is stored at .email/campaigns.json in the campaign workspace. MailOS resolves that workspace from the current directory in this order:

1. Nearest parent with an existing .email/campaigns.json.
2. Nearest parent with emailos.json or emailos.toml.
3. Nearest Git root.
4. The current directory when none of those markers exist.

This makes a campaign available from subfolders without mixing it into other projects or the global MailOS account configuration. The registry records each campaign's ID, purpose, creation and update timestamps, last use, and use count.

Manage Campaigns

# List campaigns. The active campaign is marked with *.
mailos campaign
mailos campaign list
mailos campaign list --json

# Show the active campaign and registry path.
mailos campaign current

# Switch the active campaign.
mailos campaign use "renewals-2026"

# Refine a campaign's purpose without losing its usage history.
mailos campaign update "renewals-2026" --purpose "Renew expiring 2026 accounts"

# Remove local campaign metadata. This does not delete email.
mailos campaign delete "completed-outreach"

Campaign IDs are matched case-insensitively in the local registry while the original spelling is preserved for the X-MailOS-Campaign-ID header.

Send Within a Campaign

mailos campaign send is the existing send command with the active campaign's ID supplied automatically. All normal send flags remain available:

mailos campaign send \
  --group ./recipients.md \
  --subject "Project introduction" \
  --body @message.md \
  --send-separately \
  --dry-run

The email receives the hidden X-MailOS-Campaign-ID header and a stable Message-ID. Use --dry-run or --preview before delivery. Remove the preview flag only when the live send is intentional.

To work against a saved campaign without changing the active selection, pass its ID explicitly:

mailos campaign send --campaign-id "renewals-2026" \
  --to [email protected] --subject "Renewal" --body "Hello" --preview

Recall and Track Email

show provides the shortest route back to sent campaign messages:

mailos campaign show
mailos campaign show "spring-2026" --days 90

It defaults the existing search command to --type sent. Other search flags, including --account, --days, --json, --thread, and --view, remain available.

Use search for the active campaign when you want a different mailbox or an additional query:

mailos campaign search --type inbox --days 30
mailos campaign search "pricing" --type all --thread
mailos campaign search --campaign-id "renewals-2026" --type inbox

Campaign search first finds original messages stamped with the campaign ID. It can then include replies whose In-Reply-To or References headers point to those originals, even when the reply does not preserve the custom campaign header.

Command Summary

Command	Purpose
mailos campaign	List folder campaigns
mailos campaign create <id> --purpose <text>	Create and activate a campaign
mailos campaign use <id>	Select the active campaign
mailos campaign update <id> --purpose <text>	Update a campaign purpose
mailos campaign current	Show the active campaign
mailos campaign show [id]	List sent messages for a campaign
mailos campaign search [query]	Search email for the active campaign
mailos campaign send ...	Preview or send with the active campaign ID
mailos campaign delete <id>	Remove local campaign metadata

The alias mailos campaigns is also available.