csvformatmail: A tool to format mails from csv and to send them

A simple yet powerful tool to send personalized emails using a template and CSV data.

Installation

pipx install csvformatmail  # Recommended
# or
pip install csvformatmail

Shell Completion

For bash or other shells using bash-completion:

mkdir -p ~/.local/share/bash-completion/completions
register-python-argcomplete csvformatmail > ~/.local/share/bash-completion/completions/csvformatmail

Quick Start

1. Create a template (template.txt):

From: Me <sender@example.com>
To: {{email}}
Subject: Hello {{name}}

Hi {{name}},
Welcome!

Best regards,
-- 
Me

2. Prepare your data (contacts.csv):

name,email
Alice,alice@example.com
Bob,bob@example.com

3. Send emails:

csvformatmail template.txt contacts.csv

Template Files

Templates use the Jinja2 syntax. The structure is:

• Email headers (From, To, Subject are mandatory)
• Empty line
• Email body

Variables from your CSV are accessed using {{variable}}.

If your template file uses a specific encoding (by default the system default encoding is used), see the -E option.

CSV Data

The CSV file provides the data for personalizing each email. Column names in the CSV become variables in the template.

Example:

first_name,last_name,email,order_id
John,Doe,john@example.com,12345
Jane,Smith,jane@example.com,12346

Options:

• Change delimiter: -d ";" for semicolon-separated files
• Use -e to specify CSV encoding (by default the system default encoding is used).
• Rename columns on the fly: data.csv:email,name=full_name

Sending Emails

Local SMTP Server

csvformatmail template.txt data.csv

Remote SMTP Server with authentication

csvformatmail -h smtp.example.com -l username template.txt data.csv

The password will be prompted interactively if needed. Authentication is always performed in an encrypted tunnel (STARTTLS). Plain text authentication without STARTTLS is deliberately not supported for security reasons.

Other server options are available, see csvformatmail --help.

Attachments

Add attachments using the Attachments fake header:

From: sender@example.com
To: {{email}}
Subject: Your Document
Attachments: common.pdf, {{document}}

Please find attached your documents.

Corresponding CSV file:

email,document
alice@example.com,alice_report.pdf
bob@example.com,bob_report.pdf

The attachment paths can be either fixed or from CSV variables.

Advanced Formatting

Type Conversion and Formatting

Convert CSV columns to specific types for formatting:

csvformatmail -t score:float -t date:str template.txt data.csv

In the template, you can use the formatted value:

Average score: {{"{:.1f}".format(score)}}

Conditional Formatting

Use Jinja2 conditional statements to customize your message:

Your score is {{"{:.1f}".format(score)}}/20.
{% if score >= 10 %}
Congratulations, you passed the test!
{% else %}
Unfortunately, you did not pass the test. You need at least 10/20 to pass.
{% endif %}

Accessing All Rows

Use allrows in the template to access complete columns:

Average score: {{"{:.1f}".format(np.mean(allrows['score']))}}

Enable numpy with --np:

csvformatmail --np template.txt data.csv

Text Formatting

Use textwrap for better text formatting:

csvformatmail -b "import textwrap" template.txt data.csv

Then in template:

{{textwrap.fill(long_text, width=72)}}
{{textwrap.indent(text, "> ")}}

S/MIME Signing

Using gpgsm

# Automatic signing using From address
csvformatmail -s template.txt data.csv

# Explicit gpgsm usage
csvformatmail --sign-gpgsm template.txt data.csv

Using PKCS#12 Certificate

csvformatmail --sign-p12 cert.p12 template.txt data.csv

The certificate password will be prompted interactively.