salmon.mail module

The salmon.mail module contains nothing more than wrappers around the big work done in salmon.encoding. These are the actual APIs that you’ll interact with when doing email, and they mostly replicate the salmon.encoding.MailBase functionality.

The main design criteria is that MailRequest is mostly for reading email that you’ve received, so it doesn’t have functions for attaching files and such. MailResponse is used when you are going to write an email, so it has the APIs for doing attachments and such.

class salmon.mail.MailRequest(Peer, From, To, Data)

Bases: object

This is what is given to your message handlers. The information you get out of this is ALWAYS in Python str and should be usable by any API. Modifying this object will cause other handlers that deal with it to get your modifications, but in general you don’t want to do more than maybe tag a few headers.

Peer is the remote peer making the connection (sometimes the queue name). From and To are what you think they are. Data is the raw full email as received by the server.

NOTE: It does not handle multiple From headers, if that’s even possible. It will parse the From into a list and take the first one.

all_parts()

Returns all multipart mime parts. This could be an empty list.

body()

Always returns a body if there is one. If the message is multipart then it returns the first part’s body, if it’s not then it just returns the body. If returns None then this message has nothing for a body.

is_bounce(threshold=0.3)

Determines whether the message is a bounce message based on salmon.bounce.BounceAnalzyer given threshold. 0.3 is a good conservative base.

items()

keys()

property original

to_message()

Converts this to a Python email message you can use to interact with the python mail APIs.

walk()

Recursively walks all attached parts and their children.

class salmon.mail.MailResponse(To=None, From=None, Subject=None, Body=None, Html=None)

Bases: object

You are given MailResponse objects from the salmon.view methods, and whenever you want to generate an email to send to someone. It has the same basic functionality as MailRequest, but it is designed to be written to, rather than read from (although you can do both).

You can easily set a Body or Html during creation or after by passing it as __init__ parameters, or by setting those attributes.

You can initially set the From, To, and Subject, but they are headers so use the dict notation to change them: msg['From'] = 'joe@test.com'.

The message is not fully crafted until right when you convert it with MailResponse.to_message. This lets you change it and work with it, then send it out when it’s ready.

all_parts()

Returns all the encoded parts. Only useful for debugging or inspecting after calling to_message().

attach(filename=None, content_type=None, data=None, disposition=None)

Simplifies attaching files from disk or data as files. To attach simple text simple give data and a content_type. To attach a file, give the data/content_type/filename/disposition combination.

For convenience, if you don’t give data and only a filename, then it will read that file’s contents when you call to_message() later. If you give data and filename then it will assume you’ve filled data with what the file’s contents are and filename is just the name to use.

attach_all_parts(mail_request)

Used for copying the attachment parts of a mail.MailRequest object for mailing lists that need to maintain attachments.

attach_part(part)

Attaches a raw MailBase part from a MailRequest (or anywhere) so that you can copy it over.

clear()

Clears out the attachments so you can redo them. Use this to keep the headers for a series of different messages with different attachments.

items()

keys()

to_message()

Figures out all the required steps to finally craft the message you need and return it. The resulting message is also available as a self.base attribute.

What is returned is a Python email API message you can use with those APIs. The self.base attribute is the raw salmon.encoding.MailBase.

update(message)

Used to easily set a bunch of headers from another dict like object.