pymailq.store – Mails queue storage objects¶

The store module provide several objects to convert mails queue content into python structures.

`PostqueueStore` Objects¶

class pymailq.store.PostqueueStore[source]¶

Postfix mails queue informations storage.

The PostqueueStore provides methods to load Postfix queued mails informations into Python structures. Thoses structures are based on Mail and MailHeaders classes which can be processed by a MailSelector instance.

The PostqueueStore class defines the following attributes:

mails¶

Loaded MailClass objects list().

loaded_at¶

datetime.datetime instance to store load date and time informations, useful for datas deprecation tracking. Updated on load() call with datetime.datetime.now() method.

postqueue_cmd¶

list object to store Postfix command and arguments to view the mails queue content. This property use Postfix mails content parsing command defined in pymailq.CONFIG attribute under the key ‘list_queue’. Command and arguments list is build on call with the configuration data.

spool_path¶

Postfix spool path string. Default is "/var/spool/postfix".

postqueue_mailstatus¶

Postfix known queued mail status list. Default is ['active', 'deferred', 'hold'].

mail_id_re¶

Python compiled regular expression object (re.RegexObject) provided by re.compile() method to match postfix IDs. Recognized IDs are either:

hexadecimals, 8 to 12 chars length (regular queue IDs)

encoded in a 52-character alphabet, 11 to 16 chars length (long queue IDs)

They can be followed with * or !. Default used regular expression is:

r"^([A-F0-9]{8,12}|[B-Zb-z0-9]{11,16})[*!]?$".

mail_addr_re¶

Python compiled regular expression object (re.RegexObject) provided by re.compile() method to match email addresses. Default used regular expression is: r"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]+$"

MailClass¶

The class used to manipulate/parse mails individually. Default is Mail.

See also

Python modules:

datetime – Basic date and time types

re – Regular expression operations

Postfix manual:

postqueue – Postfix queue control

RFC 3696 – Checking and Transformation of Names

The PostqueueStore instance provides the following methods:
PostqueueStore.load([method])[source]¶

Load content from postfix mails queue.

Mails are loaded using postqueue command line tool or reading directly from spool. The optionnal argument, if present, is a method string and specifies the method used to gather mails informations. By default, method is set to "postqueue" and the standard Postfix queue control tool: postqueue is used.

Optionnal argument parse controls whether mails are parsed or not. This is useful to load every known mail headers for later filtering.

Parameters:

method (str) – Method used to load mails from Postfix queue

filename (str) – File to load mails from

parse (bool) – Controls whether loaded mails are parsed or not.

Provided method str() name is directly used with getattr() to find a self._load_from_<method> method.
PostqueueStore._load_from_postqueue()[source]¶
Load content from postfix queue using postqueue command output.

Output lines from _get_postqueue_output are parsed to build Mail objects. Sample Postfix queue control tool (postqueue) output:
C0004979687     4769 Tue Apr 29 06:35:05  sender@domain.com
(error message from mx.remote1.org with parenthesis)
                                         first.rcpt@remote1.org
(error message from mx.remote2.org with parenthesis)
                                         second.rcpt@remote2.org
                                         third.rcpt@remote2.org
Parsing rules are pretty simple:

Line starts with a valid Mail.qid: create new Mail object with qid, size, date and sender informations from line.

Queue ID Size Reception date and time Sender

C0004979687 4769 Tue Apr 29 06:35:05 user@domain.com

Line starts with a parenthesis: store error messages to last created Mail object’s errors attribute.

Any other matches: add new recipient to the recipients attribute of the last created Mail object.

Optionnal argument filename can be set with a file containing output of the postqueue command. In this case, output lines of postqueue command are directly read from filename and parsed, the postqueue command is never used.

Optionnal argument parse controls whether mails are parsed or not. This is useful to load every known mail headers for later filtering.

Parameters:

filename (str) – File to load mails from

parse (bool) – Controls whether loaded mails are parsed or not.
PostqueueStore._load_from_spool()[source]¶

Load content from postfix queue using files from spool.

Mails are loaded using the command defined in postqueue_cmd attribute. Some informations may be missing using the _load_from_spool() method, including at least Mail.status field.

Optionnal argument parse controls whether mails are parsed or not. This is useful to load every known mail headers for later filtering.

Loaded mails are stored as Mail objects in mails attribute.

Parameters: parse (bool) – Controls whether loaded mails are parsed or not.

Warning

Be aware that parsing mails on disk is slow and can lead to high load usage on system with large mails queue.

PostqueueStore._get_postqueue_output()[source]¶

Get Postfix postqueue command output.

This method used the postfix command defined in postqueue_cmd attribute to view the mails queue content.

Command defined in postqueue_cmd attribute is runned using a subprocess.Popen instance.

Returns: Command’s output lines.

Return type: list()

See also

Python module:

subprocess – Subprocess management

PostqueueStore._is_mail_id(mail_id)[source]¶

Check mail_id for a valid postfix queued mail ID.

Validation is made using a re.RegexObject stored in the mail_id_re attribute of the PostqueueStore instance.

Parameters: mail_id (str) – Mail Postfix queue ID string

Returns: True or false

Return type: bool()
PostqueueStore.summary()[source]¶
Summarize the mails queue content.

Returns: Mail queue summary as dict

Sizes are in bytes.

Example response:
{
    'total_mails': 500,
    'total_mails_size': 709750,
    'average_mail_size': 1419.5,
    'max_mail_size': 2414,
    'min_mail_size': 423,
    'top_errors': [
        ('mail transport unavailable', 484),
        ('Test error message', 16)
    ],
    'top_recipient_domains': [
        ('test-domain.tld', 500)
    ],
    'top_recipients': [
        ('user-3@test-domain.tld', 200),
        ('user-2@test-domain.tld', 200),
        ('user-1@test-domain.tld', 100)
    ],
    'top_sender_domains': [
        ('test-domain.tld', 500)
    ],
    'top_senders': [
        ('sender-1@test-domain.tld', 100),
        ('sender-2@test-domain.tld', 100),
        ('sender-7@test-domain.tld', 50),
        ('sender-4@test-domain.tld', 50),
        ('sender-5@test-domain.tld', 50)
    ],
    'top_status': [
        ('deferred', 500),
        ('active', 0),
        ('hold', 0)
    ],
    'unique_recipient_domains': 1,
    'unique_recipients': 3,
    'unique_sender_domains': 1,
    'unique_senders': 8
}

`Mail` Objects¶

class pymailq.store.Mail(mail_id[, size[, date[, sender]]])[source]¶

Simple object to manipulate email messages.

This class provides the necessary methods to load and inspect mails content. This object functionnalities are mainly based on email module’s provided class and methods. However, email.message.Message instance’s stored informations are extracted to extend Mail instances attributes.

Initialization of Mail instances are made the following way:

Parameters:

mail_id (str) – Mail’s queue ID string

size (int) – Mail size in Bytes (Default: 0)

date (datetime.datetime) – Acceptance date and time in mails queue. (Default: None)

sender (str) – Mail sender string as seen in mails queue. (Default: empty str())

The Mail class defines the following attributes:

qid¶

Mail Postfix queue ID string, validated by _is_mail_id() method.

size¶

Mail size in bytes. Expected type is int().

parsed¶

bool() value to track if mail’s content has been loaded from corresponding spool file.

parse_error¶

Last encountered parse error message str().

date¶

datetime object of acceptance date and time in mails queue.

status¶

Mail’s queue status str().

sender¶

Mail’s sender str() as seen in mails queue.

recipients¶

Recipients list() as seen in mails queue.

errors¶

Mail deliver errors list() as seen in mails queue.

head¶

Mail’s headers MailHeaders structure.

postcat_cmd¶

This property use Postfix mails content parsing command defined in pymailq.CONFIG attribute under the key ‘cat_message’. Command and arguments list is build on call with the configuration data.

See also

pymailq.CONFIG – Configuration structure and usage

The Mail instance provides the following methods:

Mail.parse()[source]¶

Parse message content.

This method use Postfix mails content parsing command defined in postcat_cmd attribute. This command is runned using subprocess.Popen instance.

Parsed headers become attributes and are retrieved with help of message_from_string() function provided by the email module.

See also

Postfix manual:

postcat – Show Postfix queue file contents

Mail.dump()[source]¶

Dump mail’s gathered informations to a dict object.

Mails informations are splitted in two parts in dictionnary. postqueue key regroups every informations directly gathered from Postfix queue, while headers regroups MailHeaders attributes converted from mail content with the parse() method.

If mail has not been parsed with the parse() method, informations under the headers key will be empty.

Returns: Mail gathered informations

Return type: dict

Mail.show()[source]¶

Return mail detailled representation for printing

Returns: Representation as str

`MailHeaders` Objects¶

class store.MailHeaders[source]¶

Simple object to store mail headers.

Object’s attributes are dynamically created when parent Mail object’s method parse() is called. Those attributes are retrieved with help of message_from_string() method provided by the email module.

Standard RFC 822-style mail headers becomes attributes including but not limited to:

Received

From

To

Cc

Bcc

Sender

Reply-To

Subject

Case is kept while creating attribute and access will be made with Mail.From or Mail.Received for example. All those attributes will return list of values.

See also

Python modules:

email – An email and MIME handling package

email.message.Message – Representing an email message

RFC 822 – Standard for ARPA Internet Text Messages