Configure SMTP Server

ThunderID sends emails through an SMTP server for features such as magic link authentication and user invitations. This guide explains how to configure an SMTP server so that ThunderID can send emails on your behalf.

note

SMTP configuration is optional. Without a configured SMTP server, email-dependent features such as magic link authentication and user invitations remain unavailable. All other ThunderID features continue to operate normally.

Prerequisites

• You have access to an SMTP server (for example, Gmail, Amazon SES, SendGrid, or a self-hosted mail server).
• You have SMTP credentials (username and password) if your server requires authentication.

Configuration Properties

The following properties are available for SMTP configuration in deployment.yaml, located in your ThunderID installation directory.

Property	Default	Required	Description
email.smtp.host	""	Yes	Hostname of the SMTP server (for example, smtp.gmail.com).
email.smtp.port	0	Yes	Port of the SMTP server. Use 587 for STARTTLS.
email.smtp.username	""	Conditional	Username for SMTP authentication. Required when enable_authentication is true.
email.smtp.password	""	Conditional	Password for SMTP authentication. Required when enable_authentication is true.
email.smtp.from_address	""	Yes	Email address that appears in the From field of outgoing emails.
email.smtp.enable_start_tls	true	No	Enables explicit STARTTLS encryption for the SMTP connection. See Connection Security.
email.smtp.enable_authentication	true	No	Enables SMTP authentication with the configured username and password. See Authentication.

Set Up the SMTP Connection

1. Open deployment.yaml in a text editor.

2. Add or update the email section with your SMTP server details:

   email:
     smtp:
       host: "smtp.example.com"
       port: 587
       username: "your-username"
       password: "your-password"
       from_address: "noreply@example.com"
       enable_start_tls: true
       enable_authentication: true

3. Save the file and restart ThunderID for the changes to take effect.

Provider-Specific Examples

Gmail

1. Sign in to your Google Account.

2. Enable two-step verification if you have not already. Go to Security > 2-Step Verification and follow the prompts.

3. Generate an App Password. Go to Security > 2-Step Verification > App passwords, select Mail as the app, and click Generate. Copy the generated 16-character password.

4. Add the following configuration to your deployment.yaml:

   email:
     smtp:
       host: "smtp.gmail.com"
       port: 587
       username: "your-email@gmail.com"
       password: "your-app-password"
       from_address: "your-email@gmail.com"
       enable_start_tls: true
       enable_authentication: true

5. Replace your-email@gmail.com with your Gmail address and your-app-password with the App Password generated in step 3.

For more details, see the Gmail App Passwords documentation.

note

Google Workspace administrators can disable App Passwords for the organization. If the App passwords option does not appear, contact your Workspace administrator to enable it.

Amazon SES

1. Sign in to the AWS Management Console and open the Amazon SES console.

2. Verify a sender identity. Go to Verified identities and verify either a domain or an individual email address. Amazon SES sends emails only from verified identities.

3. If your account is in the SES sandbox, request production access. Go to Account dashboard and click Request production access. Sandbox accounts can send only to verified email addresses.

4. Generate SMTP credentials. Go to SMTP Settings and click Create SMTP Credentials. This creates an IAM user with an SMTP username and password. Copy both values.

5. Note the SMTP endpoint for your AWS region (for example, email-smtp.us-east-1.amazonaws.com). Find the endpoint on the SMTP Settings page.

6. Add the following configuration to your deployment.yaml:

   email:
     smtp:
       host: "email-smtp.us-east-1.amazonaws.com"
       port: 587
       username: "your-ses-smtp-username"
       password: "your-ses-smtp-password"
       from_address: "noreply@your-verified-domain.com"
       enable_start_tls: true
       enable_authentication: true

7. Replace the host with your region-specific endpoint, the credentials with values from step 4, and the from_address with a verified identity from step 2.

For more details, see the Amazon SES SMTP documentation.

note

SES SMTP credentials are separate from your AWS access keys. Always generate dedicated SMTP credentials through the SES console.

SendGrid

1. Sign in to your SendGrid account.

2. Verify a sender identity. Go to Settings > Sender Authentication and complete either domain authentication or single sender verification.

3. Create an API key. Go to Settings > API Keys, click Create API Key, select Restricted Access, and enable the Mail Send permission. Copy the generated API key.

4. Add the following configuration to your deployment.yaml:

   email:
     smtp:
       host: "smtp.sendgrid.net"
       port: 587
       username: "apikey"
       password: "your-sendgrid-api-key"
       from_address: "noreply@your-domain.com"
       enable_start_tls: true
       enable_authentication: true

5. Keep the username as the literal string apikey. Replace your-sendgrid-api-key with the API key from step 3, and set from_address to the verified sender from step 2.

For more details, see the SendGrid SMTP documentation.

note

SendGrid displays API keys only once during creation. Store the key securely before closing the dialog.

Configure SMTP on Kubernetes

The Helm chart generates deployment.yaml from your values file, so set the SMTP properties under configuration.email.smtp instead of editing the file directly. The value names are camelCase versions of the properties in Configuration Properties.

configuration:
  email:
    smtp:
      host: smtp.example.com
      port: 587
      fromAddress: noreply@example.com
      username: your-username
      password: your-password
      enableStartTls: true
      enableAuthentication: true

The chart stores an inline password in the generated thunderid-db-credentials Secret and injects it as the SMTP_PASSWORD environment variable. To keep the password out of your values file, put it in your own Secret and reference it with passwordRef:

configuration:
  email:
    smtp:
      host: smtp.example.com
      port: 587
      fromAddress: noreply@example.com
      username: your-username
      passwordRef:
        name: thunderid-smtp
        key: password

Create that Secret before you install the chart:

kubectl create secret generic thunderid-smtp \
  --from-literal=password=<your-smtp-password> \
  --namespace thunderid

While host is empty, the chart omits the email section and email-dependent features remain unavailable. Once you set host, port and fromAddress are required, and Helm fails the install if either is missing.

For the rest of the Kubernetes deployment settings, see Deploy on Kubernetes.

Connection Security

ThunderID secures SMTP connections using explicit STARTTLS. When enable_start_tls is true, ThunderID first connects to the SMTP server over plain TCP on the specified port, then upgrades the connection to TLS using the STARTTLS command. The TLS handshake requires TLS 1.2 or later.

ThunderID opens a new SMTP connection for each email and enforces a 30-second TCP connection timeout. Persistent connection pooling is not supported.

warning

Implicit TLS (SMTPS on port 465) is not supported. Implicit TLS establishes the TLS connection immediately without a STARTTLS upgrade. Use port 587 with enable_start_tls: true instead.

Authentication

When enable_authentication is true (the default), ThunderID authenticates with the SMTP server using PLAIN authentication over the TLS-secured connection. Both username and password must be provided when authentication is enabled. ThunderID returns an error at startup if either value is empty.

To disable authentication (for example, when using a local relay that does not require credentials), set the following properties:

email:
  smtp:
    host: "localhost"
    port: 25
    from_address: "noreply@example.com"
    enable_start_tls: false
    enable_authentication: false