##############
SendmailConfig
##############


****************
PUBLIC INTERFACE
****************


new()
=====


Don't use the constructor directly, use the ObjectManager instead:


.. code-block:: perl

     my $SendmailConfigObject = $Kernel::OM->Get('Kernel::System::SendmailConfig');



Add()
=====


Adds a new sendmail config.


.. code-block:: perl

     my $SendmailConfigID = $SendmailConfigObject->Add(
         SendmailModule      => 'SMTPTLS',
         CMD                 => '/usr/bin/sendmail...',
         Host                => 'smtp.example.org',
         Port                => 587,
         Timeout             => 30,
         SkipSSLVerification => 0,
         IsFallbackConfig    => 0,
         AuthenticationType  => 'oauth2_token',
         AuthUser            => 'mail',
         AuthPassword        => undef,
         OAuth2TokenConfigID => 2,
         EmailAddresses      => [ # Only stored/needed if IsFallbackConfig is false
             'znuny@example.org',
             'znuny2@example.org',
         ],
         Comments => 'Comment', # optional
         ValidID  => 1,
         UserID   => 3,
     );


Returns:


.. code-block:: perl

     my $SendmailConfigID = 4;



Update()
========


Updates a sendmail config.


.. code-block:: perl

     my $UpdateSuccessful = $SendmailConfigObject->Update(
         ID                  => 5,
         SendmailModule      => 'SMTPTLS',
         CMD                 => '/usr/bin/sendmail...',
         Host                => 'smtp.example.org',
         Port                => 587,
         Timeout             => 30,
         SkipSSLVerification => 0,
         IsFallbackConfig    => 0,
         AuthenticationType  => 'oauth2_token',
         AuthUser            => 'mail',
         AuthPassword        => undef,
         OAuth2TokenConfigID => 2,
         EmailAddresses      => [ # Only stored/needed if IsFallbackConfig is false
             'znuny@example.org',
             'znuny2@example.org',
         ],
         Comments => 'Comment', # optional
         ValidID  => 1,
         UserID   => 3,
     );


Returns:


.. code-block:: perl

     my $UpdateSuccessful = 1;



Delete()
========


Deletes a sendmail config.


.. code-block:: perl

     my $SendmailConfigDeleted = $SendmailConfigObject->Delete(
         ID => 123,
     );


Returns:


.. code-block:: perl

     my $SendmailConfigDeleted = 1;



Get()
=====


Returns the sendmail config for the given ID.


.. code-block:: perl

     my $SendmailConfig = $SendmailConfigObject->Get(
         ID => 4,
     );


Returns:


.. code-block:: perl

     my $SendmailConfig = {
         ID                    => 123,
         SendmailModule        => 'SMTPTLS',
         CMD                   => '/usr/bin/sendmail...',
         Host                  => 'smtp.example.org',
         Port                  => 587,
         Timeout               => 30,
         SkipSSLVerification   => 0,
         IsFallbackConfig      => 0,
         AuthenticationType    => 'oauth2_token',
         AuthUser              => 'mail',
         AuthPassword          => undef,
         OAuth2TokenConfigID   => 2,
         OAuth2TokenConfigName => '...',
         EmailAddresses        => [
             'znuny@example.org',
             'znuny2@example.org',
         ],
         Comments   => 'Comment',
         ValidID    => 1,
         CreateTime => '2025-08-29 12:34:56',
         ChangeTime => '2025-08-29 15:12:09',
     };



GetAll()
========


Returns all sendmail configurations, sorted by ID.


.. code-block:: perl

     my $SendmailConfigs = $SendmailConfigObject->GetAll();


Returns:


.. code-block:: perl

     my $SendmailConfigs = [
         {
             ID                    => 123,
             SendmailModule        => 'SMTPTLS',
             CMD                   => '/usr/bin/sendmail...',
             Host                  => 'smtp.example.org',
             Port                  => 587,
             Timeout               => 30,
             SkipSSLVerification   => 0,
             IsFallbackConfig      => 0,
             AuthenticationType    => 'oauth2_token',
             AuthUser              => 'mail',
             AuthPassword          => undef,
             OAuth2TokenConfigID   => 2,
             OAuth2TokenConfigName => '...',
             EmailAddresses        => [
                 'znuny@example.org',
                 'znuny2@example.org',
             ],
             Comments   => 'Comment',
             ValidID    => 1,
             CreateTime => '2025-08-29 12:34:56',
             ChangeTime => '2025-08-29 15:12:09',
         },
         # ...
     ];



GetByEmailAddress()
===================


Returns the sendmail config for the given email address.


.. code-block:: perl

     my $SendmailConfig = $SendmailConfigObject->GetByEmailAddress(
         EmailAddress => 'znuny@example.org',
 
         # optional, defaults to 0:
         # Return fallback config (if any) if no config found for email address
         UseFallback => 1,
     );


Returns:


.. code-block:: perl

     my $SendmailConfig = {
         ID                  => 123,
         SendmailModule      => 'SMTPTLS',
         CMD                 => '/usr/bin/sendmail...',
         Host                => 'smtp.example.org',
         Port                => 587,
         Timeout             => 30,
         SkipSSLVerification => 0,
         IsFallbackConfig    => 0,
         AuthenticationType  => 'oauth2_token',
         AuthUser            => 'mail',
         AuthPassword        => undef,
         OAuth2TokenConfigID => 2,
         EmailAddresses      => [
             'znuny@example.org',
             'znuny2@example.org',
         ],
         Comments   => 'Comment',
         ValidID    => 1,
         CreateTime => '2025-08-29 12:34:56',
         ChangeTime => '2025-08-29 15:12:09',
     };



GetFallback()
=============


Returns the fallback sendmail config (if one is configured).


.. code-block:: perl

     my $FallbackSendmailConfig = $SendmailConfigObject->GetFallback();


Returns:


.. code-block:: perl

     my $FallbackSendmailConfig = {
         ID                  => 123,
         SendmailModule      => 'SMTPTLS',
         CMD                 => '/usr/bin/sendmail...',
         Host                => 'smtp.example.org',
         Port                => 587,
         Timeout             => 30,
         SkipSSLVerification => 0,
         IsFallbackConfig    => 1,
         AuthenticationType  => 'oauth2_token',
         AuthUser            => 'mail',
         AuthPassword        => undef,
         OAuth2TokenConfigID => 2,
         EmailAddresses      => [],
         Comments            => 'Comment',
         ValidID             => 1,
         CreateTime          => '2025-08-29 12:34:56',
         ChangeTime          => '2025-08-29 15:12:09',
     };



GetAvailableSendmailModules()
=============================


Returns a list of available modules for sending mails (without the MultiSendmail module) and their
available config options for the config dialog.


.. code-block:: perl

     my $SendmailModules = $SendmailConfigObject->GetAvailableSendmailModules();
 
     my $Modules = {
         SMTP => {
             Host => {
                 Required     => 1,
                 DefaultValue => undef,
             },
             # ...
         },
         SMTPTLS => {
             Host => {
                 Required     => 1,
                 DefaultValue => undef,
             },
             Port => {
                 Required     => 0,
                 DefaultValue => undef,
             },
             # ...
         },
         # ...
     ];



GetSenderEmailAddresses()
=========================


Returns email addresses that are available to be selected for sendmail configs.
Optionally only returns those not yet used in any sendmail config.


.. code-block:: perl

     my $EmailAddresses = $SendmailConfigObject->GetSenderEmailAddresses(
 
         # optional; only those not used in any sendmail config
         OnlyUnused => 1,
 
         # optional together with OnlyUnused: Also return email addresses already selected in given sendmail config
         KeepForSendmailConfigID => 6,
     );
 
     my $EmailAddresses = {
         'system@example.org' => 'system@example.org (Admin Znuny)',
         # ...
     };



GetAuthenticationTypes()
========================


Returns the available authentication types.


.. code-block:: perl

     my $AuthenticationTypes = $SendmailConfigObject->GetAuthenticationTypes();


Returns:


.. code-block:: perl

     my $AuthenticationTypes = {
         # authentication type => name
         password              => 'Password',
         oauth2_token          => 'OAuth2 token',
     };



_ClearCaches()
==============


Clears all sendmail config caches.


.. code-block:: perl

     $SendmailConfigObject->_ClearCaches();



_EvaluateParams()
=================


Checks if the given param combination is valid and clears unneeded params
depending on given combination of params.


.. code-block:: perl

     my $Params = $SendmailConfigObject->_EvaluateParams(
         SendmailModule      => 'SMTPTLS',
         CMD                 => '/usr/bin/sendmail...',
         Host                => 'smtp.example.org',
         Port                => 587,
         Timeout             => 30,
         SkipSSLVerification => 0,
         IsFallbackConfig    => 0,
         AuthenticationType  => 'oauth2_token',
         AuthUser            => 'mail',
         AuthPassword        => undef,
         OAuth2TokenConfigID => 2,
         EmailAddresses      => [ # Only stored/needed if IsFallbackConfig is false
             'znuny@example.org',
             'znuny2@example.org',
         ],
         Comments => 'Comment', # optional
         ValidID  => 1,
         UserID   => 3,
     );
 
     Returns validated and cleaned up params hash, ready for storing in DB.
     On error, returns false value and logs the error.