Email (SMTP)

The Email (SMTP) category configures outbound email for your Hawkra instance. Email is used for user registration verification codes, password reset links, and system notifications. Without SMTP configured, all email-dependent features are disabled.

Settings Reference

SMTP Host

Key	smtp_host
Type	String
Default	Empty
Encrypted	No

The hostname of your SMTP mail server. This is the server that Hawkra connects to for sending emails.

Examples: smtp.gmail.com, smtp.sendgrid.net, smtp.mailgun.org, mail.yourdomain.com

SMTP Port

Key	smtp_port
Type	Integer
Default	587
Encrypted	No

The port number for the SMTP connection. The correct port depends on the encryption method:

Port	Encryption	Protocol
587	STARTTLS	Connects in plaintext, then upgrades to TLS. Most common and recommended.
465	SSL/TLS	Connects with TLS from the start (implicit TLS).
25	None	Unencrypted SMTP. Not recommended for production use.

SMTP Encryption

Key	smtp_encryption
Type	Dropdown (starttls or ssl)
Default	starttls
Encrypted	No

The encryption method for the SMTP connection:

• STARTTLS — The connection starts unencrypted and upgrades to TLS via the STARTTLS command. Use with port 587.
• SSL — The connection uses TLS from the start (implicit TLS). Use with port 465.

SMTP Username

Key	smtp_username
Type	String
Default	Empty
Encrypted	Yes

The username for SMTP authentication. This is typically your email address or an API username, depending on your email provider.

SMTP Password

Key	smtp_password
Type	String
Default	Empty
Encrypted	Yes

The password or API key for SMTP authentication. This value is stored encrypted in the database. When viewing the settings page, it appears masked as •••••••• — click Change to enter a new value.

SMTP From Address

Key	smtp_from_address
Type	String
Default	Empty
Encrypted	No

The sender email address that appears in the "From" field of outbound emails. This should be an address associated with your SMTP account or domain to avoid delivery issues.

Example: noreply@yourdomain.com, hawkra@yourdomain.com

Provider-Specific Setup

Gmail

Gmail requires an App Password for SMTP access when two-factor authentication is enabled on your Google account (which it should be).

1. Go to your Google Account settings at myaccount.google.com.
2. Navigate to Security > 2-Step Verification (enable it if not already active).
3. Scroll to App passwords at the bottom of the 2-Step Verification page.
4. Select Mail as the app and your device type, then click Generate.
5. Copy the 16-character app password.

Setting	Value
SMTP Host	smtp.gmail.com
SMTP Port	587
SMTP Encryption	starttls
SMTP Username	Your full Gmail address (e.g., you@gmail.com)
SMTP Password	The 16-character app password from step 5
SMTP From Address	Your Gmail address

caution

Do not use your regular Gmail password. Google blocks standard password authentication for SMTP. You must generate and use an App Password.

SendGrid

SendGrid uses API keys for SMTP authentication.

1. Log in to your SendGrid account at app.sendgrid.com.
2. Navigate to Settings > API Keys.
3. Click Create API Key, give it a name, and select Restricted Access with at least Mail Send permissions.
4. Copy the generated API key (it is only shown once).

Setting	Value
SMTP Host	smtp.sendgrid.net
SMTP Port	587
SMTP Encryption	starttls
SMTP Username	apikey (literal string, not your email)
SMTP Password	Your SendGrid API key
SMTP From Address	A verified sender address in your SendGrid account

Mailgun

1. Log in to your Mailgun account at app.mailgun.com.
2. Navigate to Sending > Domains and select your domain.
3. Click SMTP credentials to view your SMTP username and password.

Setting	Value
SMTP Host	smtp.mailgun.org
SMTP Port	587
SMTP Encryption	starttls
SMTP Username	Your Mailgun SMTP username (e.g., postmaster@mg.yourdomain.com)
SMTP Password	Your Mailgun SMTP password
SMTP From Address	An address at your verified Mailgun domain

Configuration via Environment Variables

SMTP can also be configured entirely through environment variables. When all six SMTP environment variables are set, the backend initializes email support at startup without needing dashboard configuration.

Setting	Environment Variable
SMTP Host	SMTP_HOST
SMTP Port	SMTP_PORT
SMTP Encryption	SMTP_ENCRYPTION
SMTP Username	SMTP_USERNAME
SMTP Password	SMTP_PASSWORD
SMTP From Address	SMTP_FROM_ADDRESS

Testing Your Configuration

After configuring SMTP, enable Email Verification in the Access Control settings and register a test user account. If the verification email arrives, your SMTP is working correctly. If not, check the Docker logs for error messages:

cd /opt/hawkra && docker compose logs backend | grep -i smtp

note

Environment variables take priority over dashboard values. If you set SMTP_HOST as an environment variable, the dashboard value for SMTP Host is ignored at runtime. This is useful for keeping secrets like the SMTP password in your .env file rather than the database.