Sponsor Emails

Automatically send sponsorship emails using Google Docs, Google Sheets, and MailGun.

Installation & Usage

sponsor-emails can be downloaded as a Python package from the Actions tab, or it can be installed directly with Pip.

# Pip from source
pip install git+https://github.com/WaffleHacks/sponsor-emails.git

# Pip from downloaded wheel
pip install ~/Downloads/sponsor_emails_3.9.whl

# Running
sponsor-emails --help

You can also use Pipx to install and run sponsor-emails in a virtual environment.

pipx run --spec git+https://github.com/WaffleHacks/sponsor-emails.git sponsor-emails --help

Configuration

Once you have sponsor-emails installed, run sponsor-emails validate to generate the default configuration. This should error as there are some necessary details you will need to fill in, such as your GCP and MailGun credentials.

GCP Service Account

1. Register for a Google Cloud Platform account, if you don't already have on
2. Enable the APIs for Google Docs, Google Drive, and Google Sheets
   1. Navigate to the APIs & Services page
   2. Click on "Enable APIs and Services" near the top
   3. Search for and enable the "Google Docs API", "Google Drive API", and "Google Sheets API"
3. Create a Service Account to access the APIs with
   1. Navigate to "Credentials" on the APIs & Services page
   2. Click on "Create Credentials" near the top and select "Service account"
   3. Fill out the name, id, and, optionally, the description; then click "Done"
   4. Click on "Manage service accounts" on the right by the "Service Accounts" header
   5. Click the three dots (⋮) near your recently created service account and select "Manage keys"
   6. Click on "Add Key", then select "Create new key" and use the JSON format
   7. Save the downloaded key somewhere safe and remember its location for later
4. Share any Google Docs or Google Sheets with the service account's email using the standard "Share" button
5. Copy the path to the service account file into the credentials.gcp in config.json field. Ex:

{
   "credentials": {
      "gcp": "/path/to/your/service-account.json"
   }
}

MailGun API Access

1. Register for a MailGun account, if you don't already have one
2. Add your domain if you haven't already, following the offical docs
   • You can use the automatically added sandbox domain, but it should only be used for testing
3. Get your private API key from the "API Keys" page
   1. Go to the "API Keys" page under "Settings" in the sidebar
   2. Copy the key under "Private API key"
4. Paste the API key and domain into config.json at credentials.mailgun_api_key and credentials.mailgun_domain respectively. Ex:

{
   "credentials": {
      "mailgun_domain": "your.domain.com",
      "mailgun_api_key": "afffeag-your-api-key-afgjo"
   }
}

Documents and Sheets

1. Configure the template document
   1. Copy the URL for your Google Doc and paste it into template.url
   2. Add your placeholders for the company's name, contact's name, and sender's name under template.placeholders. These are all case-sensitive.
2. Configure the sponsors spreadsheet
   1. Copy the URL for your Google Sheet and paste it into sponsors.url
   2. Put the name of the worksheet (ex. "Sheet 1") into sponsors.sheet
   3. Put the statuses for your messages into sponsors.statuses.
      • The sponsors.statuses.sent will be set when a message gets successfully sent
      • The sponsors.statuses.pending will be set when a message fails to send
      • If the status is not equal to sponsors.statuses.pending before sending, the message will not be sent
   4. Set the column headers in sponsors.headers to the respective columns in your spreadsheet
   5. If you have a sponsorship package (example), put copy the path to sponsors.package, otherwise set it to null
3. Configure the senders spreadsheet
   1. Copy the URL for your Google Sheet and paste it into senders.url
   2. Put the name of the worksheet (ex. "Sheet 2") into senders.sheet
   3. Set senders.header to the name of the column with the organizer's first and last names
   4. Set senders.reply_to to the email that messages should reply to

Validation

To ensure your configuration is correct, run sponsor-emails validate.

Development

You will need to install Poetry and a recent version of Python (3.8+). Then install the dependencies with poetry install.

The application entrypoint is in sponsor_emails/cli.py.