csvformatmail 1.3.1

A tool to send many mails from csv and a template

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 <[e-mail]>
To: {{email}}
Subject: Hello {{name}}

Hi {{name}},
Welcome!

Best regards,
Me

2. Prepare your data (contacts.csv):

name,email
Alice,[e-mail]
Bob,[e-mail]

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), use the -E option:

csvformatmail -E iso8859-15 template.txt contacts.csv

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,[e-mail],12345
Jane,Smith,[e-mail],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.

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

Attachments

Add attachments using the Attachments header:

From: [e-mail]
To: {{email}}
Subject: Your Document
Attachments: common.pdf, {{document}}

Please find attached your documents.

Corresponding CSV file:

email,document
[e-mail],alice_report.pdf
[e-mail],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)}}

Accessing All Rows

Use allrows in the templateto 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.