MailQueue

MailQueue#

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              => 123,
    Message                => '...',
    MessageID              => 123,
    UserID                 => 1,
    ForceUpdate            => '...',
    CommunicationLogObject => '...',
);

Returns 1 or undef.

_SendEventNotification()#

Formats a Notification and asks Event Handler to send it.

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

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              => 1,       # optional
    ArticleID       => 123,     # optional
    CommunicationID => 123,     # 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.

Contents