Metadata-Version: 2.2
Name: csvformatmail
Version: 1.3.1
Summary: A tool to send many mails from csv and a template
Author-email: Jean-Benoist Leger <jbleger@hds.utc.fr>
Maintainer-email: Jean-Benoist Leger <jbleger@hds.utc.fr>
License: MIT License
Project-URL: homepage, https://gitlab.com/jbleger/csvformatmail
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: argcomplete
Requires-Dist: csvspoon>=1.1.3
Requires-Dist: numpy
Requires-Dist: cryptography

# 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

```bash
pipx install csvformatmail  # Recommended
# or
pip install csvformatmail
```

### Shell Completion

For bash or other shells using bash-completion:

```bash
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:
```bash
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:
```bash
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:
```csv
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
```bash
csvformatmail template.txt data.csv
```

### Remote SMTP Server with authentication
```bash
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: sender@example.com
To: {{email}}
Subject: Your Document
Attachments: common.pdf, {{document}}

Please find attached your documents.
```

Corresponding CSV file:
```csv
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:
```bash
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`:
```bash
csvformatmail --np template.txt data.csv
```

### Text Formatting
Use textwrap for better text formatting:
```bash
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
```bash
# 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
```bash
csvformatmail --sign-p12 cert.p12 template.txt data.csv
```

The certificate password will be prompted interactively.
