API

This part of the documentation covers all the interfaces of mailProc. For parts where mailProc depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Application Object

class mailproc.Mailproc(name)

The Mailproc object implements an application and acts as the central object. It is passed the name of the application. Once it is created it will act as a central registry for routes and much more.

Parameters:

name – The name of the mailProc application. This name will be used for identify the current running application.

static build_route_pattern(route)

Converts a route pattern to a regular expression

Parameters:

route – Route pattern string

Returns:

Compiled regular expression

get_route_match(path, in_target)

Try to find a matching registered action function

Parameters:

  • path – Route string

  • in_target – Routes target to find the action. Can be ‘from’ or ‘subject’

Returns:

Returns function arguments and action function pair or None if there is no matching actions.

route(rule, routes_target)

A decorator that is used to register an action for a given rule and target

Parameters:

  • rule – Match rule as string

  • routes_target – Target to be applied the given rule, can be ‘from’ or ‘subject’

route_from(route_str)

A decorator that is used to register an action for an email “From” address

Parameters:

route_str – Match rule as string

route_subject(route_str)

A decorator that is used to register an action for an email subject

Parameters:

route_str – Match rule as string

run(mails)

Apply registered actions to Message objects

Parameters:

mails – A list of Message objects

serve_route(path, target, **kwargs)

Run action functions matching a route path pattern and target

Parameters:

  • path – Route path string

  • target – Routes target to find the action. Can be ‘from’ or ‘subject’

  • kwargs – Additional arguments to pass to the action

Returns:

Action function return value

static set_proc_name(new_name)

Try to set a system name to the python process

Parameters:

new_name – Process name

static to_mailproc_email(message)

Return a copy of Message object as a mailproc.Email instance

Parameters:

message – Message object

Returns:

mailproc.Email object

Email Object

class mailproc.Email(policy=Compat32())

Email utility class. This class is intended to be used as an utility class for interacting with Message objects

static decode_mime_words(s)

Return a decoded mime header string

Parameters:

s – String to decode

Returns:

Decoded string

get_body(html=False)

Return Email body

Parameters:

html – Get Email HTML body. Default: False

Returns:

Email body

get_from()

Return the raw ‘From’ header

Returns:

From header string

get_from_address()

Return ‘From’ header email address

Returns:

From email address string

get_from_name(decode=True)

Return email ‘From’ header name

Parameters:

decode – If True, try to decode

Returns:

Email From header name string

get_json_attachment(attachment_name=None, attachment_content_type=None, base64_decode=False, gzipped=False, email_encode='utf-8')

Return a json object stored in attachment

Parameters:

  • attachment_name – Name of attachment file to find

  • attachment_content_type – Content type of attachment file to find

  • base64_decode – If true looks for a base64 encoded json file

  • gzipped – If true try to unzip an attachment gzip file

  • email_encode – Encoding for treat body attachments. Default: ‘utf-8’

Returns:

Json object stored in email attachment

get_subject(decode=True)

Return email subject

Parameters:

decode – If True, try to decode

Returns:

Email subject string

Receiver Transports

class mailproc.transports.BaseReceiverTransport

Base class for mailProc receiver transports

abstract close()

Abstract close function

abstract connect()

Abstract connect function

abstract get_mails()

Abstract get_mails function

class mailproc.transports.FileReceiverTransport(directory, **kwargs)

File Receiver Transport. This class is mostly intended for testing proposes but you are encouraged to find a different use for it :)

Parameters:

directory – Directory path for obtaining raw emails in file system.

close()

Abstract close function

connect(**kwargs)

Abstract connect function

get_mails(extension='.eml', delete=False, **kwargs)

Returns mails stored in directory constructor parameter

Parameters:

  • extension – obtain files with extension (default: “.eml”)

  • delete – Delete obtained emails in directory (default False)

Returns:

List of Message objects

class mailproc.transports.ImapReceiverTransport(server, username, password, port=None, use_ssl=True, **kwargs)

IMAP Receiver Transport. This class instances a receiver object for the IMAP protocol

Parameters:

  • server – Server for establish the IMAP connection

  • username – Server identifying username

  • password – Server identifying password

  • port – Server port for establish the IMAP connection. Default: None (for standard IMAP port)

  • use_ssl – Use ssl connection. Default: True

close()

Close current IMAP connection

connect(**kwargs)

Starts a new IMAP connection

get_mails(get_msgs_type='(UNSEEN)', mailbox='INBOX', delete=False, **kwargs)

Returns new (unseen) mails from account

Parameters:

  • get_msgs_type – Expression for emails to get ‘(UNSEEN)’ by default to get new emails

  • mailbox – IMAP mailbox for fetching emails, default: “INBOX”

  • delete – Delete obtained emails in account (default False)

Returns:

List of email.Message objects

class mailproc.transports.ImapIdleReceiverTransport(server, username, password, callback, port=None, use_ssl=True, idle_timeout=480, idle_loop=True, **kwargs)

IMAP Idle Receiver Transport. This class instances a receiver object for the IMAP protocol which uses the IMAP IDLE check for obtaining new emails

Parameters:

  • server – Server for establish the IMAP connection

  • username – Server identifying username

  • password – Server identifying password

  • callback – Callback function for processing incoming emails

  • port – Server port for establish the IMAP connection. Default: None (for standard IMAP port)

  • use_ssl – Use ssl connection. Default: True

  • idle_timeout – Timeout for idle connections (in seconds). Default: 8 minutes (60*8)

  • idle_loop – Restart the IDLE connection when timeout. Default: True

close()

Close current IMAP connection

connect(**kwargs)

Starts a new IMAP connection

get_mails(get_msgs_type='(UNSEEN)', mailbox='INBOX', delete=False, **kwargs)

Starts monitoring an IMAP inbox for incoming emails

Parameters:

  • get_msgs_type – Expression for emails to get ‘(UNSEEN)’ by default to get new emails

  • mailbox – IMAP mailbox for fetching emails, default: “INBOX”

  • delete – Delete obtained emails in account (default False)

Sender Transports

class mailproc.transports.BaseSenderTransport

Base class for mailProc sender transports

abstract close(*args, **kwargs)

Abstract close function

abstract connect(*args, **kwargs)

Abstract connect function

create_message(email_from, email_to, email_subject, email_text, email_html=None, email_bcc=None, email_encode='utf-8', json_attachment=None, json_attachment_filename='attachment.json', json_attachment_base64_encode=False, json_attachment_gzip=False)

Send an email message with text only or multipart HTML body

Parameters:

  • email_from – ‘From’ email address

  • email_to – Email ‘To’ address, List of string also allowed

  • email_subject – Email subject

  • email_text – Text only mail body

  • email_html – HTML mail body

  • email_bcc – List of Blind Carbon Copy (BCC) addresses

  • email_encode – Email encode (default utf-8)

  • json_attachment – JSON Object to send as a JSON attachment file

  • json_attachment_filename – JSON attachment filename (default attachment.json)

  • json_attachment_base64_encode – Apply a base64 encode to JSON file (default False)

  • json_attachment_gzip – Send JSON attachment as gzip file (default False)

abstract send_mail(*args, **kwargs)

Abstract send_mail function

class mailproc.transports.FileSenderTransport(directory, **kwargs)

File Sender Transport. This class is mostly intended for testing proposes but you are encouraged to find a different use for it :)

Parameters:

directory – Directory path for saving raw emails in file system.

close()

Abstract close function

connect(**kwargs)

Abstract connect function

create_message(email_from, email_to, email_subject, email_text, email_html=None, email_bcc=None, email_encode='utf-8', json_attachment=None, json_attachment_filename='attachment.json', json_attachment_base64_encode=False, json_attachment_gzip=False)

Send an email message with text only or multipart HTML body

Parameters:

  • email_from – ‘From’ email address

  • email_to – Email ‘To’ address, List of string also allowed

  • email_subject – Email subject

  • email_text – Text only mail body

  • email_html – HTML mail body

  • email_bcc – List of Blind Carbon Copy (BCC) addresses

  • email_encode – Email encode (default utf-8)

  • json_attachment – JSON Object to send as a JSON attachment file

  • json_attachment_filename – JSON attachment filename (default attachment.json)

  • json_attachment_base64_encode – Apply a base64 encode to JSON file (default False)

  • json_attachment_gzip – Send JSON attachment as gzip file (default False)

send_mail(email_from, email_to, email_subject, email_text, email_html=None, email_bcc=None, email_encode='utf-8', log=None, json_attachment=None, json_attachment_filename='attachment.json', json_attachment_base64_encode=False, json_attachment_gzip=False, **kwargs)

Save an email message with text only or multipart HTML body in directory constructor parameter path

Parameters:

  • email_from – ‘From’ email address

  • email_to – Email ‘To’ address, List of string also allowed

  • email_subject – Email subject

  • email_text – Text only mail body

  • email_html – HTML mail body

  • email_bcc – List of Blind Carbon Copy (BCC) addresses

  • email_encode – Email encode (default utf-8)

  • log – Log message (default None)

  • json_attachment – JSON Object to send as a JSON attachment file

  • json_attachment_filename – JSON attachment filename (default attachment.json)

  • json_attachment_base64_encode – Apply a base64 encode to JSON file (default False)

  • json_attachment_gzip – Send JSON attachment as gzip file (default False)

class mailproc.transports.SmtpSenderTransport(server, username, password, port=None, use_ssl=True, use_tls=False, **kwargs)

SMTP Sender Transport. This class instances a sender object for the SMTP protocol

Parameters:

  • server – Server for establish the SMTP connection

  • username – Server identifying username

  • password – Server identifying password

  • port – Server port for establish the SMTP connection. Default: None (for standard SMTP port)

  • use_ssl – Use ssl secure connection. Default: True

  • use_tls – Use tls secure connection. Default: False

close()

Close current SMTP connection

connect()

Starts a new SMTP connection

create_message(email_from, email_to, email_subject, email_text, email_html=None, email_bcc=None, email_encode='utf-8', json_attachment=None, json_attachment_filename='attachment.json', json_attachment_base64_encode=False, json_attachment_gzip=False)

Send an email message with text only or multipart HTML body

Parameters:

  • email_from – ‘From’ email address

  • email_to – Email ‘To’ address, List of string also allowed

  • email_subject – Email subject

  • email_text – Text only mail body

  • email_html – HTML mail body

  • email_bcc – List of Blind Carbon Copy (BCC) addresses

  • email_encode – Email encode (default utf-8)

  • json_attachment – JSON Object to send as a JSON attachment file

  • json_attachment_filename – JSON attachment filename (default attachment.json)

  • json_attachment_base64_encode – Apply a base64 encode to JSON file (default False)

  • json_attachment_gzip – Send JSON attachment as gzip file (default False)

send_mail(email_from, email_to, email_subject, email_text, email_html=None, email_bcc=None, email_encode='utf-8', log=None, json_attachment=None, json_attachment_filename='attachment.json', json_attachment_base64_encode=False, json_attachment_gzip=False, **kwargs)

Send an email message with text only or multipart HTML body

Parameters:

  • email_from – ‘From’ email address

  • email_to – Email ‘To’ address, List of string also allowed

  • email_subject – Email subject

  • email_text – Text only mail body

  • email_html – HTML mail body

  • email_bcc – List of Blind Carbon Copy (BCC) addresses

  • email_encode – Email encode (default utf-8)

  • log – Log message (default None)

  • json_attachment – JSON Object to send as a JSON attachment file

  • json_attachment_filename – JSON attachment filename (default attachment.json)

  • json_attachment_base64_encode – Apply a base64 encode to JSON file (default False)

  • json_attachment_gzip – Send JSON attachment as gzip file (default False)