Microsoft Exchange 365 Mailer

Extension key: ok_exchange365_mailer
Package name: oliverkroener/ok-exchange365-mailer
Version: 4.0
Language: en
Author: Oliver Kroener <https://www.oliver-kroener.de> & Contributors
License: This document is published under the Open Publication License.
Rendered: Tue, 29 Jul 2025 20:33:48 +0000

Note

Purpose: Enables TYPO3 to send emails through Microsoft Exchange 365 using Graph API instead of SMTP
Authentication: Uses OAuth 2.0 for secure token-based authentication
API Integration: Leverages Microsoft Graph API for direct email sending
Scalability: Handles high email volumes without additional infrastructure

Installation

Explains how to install this extension in Composer-based and Classic TYPO3 installations.

Configuration Microsoft Entra ID

Learn how to configure Microsoft Entra ID (formerly Microsoft AD) for this extension.

Frequently Asked Questions (FAQ)

These questions have been frequently asked.

How to get help

Learn where to get help and how to report issues you found.

Installation

Install with Composer

Note

This is the recommended way to install this extension.

Install the extension via Composer:

composer req oliverkroener/ok-exchange365-mailer

Install in Classic Mode

Warning

This is not the recommended way to install this extension, and might involve manual steps to add dependencies.

Or download the extension from https://extensions.typo3.org/extension/ok_exchange365_mailer and install it in the Extension Manager.

Configuration of Microsoft Entra ID (formerly Azure AD)

Attention

The Client ID can be found on the overview page in Azure and should not be confused with the Client Secret ID. For the secret configuration, only the Secret value itself is required, not the Secret ID.

Please follow the steps below to configure Microsoft Entra ID (formerly Azure AD) for the TYPO3 extension ok_exchange365_mailer. This configuration is necessary to enable secure email sending through Microsoft Exchange 365 using the Graph API. .. note:: This guide assumes you have administrative access to Microsoft Entra ID and the necessary permissions to register applications.

Register an application in Microsoft Entra ID (formerly Azure AD).

Please go to https://portal.azure.com
Register the application in Microsoft Entra ID.
Note
- Name: Choose a descriptive name for your application.
- Supported account types: Select "Accounts in this organizational directory only (Single tenant)".
Register an application.

Attention

Redirect URI: No redirect URI is required since this application uses client credentials flow for server-to-server authentication without user delegation.
Collect tenant ID and client ID.
- Tenant ID: This is the unique identifier for your Microsoft Entra ID tenant.
- Client ID: This is the unique identifier for your registered application.
Attention

The Client ID can be found on the overview page in Azure and should not be confused with the Secret ID. For the secret configuration, only the Secret value itself is required, not the Secret ID.
Create a client secret. - Navigate to the "Certificates & secrets" section of your application. - Click on "New client secret".
Add client secret.
Attention
- Secret Value: Copy the secret value immediately after creation. You won't be able to see it again.
- Expiry: Ensure you manage the expiration of the secret and renew it before it expires to maintain uninterrupted service.
Copy secret value.
- Secret Value: This is the value you will use in your TYPO3 configuration to authenticate with Microsoft Entra ID.
- Secret ID: This is not required for the configuration, only the Secret Value is needed. This will be later on the clientSecret in the TYPO3 configuration.
Attention

The Secret Value is sensitive information. Store it securely and do not expose it in public repositories or logs.
Assign API permissions.
- Navigate to the "API permissions" section of your application.
- Click on "Add a permission".
Select Microsoft Graph.

Choose "Microsoft Graph" as the API you want to access.
Select application permissions.

Choose Application permissions since this application will run without user interaction.
Add Mail.Send permission.
- This permission allows the application to send emails on behalf of users in your organization.
- Choose Mail.Send (Send mail as any user) and "Add permissions".
Add User.ReadBasic.All permission.
- This permission allows the application to read basic user information, which is often necessary for sending emails on behalf of users.
- Click on "Add permissions" after selecting the permission.
Grant admin consent.
- After adding the permissions, you need to grant admin consent for the permissions to take effect.
- Click on "Grant admin consent for [Your Organization Name]".
Attention

This step is crucial as it allows the application to use the permissions granted without requiring individual user consent.

Configuration

This section covers all aspects of configuring the Microsoft Exchange 365 Mailer extension for TYPO3.

After completing the Azure Configuration, you need to configure the TYPO3 extension with the values obtained from Microsoft Entra ID.

Quick Configuration Overview

The extension requires the following key configuration variables:

Mail Transport: Set to use Exchange365Transport
Tenant ID: Your Microsoft Entra ID tenant identifier
Client ID: Your Azure application identifier
Client Secret: Your Azure application secret
From Email: The sender email address
Save to Sent Items: Whether to save emails to sent folder

For detailed step-by-step instructions, see:

Essential Configuration - For server-side email sending (recommended for production)
Frontend Configuration - For form-based email sending (Powermail, Form Framework)

Configuration Methods

You can configure this extension using:

Essential Configuration (Recommended)

Environment variables (.env file)
TYPO3 LocalConfiguration.php
TYPO3 Admin Panel (if available)

Frontend Configuration (For Forms)

TypoScript configuration
Required for Powermail, Form Framework, and other frontend forms

Choose the method that best fits your deployment workflow and security requirements.

Attention

Security Recommendation: Use backend configuration with environment variables for production environments to avoid exposing sensitive Azure credentials in TypoScript.

Essential Configuration

After completing the Azure Configuration, you need to configure the TYPO3 extension with the values obtained from Microsoft Entra ID.

Attention

Quick Navigation

This page covers the complete configuration setup for the Exchange 365 TYPO3 extension:

Configuration Variables - Required environment variables and settings
Configuration Example - Complete configuration example with screenshot
Alternative Configuration Methods - Different ways to configure the extension
Testing the Configuration - How to verify your setup works
Security Considerations - Important security guidelines
Configuration Validation - Steps to validate your configuration

Configuration Variables

The extension requires several configuration variables to be set in TYPO3. These can be configured through environment variables or directly in the TYPO3 configuration.

The following steps show the configuration with .env variables, but you can also set them in the LocalConfiguration.php file or through the TYPO3 Admin Panel if available. .. note:: The configuration variables are prefixed with TYPO3_CONF_VARS__MAIL__transport_exchange365_ to avoid conflicts with other mail transports.

Set the mail transport to Exchange365Transport.

Configure TYPO3 to use the Exchange 365 transport instead of the default SMTP transport.
```
TYPO3_CONF_VARS__MAIL__transport=OliverKroener\\OkExchange365\\Mail\\Transport\\Exchange365Transport
```
Copied!
Configure the Tenant ID.

Set the Tenant ID obtained from step 4 of the Azure Configuration.
```
TYPO3_CONF_VARS__MAIL__transport_exchange365_tenantId='your-tenant-id-here'
```
Copied!
Attention

Replace your-tenant-id-here with the actual Tenant ID from your Azure application overview page.
Configure the Client ID.

Set the Client ID (Application ID) obtained from step 4 of the Azure Configuration.
```
TYPO3_CONF_VARS__MAIL__transport_exchange365_clientId='your-client-id-here'
```
Copied!
Attention

Replace your-client-id-here with the actual Client ID from your Azure application overview page.
Configure the Client Secret.

Set the Client Secret value obtained from step 7 of the Azure Configuration.
```
TYPO3_CONF_VARS__MAIL__transport_exchange365_clientSecret='your-client-secret-here'
```
Copied!
Attention
- Replace your-client-secret-here with the actual Secret Value (not the Secret ID)
- This is sensitive information - keep it secure and never expose it in public repositories
Configure the sender email address.

Set the email address that will be used as the sender for all emails sent through this transport.
```
TYPO3_CONF_VARS__MAIL__transport_exchange365_fromEmail='service@your-domain.com'
```
Copied!
Attention

The email address will fall back to TYPO3's $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress'] if not specified here.
Note
- Replace service@your-domain.com with a valid email address from your organization (it must exist in your Exchange 365 environment as SharedMailbox or User Mailbox)
- This email address must exist in your Exchange 365 environment
- The application needs permission to send emails on behalf of this address
Configure save to sent items (optional).

Determine whether sent emails should be saved to the sender's "Sent Items" folder.
```
TYPO3_CONF_VARS__MAIL__transport_exchange365_saveToSentItems=1
```
Copied!
Note
- Set to 1 to save emails to Sent Items folder
- Set to 0 to skip saving emails to Sent Items folder
- Default value is 0 (enabled) if not specified

Configuration Example

Here's a complete example of all required configuration variables:

TYPO3 configuration showing Exchange365 transport variables setup

Environment Variables (.env file)

You can configure these settings using a .env file in your TYPO3 root directory:

# Exchange 365 Mail Transport Configuration
TYPO3_CONF_VARS__MAIL__transport=OliverKroener\\OkExchange365\\Mail\\Transport\\Exchange365Transport
TYPO3_CONF_VARS__MAIL__transport_exchange365_tenantId='your-tenant-id-here'
TYPO3_CONF_VARS__MAIL__transport_exchange365_clientId='your-client-id-here'
TYPO3_CONF_VARS__MAIL__transport_exchange365_clientSecret='your-client-secret-here'
TYPO3_CONF_VARS__MAIL__transport_exchange365_fromEmail='service@your-domain.com'
TYPO3_CONF_VARS__MAIL__transport_exchange365_saveToSentItems=1

Alternative Configuration Methods

In Typo3 config files

Alternatively, you can add these settings directly to your TYPO3 configuration files, such as config/system/settings.php or config/system/additional.php or typo3conf/LocalConfiguration.php.

<?php
return [
    // ...existing configuration...
    
    'MAIL' => [
        'transport' => 'OliverKroener\\OkExchange365\\Mail\\Transport\\Exchange365Transport',
        'transport_exchange365_tenantId' => 'your-tenant-id-here',
        'transport_exchange365_clientId' => 'your-client-id-here',
        'transport_exchange365_clientSecret' => 'your-client-secret-here',
        'transport_exchange365_fromEmail' => 'service@your-domain.com',
        'transport_exchange365_saveToSentItems' => 1,
    ],
    
    // ...existing configuration...
];

Or using the $GLOBALS syntax:

<?php
// In typo3conf/LocalConfiguration.php or ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = 'OliverKroener\\OkExchange365\\Mail\\Transport\\Exchange365Transport';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_tenantId'] = 'your-tenant-id-here';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_clientId'] = 'your-client-id-here';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_clientSecret'] = 'your-client-secret-here';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_fromEmail'] = 'service@your-domain.com';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_exchange365_saveToSentItems'] = 1;

Attention

Replace placeholder values with your actual Azure configuration values
When using PHP syntax, use single backslashes (``) in class names instead of double backslashes
Keep the client secret secure and never commit it to version control

Testing the Configuration

After configuring all variables, you can test the email functionality by:

Sending a test email through TYPO3's mail functionality
Checking the TYPO3 logs for any error messages
Verifying that emails are received at the intended recipients
Checking the sender's "Sent Items" folder if saveToSentItems is enabled

Tip

Enable TYPO3's developer log to see detailed information about the email sending process and any potential issues with the Exchange 365 integration.

Security Considerations

Warning

Azure Credential Security

Store the clientSecret securely using environment variables or encrypted configuration
Never commit secrets to version control systems
Rotate client secrets regularly before expiration
Use different Azure applications for different environments (dev/staging/prod)
Monitor Azure sign-in logs for unauthorized access

Configuration Validation

To verify your configuration is correct:

Check in backend:
- Navigate to the TYPO3 Admin Panel
- Check the mail configuration under Settings > Environment > Test Mail Setup
- Ensure the transport is set to Exchange365Transport and all required fields are filled

Check TYPO3 configuration:

// In TYPO3 backend or debug context
\TYPO3\CMS\Core\Utility\DebugUtility::debug($GLOBALS['TYPO3_CONF_VARS']['MAIL']);

Test email sending:

// Test email functionality
$mail = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class);
$mail->to('test@example.com')
    ->subject('Test Email')
    ->text('This is a test email from TYPO3.')
    ->send();

Check logs: Monitor TYPO3 logs for authentication or sending errors

Frontend Configuration

The Exchange 365 Mailer extension supports frontend email sending through popular TYPO3 extensions like Powermail, Form Framework, and other form extensions. This requires additional TypoScript configuration to work properly.

Attention

Frontend configuration is required for any page that uses forms or email functionality. Without proper TypoScript setup, frontend forms will not be able to send emails through Exchange 365.

Frontend Configuration Overview

Frontend email sending requires the same 5 core parameters as the backend configuration, but they must be configured via TypoScript instead of environment variables or LocalConfiguration.php.

TYPO3 TypoScript configuration showing Exchange365 frontend parameters

Required TypoScript Parameters

The following 5 parameters must be configured in your TypoScript setup for frontend email functionality:

Transport Class Configuration

Set the mail transport to use the Exchange365Transport class for frontend operations.
```
config.mail.transport = OliverKroener\OkExchange365\Mail\Transport\Exchange365Transport
```
Copied!
Note

This tells TYPO3 to use the Exchange 365 transport instead of the default SMTP transport for frontend emails.
Tenant ID

Configure your Microsoft Entra ID tenant identifier.
```
plugin.tx_okexchange365mailer.settings.exchange365.tenantId = your-tenant-id-here
```
Copied!
Attention

Replace your-tenant-id-here with the actual Tenant ID from your Azure Configuration (step 4).
Client ID

Set your Azure application's client identifier.
```
plugin.tx_okexchange365mailer.settings.exchange365.clientId = your-client-id-here
```
Copied!
Attention

Replace your-client-id-here with the actual Client ID from your Azure Configuration (step 4).
Client Secret

Configure the Azure application's client secret.
```
plugin.tx_okexchange365mailer.settings.exchange365.clientSecret = your-client-secret-here
```
Copied!
Warning
- Replace your-client-secret-here with the actual Secret Value from your Azure Configuration (step 7)
- Security Risk: TypoScript is visible in the frontend source. Consider using Essential Configuration with environment variables for production
- Never expose this value in public repositories or frontend debugging
From Email Address

Set the sender email address for frontend-generated emails.
```
plugin.tx_okexchange365mailer.settings.exchange365.fromEmail = service@your-domain.com
```
Copied!
Note
- Replace service@your-domain.com with a valid email address from your Exchange 365 environment
- This email must exist as a SharedMailbox or User Mailbox in your organization
- If not specified, falls back to config.mail.defaultMailFromAddress
Save to Sent Items (Optional)

Determine whether frontend emails should be saved to the sender's "Sent Items" folder.
```
plugin.tx_okexchange365mailer.settings.exchange365.saveToSentItems = 1
```
Copied!
Note
- Set to 1 to save emails to Sent Items folder
- Set to 0 to skip saving emails to Sent Items folder
- Default value is 0 if not specified

Complete TypoScript Configuration Example

Here's a complete TypoScript setup example for frontend email functionality:

# Exchange 365 Frontend Mail Configuration
config {
    mail {
        # Set transport to Exchange 365
        transport = OliverKroener\OkExchange365\Mail\Transport\Exchange365Transport
        
        # Optional: Default mail settings
        defaultMailFromAddress = service@your-domain.com
        defaultMailFromName = Your Organization Name
    }
}

# Exchange 365 specific configuration
plugin.tx_okexchange365mailer {
    settings {
        exchange365 {
            # Azure/Microsoft Entra ID Configuration
            tenantId = your-tenant-id-here
            clientId = your-client-id-here
            clientSecret = your-client-secret-here
            
            # Email Configuration
            fromEmail = service@your-domain.com
            saveToSentItems = 1
        }
    }
}

Integration with Form Extensions

Powermail Integration

When using Powermail, the extension will automatically use the configured Exchange 365 transport for sending emails:

plugin.tx_powermail {
    settings {
        setup {
            # Powermail will use the global mail configuration
            # No additional configuration needed
        }
    }
}

TYPO3 Form Framework Integration

For the TYPO3 Form Framework, ensure your form configuration references the global mail settings:

# In your form configuration (YAML)
finishers:
  -
    identifier: EmailToReceiver
    options:
      # Uses global mail configuration automatically
      recipientAddress: 'recipient@example.com'
      recipientName: 'Recipient Name'

Configuration File Locations

Place your TypoScript configuration in one of these locations:

Template Records

Add the configuration to your main TypoScript template record in the TYPO3 backend.

Static Files

Create or modify files in your site package:

Configuration/TypoScript/setup.typoscript
Configuration/TypoScript/constants.typoscript (for constants)

Page TSconfig (Not recommended for mail settings)

Only use for page-specific overrides, not for global mail configuration.

Security Considerations for Frontend

Danger

TypoScript Security Warning

TypoScript configuration is potentially visible in frontend source code and through various debugging tools:

Client Secret Exposure: Never use sensitive secrets in TypoScript on production sites
Recommended Approach: Use Essential Configuration with environment variables
Alternative: Use TYPO3's encrypted configuration features for sensitive data
Monitoring: Regularly audit your TypoScript for exposed credentials

Best Practices

Environment-Specific Configuration

Use different Azure applications for different environments:

[applicationContext == "Development"]
    plugin.tx_okexchange365mailer.settings.exchange365.clientId = dev-client-id
    plugin.tx_okexchange365mailer.settings.exchange365.tenantId = dev-tenant-id
[END]

[applicationContext == "Production"]
    plugin.tx_okexchange365mailer.settings.exchange365.clientId = prod-client-id
    plugin.tx_okexchange365mailer.settings.exchange365.tenantId = prod-tenant-id
[END]

Conditional Loading

Only load Exchange 365 configuration when needed:

[siteIdentifier == "main-site"]
    <INCLUDE_TYPOSCRIPT: source="FILE:EXT:site_package/Configuration/TypoScript/exchange365.typoscript">
[END]

Fallback Configuration

Always provide fallback settings:

config.mail {
    defaultMailFromAddress = fallback@your-domain.com
    defaultMailFromName = Fallback Sender
}

Testing Frontend Configuration

To test your frontend configuration:

Create a test form using Powermail or Form Framework
Submit the form and verify email delivery
Check TYPO3 logs for any authentication or sending errors
Verify in Exchange 365 that emails appear in the sender's mailbox (if saveToSentItems is enabled)

Tip

Use TYPO3's mail spooling functionality during development to prevent sending actual emails while testing configuration.

Troubleshooting Frontend Issues

Common issues and solutions:

Emails not sending

Verify all 5 parameters are correctly configured in TypoScript
Check that the Azure application has proper permissions
Ensure the sender email exists in Exchange 365

Authentication errors

Verify Tenant ID and Client ID are correct
Check that the Client Secret is valid and not expired
Confirm Azure admin consent has been granted

Permission errors

Ensure the Azure application has Mail.Send permission
Verify the sender email address exists in your Exchange 365 environment
Check that the application can send on behalf of the specified user

Where to get help

Note

You can get help in the TYPO3 Slack https://typo3.org/community/meet/chat-slack, Ask a question in the official TYPO3 forum, https://talk.typo3.org/c/typo3-questions/19 or contact the extension author.

Please visit the following website for contacting the author directly: https://www.oliver-kroener.de

Report Issues

Attention

You can report issues at https://github.com/oliverkroener/ok_exchange365_mailer/issues.

Sitemap

Frequently Asked Questions (FAQ)

See chapter Installation.

See chapter Configuration.

See chapter Where to get help.

Microsoft Exchange 365 Mailer

Installation

Configuration Microsoft Entra ID

Configuration

Frequently Asked Questions (FAQ)

How to get help

Installation

Install with Composer

Install in Classic Mode

Configuration of Microsoft Entra ID (formerly Azure AD)

Configuration

Quick Configuration Overview

Configuration Methods

Essential Configuration

Quick Navigation

Configuration Variables

Configuration Example

Environment Variables (.env file)

Alternative Configuration Methods

In Typo3 config files

Testing the Configuration

Security Considerations

Configuration Validation

Frontend Configuration

Frontend Configuration Overview

Required TypoScript Parameters

Complete TypoScript Configuration Example

Integration with Form Extensions

Powermail Integration

TYPO3 Form Framework Integration

Configuration File Locations

Security Considerations for Frontend

Best Practices

Testing Frontend Configuration

Troubleshooting Frontend Issues

Where to get help

Report Issues

Sitemap

Frequently Asked Questions (FAQ)

How can I install this extension?

How to can I include the TypoScript?

Where to get help?

Index