Configuring email

Last updated:

PostHog's core relies on email messaging for certain functionality. For example:

  • Sending a reset link to a user that has forgotten their password.
  • Sending an invite link for new team members to join PostHog.

By default, PostHog will not send email messages until you enable an SMTP server. We very strongly recommend using an email service to act as email server (see examples below for most common providers). These providers are optimized to maximize email deliverability.

To prevent spam, most email providers have very complex systems in place that validate a myriad of factors before allowing an email through. Optimizing local servers for this is a bit like reinventing the wheel, so avoid this unless you have a very strong reason not to.

General configuration

To configure a remote email server, you will need to head over to Instance settings and set up the following parameters (please note that if you're running PostHog older than 1.33.0, you will need to configure these parameters via environment variables):

  • EMAIL_HOST: Defaults to None. Hostname to connect to for establishing SMTP connections.
  • EMAIL_PORT: Defaults to 25. Port that should be used to connect to the host.
  • EMAIL_HOST_USER: Defaults to null. Credentials to connect to the host.
  • EMAIL_HOST_PASSWORD: Defaults to null. Credentials to connect to the host.
  • EMAIL_USE_TLS: Defaults to false. Whether to use TLS protocol when connecting to the host.
  • EMAIL_USE_SSL: Defaults to false. Whether to use SSL protocol when connecting to the host.
  • EMAIL_DEFAULT_FROM: Defaults to [email protected]. Email address that will appear as the sender in emails (From header).
  • EMAIL_ENABLED: Defaults to true. Whether email service is enabled or not.
  • SITE_URL: Defaults to http://localhost:8000. Not unique to the email service, but it needs to be set for emails to work properly. Principal URL of your PostHog instance.

Sample configuration:

EMAIL_HOST: smtp.example.com
EMAIL_PORT: 587
EMAIL_HOST_USER: [email protected]
EMAIL_HOST_PASSWORD: password
EMAIL_USE_TLS: false
EMAIL_USE_SSL: true
EMAIL_DEFAULT_FROM: no-[email protected]
SITE_URL: https://posthog.example.com

The above sample configuration can also be set in your values.yaml this way, however configuring your email service with Instance settings instead is highly recommended (this is because environment variables are only read when there are no values set from the UI/API, i.e. the values set from the UI/API take precedence, as such setting them here can help you ensure you have a single source of truth):

email:
from_email: no-[email protected]
host: smtp.example.com
port: 587
password: password
use_tls: false
use_ssl: true

Below you will find details on how to configure the most common email providers (not in any particular order).

Twilio's Sendgrid

With Sendgrid you have 2 different configuration options.

Domain authentication allows you to send emails from any address within your validated domain. It is the best option to guarantee email deliverability because it establishes DNS records on your domain that validate your identity.

  1. On sender authentication, select the option to authenticate a domain, you can also go directly to https://app.sendgrid.com/settings/sender_auth/domain/create.

  2. Fill out the required details for the domain you wish to configure. We recommend using the default configuration. If you do not use the advanced settings option please be sure to properly configure DKIM and SPF records to ensure deliverability.

  3. You will receive now a list of DNS records that need to be added to your domain. After adding them, be sure to verify them on Sendgrid. You are now ready to start sending emails.

Option B: Single sender authentication

As an alternative you can do single sender verification which is the easiest option to configure. You will only need to be able to receive emails on the address you want to use as sender. Please note this method is only recommended as a starting point, or for small scale usage.

  1. On sender authentication, select the option to create a new sender profile, you can also go directly to https://app.sendgrid.com/settings/sender_auth/senders/new.

  2. Fill out the form with the required details, see an example below.

Configuring Sendgrid

  1. Validate the email address by clicking on the link you will receive.

After you have set up your sending configuration, you can continue below to set up your credentials and configure to send emails with Sendgrid.

  1. To create the required credentials, go to Settings > API keys and click on "Create API key".

  2. Set a name for your API key, we recommend using "PostHog", and select the "Restricted Key" option. You will need to enable the "Mail Send" permission as detailed below. Copy the key directly to your instance configuration.

API Sendgrid

  1. With the key you created above, you can now set your instance configuration in PostHog:

    EMAIL_HOST: smtp.sendgrid.net
    EMAIL_PORT: 587
    EMAIL_HOST_USER: apikey # same for everyone
    EMAIL_HOST_PASSWORD: SG.rqHsfjxZPiqE5lqXTgQ_lz7x7IVLv # obtained from step above
    EMAIL_USE_TLS: true
    EMAIL_USE_SSL: false
    EMAIL_DEFAULT_FROM: [email protected] # you can define this, just use your domain or single sender address
    SITE_URL: https://posthog.example.com # this is the URL of your instance
  2. Test your integration! Whenever updating email settings, we will attempt to send you a test email so you can assert everything is working as expected. Please note that if you update these settings via environment variables, you need to restart your server and test sending an email (e.g. request a password reset).

    Remember that you will need to restart both your web server and background worker for this to work properly.

  1. As an additional optional step, we recommend turning off 'open & click tracking' to avoid having weird-looking links and increase deliverability (there's little value in having this data). You can do so by going to tracking settings.

Sendgrid Config

Mailgun

  1. After you have created an account, go to Sending > Domains, and click on "Add New Domain".

  2. Enter a domain name that you own. Using a subdomain is recommended (e.g. m.posthog.com instead of posthog.com). We strongly recommend selecting "Create DKIM Authority" (and using 2048 bits) to prevent spoofing with your domains (read more about DKIM). See sample configuration below:

  3. You will now be given instructions to set up certain DNS records in your domain. Please be sure to add all requested records to ensure proper email deliverability. If not provided, we also recommend adding the following SPF record to prevent email forgery with your domain.

    TXT @ v=spf1 include:mailgun.org ~all
  4. Once you have added all records and verify them you can go to the domain settings > "SMTP credentials" section. You then need to create a set of SMTP credentials.

  5. With the SMTP credentials, you can now set the required settings for email to work properly. You will also need to obtain the hostname from the credentials page. Your configuration should now look something like this.

    EMAIL_HOST: smtp.eu.mailgun.org # obtained from credentials page
    EMAIL_PORT: 587
    EMAIL_HOST_USER: [email protected] # obtained from credentials page
    EMAIL_HOST_PASSWORD: password # obtained from credentials page
    EMAIL_USE_TLS: true
    EMAIL_USE_SSL: false
    EMAIL_DEFAULT_FROM: [email protected] # you can define this, just use your domain
    SITE_URL: https://posthog.example.com # this is the URL of your instance
  6. Test your integration! Whenever updating email settings, we will attempt to send you a test email so you can assert everything is working as expected. Please note that if you update these settings via environment variables, you need to restart your server and test sending an email (e.g. request a password reset).

    Remember that you will need to restart both your web server and background worker for this to work properly.

Questions?