{"id":21072419,"url":"https://github.com/binarymist/mailgun-mate","last_synced_at":"2025-03-14T03:10:38.295Z","repository":{"id":69462590,"uuid":"136936643","full_name":"binarymist/mailgun-mate","owner":"binarymist","description":" :email: :gun: Email batch scheduler (CLI) :email: :gun:","archived":false,"fork":false,"pushed_at":"2019-08-30T22:48:58.000Z","size":132,"stargazers_count":3,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-21T02:48:19.501Z","etag":null,"topics":["batch","cli","consultant","email","mailgun","scheduler"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binarymist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["binarymist"]}},"created_at":"2018-06-11T14:18:25.000Z","updated_at":"2023-04-14T08:40:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"d2621219-c80a-41a6-838e-a5367d03e458","html_url":"https://github.com/binarymist/mailgun-mate","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymist%2Fmailgun-mate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymist%2Fmailgun-mate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymist%2Fmailgun-mate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymist%2Fmailgun-mate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binarymist","download_url":"https://codeload.github.com/binarymist/mailgun-mate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243515569,"owners_count":20303258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["batch","cli","consultant","email","mailgun","scheduler"],"created_at":"2024-11-19T18:56:31.943Z","updated_at":"2025-03-14T03:10:38.279Z","avatar_url":"https://github.com/binarymist.png","language":"JavaScript","funding_links":["https://github.com/sponsors/binarymist"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003emailgun-mate\u003c/h1\u003e\u003cbr/\u003e\n    Email batch scheduling CLI\n  \u003cbr/\u003e\u003cbr/\u003e\n\n  \u003ca href=\"https://travis-ci.org/binarymist/mailgun-mate\" title=\"build status\"\u003e\n     \u003cimg src=\"https://api.travis-ci.org/binarymist/mailgun-mate.png\" alt=\"build status\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://github.com/binarymist/mailgun-mate/blob/master/LICENSE\" title=\"license\"\u003e\n     \u003cimg src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"test coverage\"\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003ca href=\"https://user-images.githubusercontent.com/2862029/48294186-aa449600-e4e7-11e8-8c0e-418ff56adc8a.gif\" title=\"mailgun-mate\"\u003e\n    \u003cimg width=900px src=\"https://user-images.githubusercontent.com/2862029/48294186-aa449600-e4e7-11e8-8c0e-418ff56adc8a.gif\" alt=\"running mailgun-mate\"\u003e\n  \u003c/a\u003e\n\n\u003cbr/\u003e\n\u003c/div\u003e\n\n## Install\n\n```\nnpm i mailgun-mate -g\n```\nOr:\n\n```\ngit clone git@github.com:binarymist/mailgun-mate.git \u0026\u0026 cd mailgun-mate \u0026\u0026 npm install\n```\nBefore running, you'll need to setup a little configuration. See the [Configuration](#configuration) section below.\n\n\n## Quick Start\n\nFirst, you need to have a free mailgun account, a domain setup there, and at least one mail list to start controlling.\n\n### Configuration\n\nThis project uses [convict](https://github.com/mozilla/node-convict). The configuration file(s) are in [`./config/`](https://github.com/binarymist/mailgun-mate/tree/master/config). You will need to provide one according to the `NODE_ENV` environment variable you are running `mailgun-mate` with. First find where `mailgun-mate` is installed to with `whereis mailgun-mate`. This command will show where the bin file is, from there, you just need to ascend the directories until you find a `lib/node_modules/mailgun-mate/config/` directory. From there, you can copy the `config.example.json` file and rename it to `config.[your-environment].json` (`your-environment` should be `development`, `production`, or what ever you set `NODE_ENV` to).\n\n\n\nDecide on a directory that you will put your text files containing `HTML` (although just text is also fine), and assign that directory path to your config file's `emailBodyFileDir` property.  \nIn your `HTML` mailout files, you can add an unsubscribe link \n\nMailgun [provides the ability](https://app.mailgun.com/app/domains/mailgun.yourdomain.com) for you to have them insert an `unsubscribe` link into all emails sent from your your domain. This link allows the email receiver to unsubscribe from the specific list that the email was sent from.  \nIn many cases you wont want an `unsubscribe` link, like when sending immediately or scheduling a small batch of custom mailouts from a large list of say business contacts, as these are usually fairly personal.  \nThe only option I've found that works on a email by email basis is inserting the following:\n\n```\n\u003ca href=\"%unsubscribe_url%\"\u003eunsubscribe from domain\u003c/a\u003e \u003c!--This link unsubscribes the member from the entire domain.--\u003e\n```\n\nClicking on that will unsubscribe the list member from the entire domain, which is usually not what you may want, especially if you have many lists.\n\nBefore sending any batch, I like to make sure I have `o:testmode` set to `true`, and I'm targeting a test `emailList`. Both of these can be set in the config file(s), but are also overrideable at the command line.  \nyou can change these once you're confident your configuration, command line args, email teamplate, and recipient variables are correct.  \nI usually use a first name (`fname` in my case), then build up your email teamplate using a `%recipient.fname%` wich mailgun will substitute for the `fname` property you set in the list members recipient variables. The following is an example of how I setup the mailgun recipient variables.\n\n```\n{\n  \"fname\": \"Bob\",\n  \"mailgunMateScheduledSends\": [\n    [\n      \"a.html\",\n      \"2018-06-16_17:00:00\"\n    ],\n    [\n      \"b.html\",\n      \"2018-06-16_17:10:00\"\n    ]\n  ],\n  \"name\": \"Bob Builder\",\n  \"org\": \"Bob Builder Holdings\",\n  \"role\": \"Carpenter\"\n}\n```\n\nThe `mailgunMateScheduledSends` is what mailgun-mate adds for you. Each time you schedule an email, a new array containing the `email-body-file` and the `schedule-time` will be added to the `mailgunMateScheduledSends` array. Mailgun-mate knows where to find the`email-body-file` due to the `emailBodyFileDir` that you need to set in the configuration file.\n\nThe `name` property is printed beside the email address in `mailgun-mate`. `org` and `role` will be used to sort in the future.\n\n\n## Usage\n\n### Command Line\n\n```\nUsage: mailgun-mate [command(s)] [option(s)]\n\nOptions:\n  -a, --about               Show about screen.\n  -v, --version             Show version number.\n  -h, --help                Show help.\n\nCommands:\n  schedule-delivery         Launch scheduled mail delivery, max of three days in advance.\n\nOptions:\n  -l, --email-list      \u003cemail-list\u003e                     The mailgun email list you would like to use.\n  -b, --email-body-file \u003cemail-body-file\u003e                File containing the html for the body of the email. Relative to the emailBodyFileDir directory you set in the configuration.\n  -f, --from \u003csent-from-for-replies\u003e                     The value that the receiver will see that your emails appear to be sent from, in the form of \"Kim \u003cservices@binarymist.net\u003e\"\n  -s, --subject \u003csubject-for-email\u003e'                     The subject for the email\n  -t, --schedule-time \u003ctime-to-schedule-email-send-for\u003e  The time that all emails will be sent (in RFC 2822 time).\n  -tm, --test-mode                                       Whether or not to send in test mode \"o:testmode\". defaultValue set in config file.\n\nOptions:\n  -h, --help                     Show help.\n\nCommands:\n  schedule-delivery list         List members in order based on latest or oldest mailgunMateScheduledSends datetimes.\n\nOptions:\n  -h, --help                                    Show help.\n  -l, --email-list          \u003cemail-list\u003e        The mailgun email list you would like to use. A required string argument, if none is present on command line, value from config file is used.\n  -o, --order              [des|asc(default)]   The order you would like the items displayed in.\n```\n\nBefore authenticating with mailgun, `mailgun-mate` checks the `${os.homedir()}/.mailgun/key` for your private key, if present, it will attempt authentication, if not present, it will prompt for your key at the terminal. Currently there is no validation on your private key file ownership or permissions, but they should be set at least as restrictive as SSH private keys.\n\nIf you just want to download the source and run it... Assuming you have npm installed, from within your `mailgun-mate` source directory, run the following:\n\n```\nnpm run -- start\n```\n\n### Debugging\n\nFrom within your `mailgun-mate` source directory, run the following and open your chrome dev tools:\n\n```\nnode --inspect-brk ./bin/mailgun-mate [command(s)] [option(s)]\n```\n\nOr\n\n```\nnpm run debug\n```\n\nIf you need to pass arguments:\n\n```\nnpm run debug -- [command(s)] [option(s)]\n```\n\n## Contribution\n\nPlease open an [issue](https://github.com/binarymist/mailgun-mate/issues) to discus the proposed change before submitting a [pull request](https://github.com/binarymist/mailgun-mate/pulls).\n\n## Questions\n\nIf you have any questions around the installation, configuration or running of mailgun-mate, please submit an [issue](https://github.com/binarymist/mailgun-mate/issues).\n\n## License\n\nCopyright [Kim Carter](https://github.com/binarymist) and other contributors, Licensed under [MIT](./LICENSE).\n\n[mailgun-js]: https://github.com/bojand/mailgun-js\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarymist%2Fmailgun-mate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinarymist%2Fmailgun-mate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarymist%2Fmailgun-mate/lists"}