Gmail Notifications

This plugin sends students an email summary of the results of their public test cases using the Gmail API. To use this plugin, you must set up a Google Cloud project and create an OAuth2 Client that can be used as a proxy for another email address.


Before using this plugin, you must first create Google OAuth2 credentials on a Google Cloud project. Using these credentials, you must then obtain a refresh token that connects these credentials to the account from which you want to send the emails. Once you have the credentials, use the gmail_oauth2 CLI included with Otter to generate the refresh token. Use the command below to perform this action, substituting in your credentials client ID and secret.

gmail_oauth2 --generate_oauth2_token --client_id="<client_id>" --client_secret="<client_secret>" --scope=""

This command will prompt you to visit a URL and authenticate with Google, which will then provide you with a verification code that you should enter back in the CLI. You will then be provided with your refresh token.


This plugin requires four configurations: the Google client ID, client secret, refresh token, and the email address from which emails are being sent (the same one used to authenticate for the refresh token).

    - otter.plugins.builtin.GmailNotifications:
        client_secret: abc123
        refresh_token: 1//abc123

Optionally, this plugin also accepts a catch_api_error configuration, which is a boolean indicating whether Google API errors should be ignored.


The email sent to students uses the following jinja2 template:

<p>Hello {{ student_name }},</p>

<p>Your submission {% if zip_name %}<code>{{ zip_name }}</code>{% endif %} for assignment
<strong>{{ assignment_title }}</strong> submitted at {{ submission_timestamp }} received the
following scores on public tests:</p>

<pre>{{ score_report }}</pre>

<p>If you have any questions or notice any issues, please contact your instructors.</p>


<p>This message was automatically generated by Otter-Grader.</p>

The resulting email looks like this:

HTML Email

Note that the report only includes the results of public tests.

otter.plugins.builtin.GmailNotifications Reference

class otter.plugins.builtin.GmailNotifications(submission_path, submission_metadata, plugin_config)

Otter plugin for sending students an email notification with the results of their public test cases. Uses the Gmail API along with user-specified credentials a Google OAuth2 Client to send the emails once grading is finished.

This plugin requires the following configurations:

  • client_id: the Google OAuth2 Client ID

  • client_secret: the Google OAuth2 Client secret

  • refresh_tokem: the Google OAuth2 Client refresh token; more information below

  • email: the email address to send from

It also supports the following optional configurations:

  • catch_api_error: if this configuration is true, errors thrown by Google API calls are ignored; if false, the errors are raised and the grading process stops; defaults to True


Summarizes the results of grading and formats an email to send to the student using the submission metadata. If not submission metadata is supplied, no action is taken.


results (otter.test_files.GradingResults) – the results of grading

property service

The Google API service