Email

Gmail API or Azure Communication Services

Email is the transport that powers verification mails, password resets, invites, device-approval alerts and notifications. Configure it once and every feature that needs to send mail just works.

Two providers are supported: the Gmail API (via a Google service-account JSON key) and Azure Communication Services (via a connection string). You pick one; Nucleus abstracts the rest behind a single EmailService.

Provider selection#

Choose which transport sends your mail. Only the matching sub-block needs to be filled in.

config.nucleus.json — email (Gmail)

1{2  "email": {3    "provider": "gmail",4    "gmail": {5      "enabled": true,6      "json_file_path": "GMAIL_SERVICE_ACCOUNT_JSON",7      "from_email": "[email protected]",8      "from_name": "Acme"9    }10  }11}

provider'gmail' | 'azure'Optional

The active email backend. gmail uses the Gmail API with a service account; azure uses Azure Communication Services. Each feature that sends mail (e.g. register.emailVerification.provider) can also name its provider, but this sets the default.

gmail— Google Workspace Gmail API via a service-account key file.
azure— Azure Communication Services via a connection string.

Gmail#

Send through the Gmail API using a Google service account. The service-account JSON key is referenced by file path and must have domain-wide delegation to send as from_email.

gmailobjectOptional

Gmail provider configuration.

enabledbooleanOptional

Activate the Gmail transport.

json_file_pathstringOptional

Path to the service-account JSON key file. Treated as sensitive — keep it out of source control and mount it as a secret.

from_emailstringOptional

The sender address mail is sent as (requires delegated authority).

from_namestringOptional

Friendly display name shown to recipients.

Azure Communication Services#

Send through Azure ACS. The connection string can be a literal value or an env-var name; Nucleus resolves it at startup. Requires the optional @azure/communication-email package.

azureobjectOptional

Azure ACS provider configuration.

enabledbooleanOptional

Activate the Azure transport.

connection_stringstringOptional

ACS connection string (literal or env-var name). Sensitive — provide via secret/env.

sender_addressstringOptional

Verified ACS sender address.

from_namestringOptional

Friendly display name shown to recipients.

Under the hood — the EmailService#

Whichever provider you pick is hidden behind one EmailService interface, so every feature that sends mail calls the same method and stays provider-agnostic.

EmailService interfacesendEmail · isAvailableOptional

A provider exposes sendEmail({ to, subject, html, attachments? }) and isAvailable(). Callers (auth flows, the notification email channel) check isAvailable() and no-op cleanly when email isn't configured, rather than throwing — so disabling email never breaks a request.

two implementationsGmail · Azure ACSOptional

Gmail authenticates with a service account and sends via the Gmail API; AzureEmailService uses an Azure Communication Services connection string and verified sender. The provider field selects which one is constructed at boot.

one transport, many senderssharedOptional

Because verification, password reset, invites, new-device alerts and notifications all resolve the same EmailService instance, configuring this one block lights up email across every feature at once.

Related sections

Notification Authentication