Synapse

Synapse randomly pairs people in an organization for 1-on-1's on a regular schedule.

Setup

• Install uv

Google spreadsheet

Create a Google Spreadsheet that has the first column with emails address. Make sure to share it with the relevant service account (see Environment Variables). Example:

Environment variables

• SYNAPSE_VALID_EMAIL_REGEX: (required) Regex to filter out emails that are valid for sending to. Example: @example\.com$
• SYNAPSE_SPREADSHEET: (optional) The Google spreadsheet ID to pull emails from. Can be provided via CLI.
• SYNAPSE_SHEET: (optional) The Google worksheet ID to pull emails from. Defaults to 0; can be provided via CLI.
• SYNAPSE_GOOGLE_SERVICE_ACCOUNT: (required) The JSON token for the Google service account that has access to the Google Drive and Google Sheets.
  • The format should be something like this; make sure to escape double quotes and new line characters (or remove): \

    GOOGLE_SERVICE_ACCOUNT="{
      \"type\": \"service_account\",
      \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nXXXX...YYYY\\n-----END PRIVATE KEY-----\\n\",
      \"client_email\": \"project@project.iam.gserviceaccount.com\",
      \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",
      \"token_uri\": \"https://oauth2.googleapis.com/token\",
      \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",
      \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/project%40project.iam.gserviceaccount.com\"
    }"

  • Make sure the email for the service account is shared with the document that is meant to be written to.
  • Helpful reference: gspread auth
• SYNAPSE_MAILGUN_API_KEY: (required) Mailgun API key.
• SYNAPSE_MAILGUN_DOMAIN: (required) The Mailgun sending domain, e.g. mg.example.com.
• SYNAPSE_MAILGUN_FROM: (required) The From header to use, e.g. Synapse <synapse@mg.example.com>.
• SYNAPSE_GMAIL_USERNAME: (optional, for testing only) The Google Mail account to send emails from.
• SYNAPSE_GMAIL_APP_PASSWORD: (optional, for testing only) The Google Mail account's password, specifically should use an App Password.

Usage

uv run synapse

More examples:

• Help uv run synapse --help
• Don't send emails: uv run synapse --no-send

Options

• --no-send: Do not actually send emails.
• --send: Send emails without confirmation.
• --spreadsheet: The Google Spreadsheet ID to save output to.
• --sheet: The Google Spreadsheet Sheet ID to save output to. Utilizes relevant environment variable if not provided. Defaults to 0 if neither supplied.
• --email-mode-test: Send via Mailgun in test mode. Mailgun accepts the request but does not deliver the email.
• --email-transport: Email transport to use, either mailgun (default) or gmail. Gmail sends via SMTP and is intended for local testing only; it requires an interactive confirmation.
• --email-test: Send a single email to two addresses given as a comma-separated pair (e.g. a@example.com,b@example.com). Skips loading emails from the spreadsheet and does not read or save history.

Contributing

See docs/CONTRIBUTING.md.

License

Licensed under the LGPL 3.0; see LICENSE.txt for details.