• PUBLIC INTERFACE
  • new()
  • Create()
  • List()
  • Get()
  • Update()
  • Delete()
  • Send()
• PRIVATE INTERFACE
  • _SendSuccess()
  • _SendError()
  • _SetArticleTransmissionError()
  • _SendEventNotification()
  • _FiltersSQLAndBinds()
  • _CheckValidEmailAddresses()
  • _CheckValidMessageData()
  • _SerializeMessage()
  • _DeserializeMessage()
  • _IsArticleAlreadyQueued()
  • _DBInsert()
  • _CreateCommunicationLogLookup()
  • _GetCommunicationLog()
• TERMS AND CONDITIONS

PUBLIC INTERFACE

new()

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

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

Create()

Create a new queue element.

    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.

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

This returns something like:

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

Get()

Get a queue element.

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

This returns something like:

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

or and empty hashref if element not found.

Update()

Update queue elements.

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

Returns 1 or undef.

Delete()

Delete queue elements.

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

Returns 1 or undef.

Send()

Send/Process a mail queue element/item.

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

This returns something like:

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

    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

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

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

Returns 1 or undef.

_SendEventNotification()

Formats a Notification and asks Event Handler to send it.

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

This returns something like:

    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.

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

This returns something like:

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

_CheckValidEmailAddresses()

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

    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.

    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.

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

Returns communication-log object.

TERMS AND CONDITIONS

This software is part of the OTRS project (https://otrs.org/).

This software comes with ABSOLUTELY NO WARRANTY. For details, see the enclosed file COPYING for license information (GPL). If you did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.