# spmailer > Send targeted "action-needed" emails Latest version **0.2.4** (published 2023-03-31) · 0 weekly downloads ## Install ```sh npm install spmailer pnpm add spmailer yarn add spmailer bun add spmailer ``` Provides the command `spmailer`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.2.4 | | Published | 2023-03-31 | | First published | 2023-03-30 | | Weekly downloads | 0 | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 5 | | Unpacked size | 34.7 KB | | Known vulnerabilities | 0 (+16 in 2 direct dependencies) | | Install scripts | no | | Author | Mitchell Hentges | | Maintainers | mitchhentgesspotify | ## Links - npm: https://www.npmjs.com/package/spmailer - npm.io page: https://npm.io/package/spmailer ## Dependencies (5) - [nunjucks](https://npm.io/package/nunjucks.md) ^3.2.3 - [commander](https://npm.io/package/commander.md) ^10.0.0 - [csv-parse](https://npm.io/package/csv-parse.md) ^5.3.6 - [dedent-js](https://npm.io/package/dedent-js.md) ^1.0.1 - [nodemailer](https://npm.io/package/nodemailer.md) ^6.9.1 ## Recent versions - 0.2.4 (latest) — 2023-03-31 - 0.2.3 — 2023-03-31 - 0.2.2 — 2023-03-31 - 0.2.1 — 2023-03-31 - 0.2.0 — 2023-03-30 - 0.1.1 — 2023-03-30 - 0.1.0 — 2023-03-30 ## README # Spmailer _Send targeted "action-needed" emails_ Sometimes, your squad needs to do a large-scale migration with the collaboration of downstream squads. So, you build up a nice spreadsheet of where work is needed, then you notify the downstreams with a polite link to the spreadsheet. Unfortunately, this puts a bit of a burden on the downstream squads: * They need to search through a _potentially huge_ spreadsheet to find out which specific "things" this email is about * If they're a member of multiple groups, they need to look through the spreadsheet for _each one_ * Due to this added effort, it's harder for downstreams to triage how much effort such an email entails, and they're more likely to defer it. Instead, this tool should make it easier to submit "personalized" emails for each affected group, so they can see _at a glance_ what work needs to be done. ## Usage First, generate a Google App Password so that emails can be sent from your account: 1. [Go to the Google App Passwords page](https://myaccount.google.com/apppasswords) 2. Click the `Select app` dropdown and choose "Other", write `spmailer` into the provided input field 3. Click `GENERATE` 4. In your terminal, export two environment variables: * `export GMAIL_USERNAME=` * `export GMAIL_APP_PASSWORD=` Create an email template file. Put your subject first, followed by a line with `-----`: ``` You have {{ rows | length }} components that depend on the soon-deprecated "foo" service ----- Hello {{ recipient }} We will be deprecating the glorious "foo" service soon. We are telling you this because you own components that still depend on "foo", and should migrate to "bar" instead. {% for row in rows -%} * https://backstage.spotify.net/components/{{ row.componentId }} {% endfor -%} Thank you for your understanding in these trying times, The "foo" fighters ``` Next, formulate your data of "teams to email" into a CSV file: ``` recipient,componentId team-a@spotify.com,service-1 team-a@spotify.com,service-2 team-b@spotify.com,service-3 ``` Finally, run `spmailer`: ```shell npx spmailer foo.template foo.csv Sent 2 emails! ``` To test your emails before submission, you can run the following and look at the files in the created `spmailer-dry-run` folder: ```shell npx spmailer foo.template foo.csv --dry-run ``` ## Templating The template is rendered with [Mozilla Nunjucks](https://mozilla.github.io/nunjucks/templating.html). The context (variables) provided to the template take the following form: ```json { "recipient": "", "": "" "...": "...", "rows": [ { "": "", "...": "..." } ] } ``` The variables provided are based on the columns in your CSV file. "Grouped" variables are always the same for a recipient, while "row" variables are one-to-one with row fields in the CSV spreadsheet. You can designate the difference between "grouped" and "ungrouped" variables using the `ENDGROUP` column name. For example: ``` recipient,team,city,ENDGROUP,componentId,repository team-a@spotify.com,A team,Stockholm,,sysmodel,https://ghe.spotify.net/tools/sysmodel team-a@spotify.com,A team,Stockholm,,backstage-frontend,https://ghe.spotify.net/backstage/backstage-frontend/ team-b@spotify.com,Bees,Madrid,,backstage-backend,https://ghe.spotify.net/backstage/backstage-backend team-c@spotify.com,Cruisin,New Yawk,,jarvis,https://ghe.spotify.net/tools/jarvis team-c@spotify.com,Cruisin,New Yawk,,dashd,https://ghe.spotify.net/tools/dashd ``` This will be available to the template as: ```json { "recipient": "team-a@spotify.com", "team": "A team", "city": "Stockholm", "rows": [ { "componentId": "sysmodel", "repository": "https://ghe.spotify.net/tools/sysmodel" }, { "componentId": "backstage-frontend", "repository": "https://ghe.spotify.net/backstage/backstage-frontend" } ] } { "recipient": "team-b@spotify.com", "team": "Bees", "city": "Madrid", "rows": [ { "componentId": "backstage-backend", "repository": "https://ghe.spotify.net/backstage/backstage-backend" } ] } { "recipient": "team-c@spotify.com", "team": "Cruisin", "city": "New Yawk", "rows": [ { "componentId": "jarvis", "repository": "https://ghe.spotify.net/tools/jarvis" }, { "componentId": "dashd", "repository": "https://ghe.spotify.net/tools/dashd" } ] } ``` Which could then be used in a template like: ``` Be advised, you own some components ----- Hello {{ team }} from {{ city }}, you own the following things: {% for row in rows -%} * {{ row.componentId }} at {{ row.repository }} {% endfor -%} ``` Which would be rendered into three emails. The one to `team-c@spotify.com` would have the subject `Be advised, you own some components`, and the body would look like: ``` Hello Cruisin from New Yawk, you own the following things: * jarvis at https://ghe.spotify.net/tools/jarvis * dashd at https://ghe.spotify.net/tools/dashd ``` --- _Source: https://npm.io/package/spmailer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._