#########
MailQueue
#########


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


new()
=====


Create a MailQueue object. Do not use it directly, instead use:


.. code-block:: perl

     my $MailQueueObject = $Kernel::OM->Get('Kernel::System::MailQueue');



Create()
========


Create a new queue element.


.. code-block:: perl

     my $Result = $MailQueue->Create(
         ArticleID => '...',         # optional
         MessageID => '...',         # optional (in case article id was passed this should be also)
         Sender    => '...',
         Recipient => '...' || [],
         Message   => '...',
         Attempts  => '...',         # optional
     );


Returns 1 or undef.


List()
======


Get a list of the queue elements.


.. code-block:: perl

     my $List = $MailQueue->List(
         ID        => '...', # optional
         ArticleID => '...', # optional
         Sender    => '...', # optional
         Recipient => '...', # optional
         Attempts  => '...', # optional
     );


This returns something like:


.. code-block:: perl

     my $List = [
         {
             ID              => '...',
             ArticleID       => '...',
             Attempts        => '...',
             Sender          => '...',
             Recipient       => ['...'],
             Message         => '...',
             DueTime         => '...',
             LastSMTPCode    => '...',
             LastSMTPMessage => '...',
         },
         # ...
     ]



Get()
=====


Get a queue element.


.. code-block:: perl

     my $Item = $MailQueue->Get(
         ID        => '...', # optional
         ArticleID => '...', # optional
     );


This returns something like:


.. code-block:: perl

     $Item = {
         ID              => '...',
         ArticleID       => '...',
         Attempts        => '...',
         Sender          => '...',
         Recipient       => ['...'],
         Message         => '...',
         DueTime         => '...',
         LastSMTPCode    => '...',
         LastSMTPMessage => '...',
     };


or and empty hashref if element not found.


Update()
========


Update queue elements.


.. code-block:: perl

     my $Result = $MailQueue->Update(
         Filters => {},
         Data    => {},
     );


Returns 1 or undef.


Delete()
========


Delete queue elements.


.. code-block:: perl

     my $Result = $MailQueue->Delete(
         %Filters,       # See _FiltersSQLAndBinds
     );


Returns 1 or undef.


Send()
======


Send/Process a mail queue element/item.


.. code-block:: perl

     my $List = $MailQueue->Send(
         ID        => '...',
         Sender    => '...',
         Recipient => '...',
         Message   => '...',
         Force     => '...',     # optional, to force the sending even if isn't time
     );


This returns something like:


.. code-block:: perl

     $List = {
         Status  => '(Failed|Pending|Success)',
         Message => '...',                      # undef if success.
     };




*****************
PRIVATE INTERFACE
*****************


_SendSuccess()
==============


This method is called after a MailQueue item is successfully sent.
It clears the item from the MailQueue, closes the communication log and
triggers a Event Notification.


.. code-block:: perl

     my $Result = $Object->_SendSuccess(
         Item => {
             ID                     => ...,
             ArticleID              => ...,  # optional
             UserID                 => ...,
             CommunicationLogObject => ...,
         }
     );


Returns 1 or undef.


_SendError()
============


Handles Send errors.
Situations where the mail queue item is deleted:
- SMTP 5?? errors codes, considered permanent errors.
- reached maximum attempts


.. code-block:: perl

     $Object->_SendError(
         Item       => '...',
         SendResult => '...',
     );


This always returns undef.


_SetArticleTransmissionError()
==============================


Creates or Updates the Article Transmission Error record with the error message.
Then, fires a Notification Event.


.. code-block:: perl

     my $Result = $Object->_SetArticleTransmissionError(
         ArticleID              => 123,
         Message                => '...',
         MessageID              => 123,
         UserID                 => 1,
         ForceUpdate            => '...',
         CommunicationLogObject => '...',
     );


Returns 1 or undef.


_SendEventNotification()
========================


Formats a Notification and asks Event Handler to send it.


.. code-block:: perl

     my $Result = $Object->_SendEventNotification(
         ArticleID => 123,
         Status    => "Queued|Sent|Error",
         Message   => '...',
         UserID    => 1,
     );


This returns something like:


.. code-block:: perl

     my $Result = {
         Status  => 'Failed',
         Message => 'Need ArticleID',
     };


in case of missing or invalid arguments, or the status of the EventHandler call.


_FiltersSQLAndBinds()
=====================


Build the filter sql and associated binds.


.. code-block:: perl

     my ( $FilterSQL, $Binds ) = $MailQueue->_FiltersSQLAndBinds(
         ID              => 1,       # optional
         ArticleID       => 123,     # optional
         CommunicationID => 123,     # optional
         Sender          => '...',   # optional
         Recipient       => '...',   # optional
         Attempts        => '...',   # optional
     );


This returns something like:


.. code-block:: perl

     $FilterSQL = '...';
     $Binds     = \[...];



_CheckValidEmailAddresses()
===========================


Check if the provided email address(es) is valid.


.. code-block:: perl

     my $IsValid = $MailQueue->_CheckValidEmailAddresses(
         ParamName => '...',         # name of the parameter that we are checking
         Addresses => '...', || []   # email addresses to validate
     );


Returns 1 or undef.


_CheckValidMessageData()
========================


Check if the provided data is a non-empty hash-ref.


.. code-block:: perl

     my $IsValid = $MailQueue->_CheckValidMessageData(
         Data => {
             # ...
         },
     );


Returns 1 or undef.


_SerializeMessage()
===================


Serialize a simple perl structure to be save in the database.

Returns an encoded or a storable string.


_DeserializeMessage()
=====================


Deserialize a simple perl structure to the original format.


_IsArticleAlreadyQueued()
=========================


Checks if the article is already queued.

Returns 1 or undef.


_DBInsert()
===========


Inserts a new record in the table and returns the newly record id.
Returns a number (id of the new record inserted) or undef.


_CreateCommunicationLogLookup()
===============================


Creates the mail-queue item communication-log message association.
It will also create the association for the article if any ArticleID was passed.
Returns 1 always.


_GetCommunicationLog()
======================


Get the communication log associated to the queue item, if not found, creates a new one.


.. code-block:: perl

     my $CommunicationLog = $Self->_GetCommunicationLog(
         ID => '...',    # mail-queue item ID
     );


Returns communication-log object.