Shellius sends email for invitations, password resets, email verification and sign-in codes, access requests awaiting approval, and posture alerts. You choose how under Administration → Email.

Required permissions

Task	Permission
View and manage email providers, send test email	settings.smtp (Email delivery)

How Shellius picks a sender

The choice is made fresh for every message, so changes apply without a restart.

1. The organisation's active provider. You can define several; at most one is active.
2. The SMTP_* environment variables, when no provider is active.
3. Log-only mode, when neither exists. Nothing is sent. The backend log records the subject and the start of the text body so an admin can copy an invite or reset link, and Administration → Users shows such links directly.

No silent fallback

If the active provider fails, Shellius does not fall back to the environment settings. The send fails, the person sees an error (or the link to copy), and the backend log records the provider's name, type and error message.

When no provider is active, the Email section tells you which case applies — either that the server's SMTP_* settings are in use, or Emails are not being sent.

Add a provider

1. Go to Administration → Email and choose Add provider.
2. Pick a type and fill in its settings (see the sections below).
3. Choose Send test email. It sends a real message — to your own address by default — through that provider, whether or not it is active, and shows the provider's own error text if it fails. Tests are limited to 10 per minute per user.
4. Choose Make active. The previously active provider is deactivated in the same step.

Deactivate or Delete on the active provider leaves none active, so the environment fallback (or log-only mode) applies.

Secret fields — API keys, client secrets, passwords, the service-account key — are write-only. They are encrypted at rest with SERVER_ENCRYPTION_KEY (AES-256-GCM) and never returned by the API; the form shows Stored instead. Leave a secret blank when editing to keep it.

The From address is required for SendGrid, Mailgun, Postmark and Resend. Google uses the connected account, Microsoft 365 uses the sender mailbox, and SMTP uses the username if it is an email address.

All providers except SMTP talk to fixed, provider-owned HTTPS endpoints, never follow redirects, and time out after 15 seconds.

SMTP

Any SMTP server or relay: Postfix, Exchange, Amazon SES SMTP, or the SMTP relay of a transactional provider.

Field	Notes
Host	Bare hostname or IP — no smtp://, no port. Internal relays are allowed.
Port	Usually 587 (STARTTLS) or 465 (TLS); 25 for internal relays.
Security	STARTTLS — plain connect, TLS upgrade required. TLS — implicit TLS from the first byte. None — TLS not required; Shellius still upgrades if the server offers STARTTLS.
Username / Password	Optional; sent only when both are set.

Google (Gmail API)

Sends as a Gmail or Google Workspace mailbox. There are two ways to authenticate.

Connect a Google account

1. In Google Cloud Console, enable the Gmail API for a project.

2. Create an OAuth client ID of type Web application. Add the Authorized redirect URI shown in the Add-provider dialog:

   https://shellius.example.com/api/settings/email/google/callback

   If the consent screen is in Testing, add the sending account as a test user.

3. In Shellius, add a Google provider with that client ID and secret. If the server already has SSO_GOOGLE_CLIENT_ID and SSO_GOOGLE_CLIENT_SECRET set for Google SSO, leave both blank to reuse them — and add the redirect URI above to that client.

4. Choose Connect Google account and sign in as the mailbox that should send. Shellius asks only for the gmail.send scope, plus openid email to show which account is connected. The refresh token is stored encrypted.

5. Send a test email, then Make active.

The connect link is valid for 10 minutes, works once, and is bound to the organisation, the provider and the admin who started it.

Workspace service account

1. Create a service account and a JSON key in Google Cloud.
2. In the Workspace Admin console, under Security → API controls → Domain-wide delegation, add the service account's client ID with the scope https://www.googleapis.com/auth/gmail.send.
3. Add a Google provider, choose Workspace service account, paste the JSON key and enter the mailbox to send as.

Microsoft 365

Sends through Microsoft Graph with app-only authentication.

1. In Microsoft Entra ID → App registrations, register an application.
2. Under API permissions, add Microsoft Graph → Application permissions → Mail.Send, then Grant admin consent.
3. Under Certificates & secrets, create a client secret and note its value.
4. In Shellius, add a Microsoft 365 provider with the Directory (tenant) ID, Application (client) ID, client secret and the sender mailbox's UPN.

Restrict the app to one mailbox

Without an Exchange Online application access policy, Mail.Send lets the app send as any mailbox in the tenant. Scope it to the sending mailbox.

SendGrid, Mailgun, Postmark, Resend

Provider	You need	Notes
SendGrid	An API key with Mail Send	From address must be a verified sender or on an authenticated domain. Choose the EU region for EU-resident accounts.
Mailgun	A sending API key and the sending domain	From address must be on that domain. Choose EU for EU-hosted domains.
Postmark	The Server API token	Optional message stream ID (default outbound). From address must be a confirmed signature or on a verified domain.
Resend	An API key with sending access	From address must be on a verified domain.

Environment fallback

Useful for a first boot, before anyone can sign in to configure a provider.

Variable	Default	Notes
SMTP_HOST	—	Setting it enables the fallback.
SMTP_PORT	587
SMTP_USER, SMTP_PASS	—	SMTP_PASS is a secret.
SMTP_FROM	SMTP_USER, if it is an address
SMTP_FROM_NAME	—	Optional display name.
SMTP_SECURITY	derived	none, starttls or tls. Unset: TLS on port 465, otherwise STARTTLS if offered.
SMTP_SECURE	true	Legacy; only read when SMTP_SECURITY is unset.

The API only reveals whether SMTP_HOST is set, never the values.

Templates

Messages use a built-in Shellius-branded layout with a plain-text alternative. Templates are part of the backend and are not editable from the portal.

The header image is loaded from your own Shellius instance, so set the public URL (FRONTEND_URL, or TRAEFIK_HOST) correctly. If it is unset or points at localhost, emails fall back to a text wordmark rather than a broken image — and the links inside them will be wrong too.

Auditing

Every change is audited — email_provider.create, .update, .delete, .activate, .deactivate, .test and .google_connect. Entries record names, types and which fields changed, never secret values.

Troubleshooting

Invites are not arriving. Open Administration → Email. If it says emails are not being sent, no provider is active and SMTP_HOST is unset. If a provider is active, send a test email and read the error.

The test passes but real mail does not arrive. The test goes to your own address. Check the recipient's spam folder and that the From address is authorised for your domain (SPF and DKIM are configured at your provider, not in Shellius).

STARTTLS fails on port 587. Your server may not offer STARTTLS. Switch Security to None, or use port 465 with TLS.

Next steps

NotificationsWhich events notify people, and which also send email.Team and rolesInvite people once delivery works.Environment variablesThe full list, including SMTP_* and SERVER_ENCRYPTION_KEY.