Leviro Mailer CLI

Leviro Mailer is an open-source command-line tool for sending a campaign from a local CSV file through an SMTP account. It fills a Handlebars template with each row's values, sends messages at a controlled pace, and records successful sends so an interrupted run can resume.

The problem

A small mailing task should not require a hosted campaign service. It still needs input checks, a preview, retry handling, and a way to avoid sending the same message again after a process stops. The CLI keeps those decisions visible to the person running it.

Key features

• The send command accepts a CSV file, template, subject, sender, and campaign identifier.
• CSV parsing requires an email column and validates recipient addresses.
• Handlebars renders message content from fields in each recipient row.
• A dry run validates and previews the campaign without sending mail.
• Test mode sends a single marked message using the first data row.
• Configurable delay spaces messages, while retries handle transient SMTP failures.
• Local campaign state skips addresses already recorded as sent.
• A force option can deliberately resend to recorded recipients.

Technical architecture

A TypeScript CLI parses options with Commander and validates them with Zod. It reads the CSV, compiles the template, and hands each message to Nodemailer for SMTP delivery. Campaign state lives in a local .leviro-mailer directory. The runner records each accepted send before moving on. A failed state write stops the campaign so the tool does not continue without a reliable resume record.

Engineering highlights

• State stores SHA-256 identifiers derived from campaign and recipient address instead of raw addresses.
• State updates use a temporary file and rename, reducing the chance of a partial record.
• Retry logic applies exponential backoff to failures classified as temporary.
• Invalid CSV rows and missing template values are reported before delivery.
• Vitest covers parsing, rendering, SMTP behavior, campaign state, and the runner.