:navigation-title: Frontend

..  _frontend:

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

..  figure:: /_Images/image-frontend.png
    :alt: TYPO3 TypoScript configuration showing Exchange365 frontend parameters
    :class: with-shadow
    :scale: 100

Required TypoScript Parameters
==============================

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

..  rst-class:: bignums-xxl

1.  **Transport Class Configuration**

    Set the mail transport to use the Exchange365Transport class for frontend operations.

    ..  code-block:: typoscript

        config.mail.transport = OliverKroener\OkExchange365\Mail\Transport\Exchange365Transport

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

    ..  code-block:: typoscript

        plugin.tx_okexchange365mailer.settings.exchange365.tenantId = your-tenant-id-here

    ..  attention::
        Replace `your-tenant-id-here` with the actual Tenant ID from your :ref:`Azure Configuration <azure>` (step 4).

3.  **Client ID**

    Set your Azure application's client identifier.

    ..  code-block:: typoscript

        plugin.tx_okexchange365mailer.settings.exchange365.clientId = your-client-id-here

    ..  attention::
        Replace `your-client-id-here` with the actual Client ID from your :ref:`Azure Configuration <azure>` (step 4).

4.  **Client Secret**

    Configure the Azure application's client secret.

    ..  code-block:: typoscript

        plugin.tx_okexchange365mailer.settings.exchange365.clientSecret = your-client-secret-here

    ..  warning::
        - Replace `your-client-secret-here` with the actual Secret **Value** from your :ref:`Azure Configuration <azure>` (step 7)
        - **Security Risk**: TypoScript is visible in the frontend source. Consider using :ref:`essential` 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.

    ..  code-block:: typoscript

        plugin.tx_okexchange365mailer.settings.exchange365.fromEmail = service@your-domain.com

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

    ..  code-block:: typoscript

        plugin.tx_okexchange365mailer.settings.exchange365.saveToSentItems = 1

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

..  code-block:: typoscript

    # 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:

..  code-block:: typoscript

    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:

..  code-block:: yaml

    # 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 :ref:`essential` with environment variables
    - **Alternative**: Use TYPO3's encrypted configuration features for sensitive data
    - **Monitoring**: Regularly audit your TypoScript for exposed credentials

Best Practices
==============

1. **Environment-Specific Configuration**
   
   Use different Azure applications for different environments:
   
   ..  code-block:: typoscript
   
       [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]

2. **Conditional Loading**
   
   Only load Exchange 365 configuration when needed:
   
   ..  code-block:: typoscript
   
       [siteIdentifier == "main-site"]
           <INCLUDE_TYPOSCRIPT: source="FILE:EXT:site_package/Configuration/TypoScript/exchange365.typoscript">
       [END]

3. **Fallback Configuration**
   
   Always provide fallback settings:
   
   ..  code-block:: typoscript
   
       config.mail {
           defaultMailFromAddress = fallback@your-domain.com
           defaultMailFromName = Fallback Sender
       }

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)

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

..  seealso::
    For backend configuration details, see :ref:`Essential Configuration <essential>`.
    For Azure setup instructions, see :ref:`Azure Configuration <azure>`.