Site Set Configuration

New in version 4.3.0

The extension ships a site set for TYPO3 v13 and v14. On those versions it replaces the static TypoScript template as the recommended way to configure the frontend. TYPO3 v12 is unaffected and keeps using the static template.

Site sets bundle the extension's TypoScript together with typed, labelled settings. Integrators activate the set per site and edit the values in the TYPO3 backend instead of hand-writing TypoScript constants.

The set provided by this extension is:

oliverkroener/ok-exchange365-mailer

Activating the set

Add the set to the dependencies of the site configuration in config/sites/<identifier>/config.yaml:

config/sites/main/config.yaml

base: 'https://example.org/'
rootPageId: 1
dependencies:
  - oliverkroener/ok-exchange365-mailer

Alternatively, select [kroener.DIGITAL] Exchange 365 Mailer in the backend under Site Management > Sites, in the Sets tab of the site record.

Attention

Use the site set or the static template [kroener.DIGITAL] Exchange 365 Mailer on a sys_template record — never both. Site settings are added to the TypoScript constants before template records, so a static template that is still included would override the values of the set with its own empty defaults.

Editing the settings

Once the set is active, the values are editable under Site Management > Sites, in the Settings of the site record. They are grouped into Credentials and Email Settings:

Tenant ID

type: string
Default: (empty)

OAuth2 tenant ID of the Microsoft Entra ID directory.

Client ID

type: string
Default: (empty)

OAuth2 client ID (application ID) of the registered Entra ID app.

Client Secret

type: string
Default: (empty)

OAuth2 client secret of the registered Entra ID app. See the security warning below before entering a value here.

From Email

type: string
Default: (empty)

Email address the messages are sent from.

Graph Sender User ID

type: string
Default: (empty)

Optional Microsoft Graph mailbox used for the /users/{id}/sendMail call, for Send As / Send On Behalf scenarios. The visible From header is unaffected.

Save sent emails

type: boolean
Default: true

Store a copy of every sent message in the mailbox "Sent Items" folder.

The full setting keys are identical to the TypoScript constants documented in Frontend Configuration, for example plugin.tx_okexchange365mailer.settings.exchange365.tenantId. Values entered in the backend are written to config/sites/<identifier>/settings.yaml:

config/sites/main/settings.yaml

plugin.tx_okexchange365mailer.settings.exchange365.tenantId: 00000000-0000-0000-0000-000000000000
plugin.tx_okexchange365mailer.settings.exchange365.fromEmail: service@example.org
plugin.tx_okexchange365mailer.settings.exchange365.saveToSentItems: true

Every value left empty falls back to the corresponding global mail setting ($GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_*']), evaluated per key rather than all-or-nothing.

Danger

Do not put the client secret into site settings on production.

config/sites/<identifier>/settings.yaml is a plaintext file that is usually committed to version control. Configure the credentials through environment variables as described in Essential Configuration and leave tenantId, clientId and clientSecret empty in the site set — the per-key fallback means the remaining settings (fromEmail, graphSenderUserId, saveToSentItems) still work from the backend.

If a site needs credentials of its own, read them from the environment in the site's TypoScript with := getEnv(...) — see Recommended: read the credentials from the environment.

Setting the transport

The site set only supplies the credentials. The transport itself is always selected in $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] as described in Essential Configuration — there is no TypoScript or site setting for it:

TYPO3_CONF_VARS__MAIL__transport="OliverKroener\\OkExchange365\\Mail\\Transport\\Exchange365Transport"

Scope

Site settings reach the mail transport as TypoScript constants, which exist in the frontend only. Mail sent from the backend, the command line or the scheduler has no site context and always uses the global $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_*'] settings. Configure those as well if you send mail outside of frontend requests.