DOCSEARCHbyAlgolia
Submit Docs

mailmerge 2.3.0

repository·develop·Indexed 41 days ago

https://github.com/awdeorio/mailmerge

A command-line mail merge tool that uses plain text templates and CSV databases. It leverages the Jinja2 engine for template customization and supports HTML, Markdown, and multipart email formats. Features include SMTP server configuration, file attachments, inline images, and a dry-run mode to preview messages before sending.

Tokens
4.4K
Snippets
19
Records
21
Agent score
49%

What's inside mailmerge

  1. Format emails with HTML or Markdown

    develop

    Mailmerge supports multiple content types by specifying the Content-Type header.

    HTML Only

    Add Content-Type: text/html under the headers and wrap your body in <html> tags.

    HTML and Plain Text (Multipart)

    To provide both, use Content-Type: multipart/alternative; boundary="boundary" and define the parts separated by --boundary.

    Markdown

    Add Content-Type: text/markdown. Mailmerge will automatically render the Markdown to HTML and include both HTML and plain text versions in a multipart message.

  2. Create email templates with Jinja2

    develop

    Email templates are written in plain text using the jinja2 template engine.

    Required Headers:

    • TO: Use {{email}} or another placeholder matching your database column.
    • SUBJECT: The email subject line.
    • FROM: The sender's identity.

    Placeholders: Use {{column_name}} to inject data from your CSV database. For example, {{name}} will be replaced by the value in the name column of your CSV.

    Example mailmerge_template.txt:

    TO: {{email}}
SUBJECT: Testing mailmerge
FROM: My Self <myself@mydomain.com>
BCC: myself@mydomain.com

Hi, {{name}},

Your number is {{number}}.

  3. Generate sample configuration files

    develop

    To quickly set up a working environment, use the --sample flag. This creates three files in your current directory: a template email (mailmerge_template.txt), a database (mailmerge_database.csv), and an SMTP server configuration (mailmerge_server.conf).

    $ mailmerge --sample

  4. Add file attachments to emails

    develop

    You can attach files to your emails by using the ATTACHMENT: header in your template file. You can provide relative paths, absolute paths, or even use Jinja2 template syntax within the path to dynamically select files based on database values.

    To verify that your attachment paths are correct and that the files exist before actually sending emails, perform a dry run. If your attachment paths use Jinja2 templates, it is recommended to use the --no-limit flag during the dry run to ensure all possible file paths are validated.

    TO: {{email}}
SUBJECT: Testing mailmerge
FROM: My Self <myself@mydomain.com>
BCC: myself@mydomain.com
ATTACHMENT: file1.docx
ATTACHMENT: ../file2.pdf
ATTACHMENT: /z/shared/{{name}}_submission.txt

Hi, {{name}},

This email contains three attachments.
    # Dry run to verify attachment files exist
mailmerge

# Dry run with no limit (recommended if attachment paths use Jinja)
mailmerge --no-limit

# Send actual messages
mailmerge --no-dry-run

  6. Add inline image attachments

    develop

    To render images directly within the email body (rather than just as files), you must follow two rules:

    1. Add the image as an ATTACHMENT: in the header section.
    2. Reference the attachment filename in your HTML or Markdown body.

    HTML Example

    Set Content-Type: text/html in the header and use standard <img> tags.

    Markdown Example

    Set CONTENT-TYPE: text/markdown in the header and use standard Markdown image syntax ![alt](path).

    # HTML Template Example
TO: {{email}}
SUBJECT: Testing mailmerge
FROM: My Self <myself@mydomain.com>
BCC: myself@mydomain.com
Content-Type: text/html
ATTACHMENT: image.jpg
ATTACHMENT: second/image.jpg

<html>
<body>
<p>Hi, {{name}},</p>
<img alt="Sample image" src="image.jpg" />
<p>The second image: <img alt="second" src="second/image.jpg"/></p>
</body>
</html>
    # Markdown Template Example
TO: {{email}}
SUBJECT: Testing mailmerge
FROM: My Self <myself@mydomain.com>
BCC: myself@mydomain.com
ATTACHMENT: image.jpg
CONTENT-TYPE: text/markdown

Hi, {{name}},

![image alt-description](image.jpg)

  7. Resume a failed mail merge

    develop

    If a mail merge process is interrupted (e.g., due to a rate limit or error), Mailmerge provides a --resume option.

    When an error occurs, the tool will often provide a hint such as Hint: "--resume <number>". Use this number with the --resume flag to skip the messages that were already processed and start from the point of failure.

  8. Configure the SMTP server

    develop

    Edit mailmerge_server.conf to define your mail server settings. The default configuration is set up for Gmail.

    Important for Gmail users:

    • Change username to your actual email address.
    • If using 2-factor authentication, you must use an app password.

    Example mailmerge_server.conf structure:

    [smtp_server]
host = smtp.gmail.com
port = 465
security = SSL/TLS
username = YOUR_USERNAME_HERE

  9. Use the Mailmerge CLI

    develop

    Mailmerge is a command-line tool for performing mail merges using a template, a database (CSV), and an SMTP server configuration. By default, it runs in dry-run mode, meaning it will print the rendered messages to the console instead of sending them via email.

    To send actual emails, you must use the --no-dry-run flag.

    # Example: Dry run (default) to preview messages
mailmerge --template my_template.txt --database my_data.csv --config my_server.conf

# Example: Send actual emails
mailmerge --no-dry-run --template my_template.txt --database my_data.csv --config my_server.conf

  10. Generate sample template, database, and config files

    develop

    If you are new to Mailmerge, you can use the --sample flag to generate a set of working example files. This will create a template email, a CSV database, and an SMTP server configuration file with valid syntax and placeholder values.

    Note: This command will fail if any of the target files already exist to prevent overwriting your data.

    mailmerge --sample

  11. Configure SendmailClient via config file

    develop

    The SendmailClient reads its settings from a configuration file using configparser. The configuration must contain an [smtp_server] section.

    Required and optional keys in [smtp_server]:

    • host: The SMTP server hostname.
    • port: The SMTP server port (integer).
    • security: The authentication method. Supported values are:
      • SSL/TLS (uses SMTP_SSL)
      • STARTTLS (uses STARTTLS)
      • PLAIN (standard login)
      • XOAUTH (OAuth2 via Bearer token)
      • Never (legacy alias for no security/None)
    • username: The username for authentication (required if security is not None).
    • ratelimit: An integer representing the number of emails allowed per minute. If set to 0, no rate limiting is applied.
    [smtp_server]
host = smtp.example.com
port = 587
security = STARTTLS
username = myuser
ratelimit = 10

  12. Run mailmerge (Dry run vs. Send)

    develop

    By default, mailmerge performs a dry run. It processes the template and prints the resulting email to the terminal without sending anything.

    Commands

    • Dry run (default): $ mailmerge (processes only the first recipient).
    • Dry run all recipients: $ mailmerge --no-limit.
    • Send only the first email: $ mailmerge --no-dry-run.
    • Send all emails: $ mailmerge --no-dry-run --no-limit.

    Note: You may be prompted for your SMTP password during a real send operation.

    # Dry run the first message
$ mailmerge

# Dry run all messages
$ mailmerge --no-limit

# Send all messages
$ mailmerge --no-dry-run --no-limit