What does it do? 

The Microsoft Exchange 365 Mailer extension replaces TYPO3's default SMTP mail transport with a custom transport that sends emails via the Microsoft Graph API.

Instead of configuring an SMTP server, you register an application in Microsoft Entra ID (formerly Azure AD) and authenticate using the OAuth 2.0 client credentials flow — no user interaction or stored passwords required.

Features 

• Send emails through Microsoft Graph API — no SMTP required
• OAuth 2.0 client credentials flow for server-to-server authentication
• Supports both backend (environment variables / TYPO3 settings) and frontend (TypoScript) configuration
• Compatible with Powermail, TYPO3 Form Framework, and other form extensions
• Optional saving of sent emails to the sender's "Sent Items" folder
• Automatic credential blinding in TYPO3's configuration module
• Works with shared mailboxes and Application Access Policies

Requirements 

• TYPO3: 12.4 LTS, 13.4 LTS, or 14.x
• PHP: 8.3+

• Dependencies:

  • microsoft/microsoft-graph ^2 — Microsoft Graph SDK
  • oliverkroener/ok-typo3-helper — provides MSGraphMailApiService for message conversion

Install with Composer 

Install the extension via Composer:

composer req oliverkroener/ok-exchange365-mailer

See also Installing extensions, TYPO3 Getting started.

Install in Classic Mode 

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

Import and connect 

Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName your-admin@yourdomain.com

This opens a browser window for authentication. Use an account with Exchange Admin rights.

Create the Application Access Policy 

The New-ApplicationAccessPolicy cmdlet restricts your application to only access specific mailboxes instead of all mailboxes in the tenant.

Parameters:

• -AppId: The Application (client) ID from your Microsoft Entra ID app registration
• -PolicyScopeGroupId: The email address of the mailbox or mail-enabled security group the app is allowed to access
• -AccessRight RestrictAccess: Limits the app to only the specified mailbox(es)
• -Description: A human-readable description for the policy

New-ApplicationAccessPolicy -AppId "<your-app-id>" -PolicyScopeGroupId "shared@yourdomain.com" -AccessRight RestrictAccess -Description "Restrict to shared mailbox"

To verify the policy was created:

Get-ApplicationAccessPolicy | Format-List

To test if the policy works correctly:

Test-ApplicationAccessPolicy -Identity "shared@yourdomain.com" -AppId "<your-app-id>"

Troubleshooting 

# Check if connected
Get-ConnectionInformation

# Verify cmdlet exists
Get-Command New-ApplicationAccessPolicy

# Check PowerShell version (needs 5.1+)
$PSVersionTable.PSVersion

# List all existing policies
Get-ApplicationAccessPolicy | Format-List

# Remove a policy if needed
Remove-ApplicationAccessPolicy -Identity "<policy-id>"

Create a mail-enabled security group 

1. Create the security group via PowerShell:

New-DistributionGroup -Name "Graph API Shared Mailboxes" -Type Security -PrimarySmtpAddress "graph-mailboxes@yourdomain.com"

2. Add your shared mailbox to the group:

Add-DistributionGroupMember -Identity "Graph API Shared Mailboxes" -Member "shared@yourdomain.com"

3. Verify the group was created correctly:

Get-DistributionGroup -Identity "Graph API Shared Mailboxes" | Format-List
Get-DistributionGroupMember -Identity "Graph API Shared Mailboxes"

4. Now create the Application Access Policy using the group:

New-ApplicationAccessPolicy -AppId "<your-app-id>" -PolicyScopeGroupId "graph-mailboxes@yourdomain.com" -AccessRight RestrictAccess -Description "Allow app to send from shared mailboxes"

5. Test the policy:

Test-ApplicationAccessPolicy -Identity "shared@yourdomain.com" -AppId "<your-app-id>"

You should see AccessCheckResult: Granted.

Adding multiple mailboxes 

Simply add additional mailboxes to the same security group you already created:

Add-DistributionGroupMember -Identity "Graph API Shared Mailboxes" -Member "another-shared@yourdomain.com"

The Application Access Policy applies to all members of the group – no need to create a new policy.

Verify it worked:

# List all members of the group
Get-DistributionGroupMember -Identity "Graph API Shared Mailboxes"

# Test the new mailbox
Test-ApplicationAccessPolicy -Identity "another-shared@yourdomain.com" -AppId "<your-app-id>"

Alternative via Microsoft 365 Admin Center 

1. Go to Admin Center → Teams & Groups → Active teams & groups
2. Click Add a group and select Mail-enabled security
3. Name the group (e.g., "Graph API Shared Mailboxes")
4. Add the shared mailbox as a member
5. Then run the New-ApplicationAccessPolicy command with that group's email address

Configure via Microsoft 365 Admin Center 

1. Open the Microsoft 365 Admin Center.

   Go to https://admin.microsoft.com and sign in with an admin account.

2. Navigate to the mailbox.

   • For shared mailboxes: Go to Teams & Groups → Shared mailboxes (or Active teams & groups if the mailbox is a group).
   • For regular user mailboxes: Go to Users → Active users.

   Select the mailbox you configured as the fromEmail in your TYPO3 setup.

3. Edit the display name.

   Click on the mailbox name to open its properties. Under General, update the Display name to the name you want recipients to see as the sender (e.g., "Oliver Kroener" or "Contact - Oliver Kroener").

   Click Save changes.

4. Verify the sender display name.

   Send a test email through TYPO3 and verify that the recipient sees the correct sender name in their inbox.

Configure via Exchange Admin Center 

Alternatively, you can use the Exchange Admin Center for more granular mailbox settings:

1. Open the Exchange Admin Center.

   Go to https://admin.exchange.microsoft.com and sign in with an admin account.

2. Navigate to the mailbox.

   Go to Recipients → Mailboxes (for user mailboxes) or Recipients → Groups → Shared mailboxes (for shared mailboxes).

   Select the mailbox used as fromEmail.

3. Edit mailbox properties.

   Click on the mailbox to open its settings. Under General, you can configure:

   • Display name: The name shown to email recipients (e.g., "Oliver Kroener Website")
   • Email addresses: Add or modify email aliases if needed

   Click Save to apply the changes.

Configure via PowerShell 

You can also update the display name via PowerShell:

# For a shared mailbox
Set-Mailbox -Identity "shared@yourdomain.com" -DisplayName "Your Desired Sender Name"

# Verify the change
Get-Mailbox -Identity "shared@yourdomain.com" | Format-List DisplayName, PrimarySmtpAddress

Quick Configuration Overview 

The extension requires the following key configuration variables:

1. Mail Transport: Set to use Exchange365Transport
2. Tenant ID: Your Microsoft Entra ID tenant identifier
3. Client ID: Your Azure application identifier
4. Client Secret: Your Azure application secret
5. From Email: The sender email address
6. 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.

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.

1. 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!

2. 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.

3. 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.

4. 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

5. 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

6. 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:

# 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 

<?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...
];

<?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;

Testing the Configuration 

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

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

Security Considerations 

Configuration Validation 

To verify your configuration is correct:

1. 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

   

2. Check TYPO3 configuration:

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

   Copied!

3. 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();

   Copied!

4. Check logs: Monitor TYPO3 logs for authentication or sending errors

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.

Required TypoScript Parameters 

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

1. 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.

2. 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).

3. 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).

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

5. 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

6. 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 

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

# 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 

Best Practices 

1. 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]

   Copied!

2. Conditional Loading

   Only load Exchange 365 configuration when needed:

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

   Copied!

3. Fallback Configuration

   Always provide fallback settings:

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

   Copied!

Testing Frontend Configuration 

To test your frontend configuration:

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

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

Report Issues 

Author — Oliver Kroener 

Support 

If you encounter issues or have questions about this extension:

• Bug reports & feature requests: Use the GitHub issue tracker
• Email: ok@oliver-kroener.de

Contributing 

Contributions are welcome. Please open a pull request or issue on GitHub.

License 

This extension is licensed under the GPL-2.0-or-later.