Sending Notifications

Tabbycat offers integrations with email delivery services to send notifications to participants on certain enumerated events. Before you can use them, you will need to configure your app to use an external email provider, such as SendGrid, Mailgun or MailChimp.

Configuring an email provider

Changed in version 2.6: Tabbycat no longer automatically provisions SendGrid via Heroku.

Tabbycat does not come with an email provider. You will need to configure your app to use a third-party email provider. Your Tabbycat site will not be able to send emails until you have done this. There are a number of options for this. The right one for you will depend on your tournament size and budget.

SendGrid

To use SendGrid, you’ll need to create your own (personal or business) SendGrid account. The free tier is unlikely to suffice. If you’re a student, you may be eligible for SendGrid’s (free) offer under the GitHub Education Pack.

Once you have a SendGrid account:

  1. Create an API key in your SendGrid account.

There are instructions for how to do this in the SendGrid documentation. The only permission that is needed is the “Mail Send” permission, so you can turn off all others if you want to be safe.

  1. Set the following config vars in Heroku Dashboard (or using the Heroku CLI, if you have it):

  • Set SENDGRID_API_KEY to your API key, which will start with SG.*******.

  • Set DEFAULT_FROM_EMAIL to the email address you want your emails to appears as coming from. This will probably need to be an email address that you can verify ownership of to SendGrid (see next step).

  1. You’ll probably need to complete sender authentication on SendGrid by following these instructions in the SendGrid documentation. Specifically, if sending a test email raises an error about “not matching a verified Sender Identity” (this is likely), you need to complete one of the two methods listed there:

  • Single Sender Verification, if you’re comfortable with all of Tabbycat’s emails coming from an email address that belongs to you and exists (e.g. your personal email address). This is more likely to be convenient for most users.

  • Domain Authentication, if you have access to a domain whose DNS record you control, e.g. a tournament or society website hosted on its own domain.

  1. Send a test email using the tool on your Tabbycat site’s home page.

Changed in version 2.6: The SENDGRID_USERNAME and SENDGRID_PASSWORD config vars are deprecated in favour of SENDGRID_API_KEY.

Upgrading from legacy settings

If you’ve recently upgraded to version 2.6, and need to update your config vars, follow these instructions. First, check if the value of the config var SENDGRID_USERNAME is apikey. If it is, you can do the following:

  1. Create a new config var SENDGRID_API_KEY, and copy the value from SENDGRID_PASSWORD to it. This value should start with SG.******. Be sure you have the value saved (try sending a test email now) before you continue.

  2. Delete the config vars SENDGRID_USERNAME and SENDGRID_PASSWORD (whose value you just copied over).

  3. If it’s not already set, set DEFAULT_FROM_EMAIL to the email address you want your emails to appears as coming from.

If the value of SENDGRID_USERNAME is anything other than apikey, you’ll need to convert your SendGrid configuration to use an API key instead. To do so, follow the instructions under SendGrid above. Then, delete the old SENDGRID_USERNAME and SENDGRID_PASSWORD config vars.

Other email providers

If you configure these config vars, Tabbycat will use them to send emails.

  • DEFAULT_FROM_EMAIL: Email to send from

  • EMAIL_HOST: Host server

  • EMAIL_HOST_USER: Username for authentification to host

  • EMAIL_HOST_PASSWORD: Password with username

  • EMAIL_PORT (default 587): Port for server

  • EMAIL_USE_TLS (default true): Whether to use Transport Layer Security (true or false)

Events

Tabbycat includes a number of templated notifications that can be sent in various times. Variables which are included between curly brackets which are substituted for personalized information passed by email. Links to email will redirect to a page where the message can be changed and the participants selected.

All emails have the {{ USER }} and {{ TOURN }} variables to indicate who the email is sent to, and the tournament it relates to. The “From” in the emails will also be the tournament’s name.

Email content and description

Variables

Adjudicator draw notification

Email to adjudicators indicating their room assignment.

Available through the admin draw page.

  • {{ ROUND }}: The round name

  • {{ VENUE }}: The venue of the assigned debate

  • {{ PANEL }}: A list of all the adjudicators assigned to the venue (with positions)

  • {{ DRAW }}: A list of the team matchup with their roles

  • {{ POSITION }}: The target adjudicator’s position in the panel

  • {{ URL }}: A link to the adjudicator’s private URL page

Team draw notification

Email to teams indicating their pairing.

Available through the admin draw page.

  • {{ ROUND }}: The round name

  • {{ VENUE }}: The venue of the assigned debate

  • {{ PANEL }}: A list of all the adjudicators assigned to the venue (with positions)

  • {{ DRAW }}: A list of the team matchup with their roles

  • {{ TEAM }}: The team’s code or short name

  • {{ SIDE }}: The team’s side

Private URL distribution

Email to participants giving them their private URL for electronic forms.

Available through the private URLs page.

  • {{ URL }}: The personalized URL

  • {{ KEY }}: The private code in the URL

Ballot submission receipt

Email to adjudicators of their ballot after tabroom confirmation.

Sent automatically when their ballot’s result status becomes confirmed, if enabled in the “Notifications” section of the tournament options.

  • {{ DEBATE }}: The name (with round & venue) of the relevent debate

  • {{ SCORES }}: The submitted ballot with speaker scores and team names

Current team standings

Email to speakers with their point total.

Available through the “Confirm Round Completion” page.

  • {{ URL }}: The URL of the team standings page (if public)

  • {{ TEAM }}: The team’s name

  • {{ POINTS }}: The team’s number of points

Motion release

Email to speakers with the motion(s) of the current round.

Available through the admin draw page.

  • {{ ROUND }}: The name of the round

  • {{ MOTIONS }}: A list of the motions released

Team information

Email to speakers with information pertaining to their team, such as eligibility and codes.

Available through the Participants page.

  • {{ SHORT }}: The team’s short name

  • {{ LONG }}: The team’s long name

  • {{ CODE }}: The team’s code name

  • {{ EMOJI }}: The team’s assigned emoji

  • {{ BREAK }}: Break categories which the team is a member

  • {{ SPEAKERS }}: A list of the speakers in the team

  • {{ INSTITUTION }}: The team’s affiliation

Event Webhook

With SendGrid, the status of sent emails can be sent to Tabbycat to be displayed, giving an indication of failures and whether participants have opened the messages. To activate this feature, setup must be done both in your SendGrid account and in Tabbycat.

  1. Set a secret key in the Email section of the tournament’s preferences. This key must be alphanumeric without any spaces.

  2. Copy the “web-hook” link presented in a box at the top of the “email participants” page.

  3. Go to https://app.sendgrid.com/settings/mail_settings and select “Event Notifications”

  4. Enable the feature and paste the Tabbycat URL under “HTTP POST URL”.

  5. Select the notifications to keep track (or all of them).

Caution

Each email and change in status sent to Tabbycat will add a row to the database. If the number of rows is limited, as is for free Heroku apps, enabling the webhook may use up a significant number of rows. Be selective in the events to keep track.