Bulk Gmail

This is a CLI tool for sending bulk emails using Gmail.

It was originally created for Hack the Hill to send emails to all of the applicants.

Bulk Gmail is a CLI that reads from a CSV file for the lists of recipients and a directory of Handlebars email templates. It then sends emails to the recipients using the email templates.

Usage

You can send emails using the npx bulk-gmail command. The CLI will prompt you for which email template to use, the for a path to the CSV file containing the list of recipients, and your Gmail credentials. The CSV file should have the following columns:

• id: The ID of the recipient
• name: The name of the recipient
• email: The email address of the recipient
• language: The language of the recipient (en or fr)

The chosen email templates directory should contain folders for each template. Inside of those folders, there should be a text.hbs file for the text version of the email and a html.hbs file for the HTML version of the email. The email templates are written in Handlebars and they are compiled with the language data from the corresponding language.json file (in addition to name and email variables with the recipient's info).

The language.json file can also have from, subject, and meta keys. meta will be parsed as email List headers.

Here is an example of a language.json file:

{
    "en": {
        "from": "Your name",
        "subject": "Subject here",

        // These are optional free-form fields (they can be anything you want) that can be used in the email templates
        "greeting": "Hello",
        "message": [
            "This is a message",
            "It has multiple lines"
        ],
        "signature": "Your signature",
        "closing": "Your name",
        "unsubscribe": "Unsubscribe",

        // These are optional fields that will be parsed as email List headers
        "meta": {
            "help": "[email protected]?subject=Help with mailing list",
            "unsubscribe": {
                // The `{{email}}` variable will be replaced with the recipient's email address
                "url": "https://example.com/unsubscribe?email={{email}}",
                "comment": "Unsubscribe from further emails"
            },
            "id": {
                "url": "https://example.com",
                "comment": "2023 mailing list"
            }
        }
    },
    "fr": {
        "from": "Votre nom",
        "subject": "Sujet ici",

        // etc.
    }
}

Here is an example of a text.hbs file:

{{greeting}}, {{name}}!

{{#each message as |paragraph|}}
    {{paragraph}}
{{/each}}

{{signature}}

{{closing}}

{{unsubscribe}}: https://example.com/unsubscribe?email={{email}}

Here is an example of a html.hbs file:

<p>{{greeting}}, {{name}}!</p>

{{#each message as |paragraph|}}
    <p>{{paragraph}}</p>
{{/each}}

<p>{{signature}}</p>

<p>{{closing}}</p>

<a href="https://example.com/unsubscribe?email={{email}}">{{unsubscribe}}</a>

Support

Please consider supporting me on my Patreon if you like my work. You can see a list of all my projects on my website.

Bugs

You can submit bugs via Github Issues or on my Discord server.

Contact me

Come hang out on my my Discord server.

License

Copyright © 2022 arcanist

This package is under an MIT license.