automated_emails.md

Automated emails

Our website sends a lot of automated emails to organizers, support team and workshop attendees. This section of our documentation seeks to describe all the automated emails we are sending and how we are sending them for the purpose of making troubleshooting easier and letting users know which emails they can send manually.

This document will cover the following:

• Email backend and APIs used by the website
• Event email creation
• Email sent by the contact app
• Emails sent by the organize app for event applications
• Emails sent by the core app for deployed events
• Emails sent by the applications app to workshop applicants and attendees
• What to do if automatic emails fail
• Adding a new email backend

Email backend and APIs used by the website

We are currently using one email backend and two APIs to send emails from the website:

• Sendgrid - is the email backend we are using to send emails from [email protected] email address to event organizers and Django Girls Support Team. The details of the API are set using the Django setting EMAIL_BACKEND = os.environ.get("EMAIL_BACKEND").
• Gappssmtp - is the API we are using for events to send emails to workshop applicants and attendees using their event email acccounts which are Gmail accounts since our email provider is Google.
• Mailchimp - is the API we are using to manage newsletter signups and send our Django Girls Newsletter using [email protected].

Event email creation

Event email is created automatically when the event is deployed. The admin section has Triage options for event applications, which are Accept application, Move to In Review, Move to Hold and Reject application. If an event application status is changed to Move to in Review or Move to Hold, a comment is added and the status is changed but no email is sent out to the organizers.

However if an event application is accepted or rejected, an email is sent out to the organizers. We will give details about these emails below, in this section, we will only cover how the event email address is created when an event application is accepted.The process is as follows:

1. The Accept application triage option is selected and changes the status to Accepted thereby trigering the EventApplication.deploy() method which creates a new event or clones an existing one if a previous event for that city exists.
2. This new event will trigger the EventApplication.send_deploy_email() method, which triggers the get_or_create_gmail() function from core/gmail_accounts.py and then send login details to event organizers once the email is created or retrieved.
3. The get_or_create_gmail() function calls the get_gmail_account() which calls make_email() function if the event has past team members, or the migrate_gmail_account() then returns create_gmail_account() if the event has been organized us by different organizers before or create_gmail_account() if the event is new in that city.

Emails sent by the contact app

The contact app sends emails to either the Django Girls Support Team or organizers of a selected Django Girls event via the Contact form which is based on the contact model. The email is sent using [email protected] via Sendgrid API.

Emails sent by the organize app for event applications

The organize app sends a couple of emails from the start of the event application process to the end when the event is either are accepted or rejected. These are:

• Send Application Confirmation to event organizers applying to organize an event done by the send_application_confirmation() function called by the OrganizeFormWizard.done() method.
• Send Application Notification to Django Girls Support team that a new event application has been submitted via the send_application_notification() function called by the OrganizeFormWizard.done() method.
• Send Application Deployed Email to event organizers when their event application has been accepted and event deployed done by send_application_deployed_email() called by the method.
• Send Application Rejected Email to event organizers when their event application has been rejected done by send_application_rejection_email() which is called by the method.

Emails sent by the core app for deployed events

The core app has a management command that is run as a scheduled task to send emails to organizers that meet a certain criteria. These are executed through the handle_emails management command which sends out the following emails:

• Thank you emails - these are handled by the send_thank_you_emails() function. They are sent to organizers who just run an event in the previous weekend to say thank you and congratulate them on the success of their event as well ask for statistics.
• Submit information emails - these are handled by the send_submit_information_emails() function. These are sent out to events which took place two weeks prior but have still not updated their statistics on number of applicants and workshop attendees. They are reminder to submit these important details.
• Offer help emails - these are handled by the send_offer_help_emails()function. These are sent to events which are deployed but still do not have a live website or live application form.

Emails sent by the applications app to workshop applicants and attendees

Our Organizer Manual gives guidelines on sending acceptance/rejection emails and RSVPS to applicants and attendees. These emails are saved for each event by the compose_email() view and sent out out by the communication() view.

What to do if automatic emails fail

1. Contact Form emails sent by the contact app - these can be viewed in the admin by opening the ContactEmail model as all emails are saved on submission.
2. EventApplication emails sent by the organize app - these are a bit difficult to resend once an event application has changed state. Organizers can be emailed manually that their event was accepted/rejected and then their event email account or Django Girls admin accounts reset.
3. Event emails sent out by the handle_emails management command - These can be resent automatically when the emails are working as they are sent by automated tasks. It is however important to ensure that these automated tasks are always running and haven't expired.
4. Emails sent by the applications app to workshop applicants and attendees - Organizers can download a CSV of their workshop applicants and attendees and send out the emails manually.

Adding a new email backend/API

We have recently had some phishing emails sent to us using our own domain and to protect our domain we added a Sender Policy Framework (SPF) and DomainKeys Identified Mail (DKIM) policies to our domain on Cloudfare to advertise domains authorized to send emails on behalf of our domain.

This means adding a new email backend/API is not as simple and straightfoward as adding the API key to our environment variable. To add a new email backend/API follow the following steps:

1. Add the API key to the environment variables on PythonAnywhere. Login details are in 1password.
2. Get the new API's DKIM settings.
3. Login to Cloudfare and create a TXT record for the new API (again login details are in 1password).
4. Add the new API's domain to our SPF record on Cloudfare and wait for at least 48hrs for the new domain settings to propagate. And you are all set!