Configure email sending / SMTP server

Sourcegraph uses an SMTP server of your choosing to send emails for:

  • Code Monitoring notifications
  • Inviting other users to a Sourcegraph instance, or to an organization/team on a Sourcegraph instance
  • Important updates to a user accounts (for example, creation of API keys)
  • For builtin authentication, password resets and email verification

Configuring Sourcegraph to send email via Amazon AWS / SES

To use Amazon SES with Sourcegraph, first follow these steps to create an SES account for Sourcegraph.

Navigate to your site configuration (e.g. https://sourcegraph.com/site-admin/configuration) and fill in the configuration:

  "email.address": "[email protected]",
  "email.smtp": {
    "authentication": "PLAIN",
    "username": "<SES SMTP username>",
    "password": "<SES SMTP password>",
    "host": "email-smtp.us-west-2.amazonaws.com",
    "port": 587
  },

Please note that the configured email.address (the from address) must be a verified address with SES, see this page for details.

Send a test email to verify it is configured properly.

Configuring Sourcegraph to send email via Google Workspace / GMail

To use Google Workspace with Sourcegraph, you will need to create an SMTP Relay account. Be sure to choose Require SMTP Authentication and Require TLS encryption in step 7.

Navigate to your site configuration (e.g. https://sourcegraph.com/site-admin/configuration) and fill in the configuration:

  "email.address": "[email protected]",
  "email.smtp": {
    "authentication": "PLAIN",
    "username": "[email protected]",
    "password": "<YOUR SECRET>",
    "host": "smtp-relay.gmail.com",
    "port": 587,
    "domain": "domain.com"
  },

Make sure that [email protected] in both places of the configuration matches the email address of the account you created, and that <YOUR SECRET> is replaced with the account password or app password when 2FA enabled.

Send a test email to verify it is configured properly.

Configuring Sourcegraph to send email using another provider

Other providers such as Mailchimp and Sendgrid may also be used with Sourcegraph. Any valid SMTP server account should do. For those two providers in specific, you may follow their documentation:

Once you have an SMTP account, simply navigate to your site configuration (e.g. https://sourcegraph.com/site-admin/configuration) and fill in the configuration:

  "email.address": "[email protected]",
  "email.smtp": {
    "authentication": "PLAIN",
    "username": "[email protected]",
    "password": "<YOUR SECRET>",
    "host": "smtp-server.example.com",
    "port": 587
  },

A few helpful tips:

  • email.address is the email Sourcegraph will send email FROM. Make sure your account has privilege to send mail from that address.
  • You should use a TLS/SSL enabled port, either 587 or 2525. Any port number is allowed, though.
  • The following authentication types are allowed: PLAIN (default), CRAM-MD5, and none
  • If a HELO domain is required, simply add "domain": "<the domain>", under email.smtp
  • TLS certificate verification can be disabled if your SMTP server does not have a valid TLS cert. To do so, set "noVerifyTLS": true, (this is not recommended and may be a security risk)

Send a test email to verify it is configured properly.

Sending a test email

(Added in Sourcegraph v3.38)

To verify email sending is working correctly, visit the GraphQL API console at e.g. https://sourcegraph.example.com/api/console and then run the following query replacing [email protected] with your personal email address:

mutation {
  sendTestEmail(to: "[email protected]")
}

If everything is successfully configured, you should see a response like:

{
  "data": {
    "sendTestEmail": "Sent test email to \"[email protected]\" successfully! Please check it was received."
  }
}

Otherwise, you should see an error with more information:

{
  "data": {
    "sendTestEmail": "Failed to send test email: mail: ..."
  }
}

If you need further assistance, please let us know at mailto:[email protected].