[Internal] Sending bulk email via main site

Bulk email notes

These notes describe how the bulk_email management command can be used by staff with admin access to the main site, to send newsletters and other emails out to Open Humans members.

Note from Mad: Pretty much every time I use this command, I'm cautious and do things like...

• edit the management command itself for some sanity checks (like adding a premature print and return)
• before doing a real email, run it WITHOUT the Mailgun environment variable and watch console output
• send to a test email list of myself, people that are helping test

Currently it's pretty hacky. So... notes.

Local files and configurations

Local files and configurations are used in conjunction with the production site to send emails. Dangerous information is in bold (be careful with these, and don't put in git).

• .env configuration never in git!
  • DATABASE_URL: set to read-only production database in Heroku
  • MAILGUN_PASSWORD: taken from Heroku – don't leave this set! your local repository has the power to email all users with this!
  • BULK_EMAIL_TEMPLATE_DIR: full path to local dir your templates are in (matches the -t flag)
• files
  • Email list - be careful this doesn't end up in git!
  • Email content subject: .subject suffix
  • Email content text: .txt suffix
  • Email content html: .html suffix

Note: The same base name is used for all the email content files, and the suffixes should match the patterns above.

Email list

e.g. path/to/email-list.csv

CSV containing a list of email addresses in the first column, plus optional additional fields that will be used to mail merge. For example:

email,usertoken
someone@example.com,7wVNS4lxWgYn
anotherguy@example.com,iFdWgZUrIbzA

Email content

Subject

e.g. path/to/email-content.subject

Text on a single like. For example:

Open Humans: Please read this!

Text

e.g. path/to/email-content.txt

Text version of email content. This uses Django templating and can use information from the User object with {{ user }}, as well as any custom merge fields provided in the email list (e.g. {{ usertoken }}). Note that text emails should have a max of 78 characters per line. For example:

Dear {{ user.username }},

We'd love to know more about you.

Please follow this link to fill out a form:
https://www.example.com/form?usertoken={{ usertoken }}

Thanks so much,

Open Humans

HTML

e.g. path/to/email-content.html

HTML version of email content. For example:

<p>Dear {{ user.username }},</p>

<p>We'd love to know more about you.</p>

<p>
Please follow this link to fill out a form:
<a href="https://www.example.com/form?usertoken={{ usertoken }}">
https://www.example.com/form?usertoken={{ usertoken }}
</a></p>

<p>Thanks so much,</p>

<p>Open Humans</p>

Running the command

The -t flag specifies the basename for all email content files, and the -e flag specifies the email list CSV. Run the command within your virtual environment, with .env variables applied, for example:

python -Wi manage.py bulk_email -t 20180808_foobar_mail/201800808-foobar -e 20180808_foobar_mail/20180808-foobar-list-batch1.csv