mail

The module provides interfaces for sending and reading electronic mails and provides implementation for the SMTP, IMAP and POP3 mail exchange protocols.

Fields

mail.TLS_NONE

Do not attempt to use SSL.

mail.TLS_TRY

Try using SSL, proceed as normal otherwise. Note that server may close the connection if the negotiation does not succeed.

mail.TLS_CONTROL

Require SSL for the control connection or fail.

mail.TLS_ALL

Require SSL for all communication or fail.

Functions

mail.parse(message)

Parses email messages and return an instance of Mail representing it.

• @params:
  • string message

• @returns: Mail

mail.smtp(options)

Returns a new instance of SMTP Transport with the given options.

• @params:
  • {dict?} options See Transport

• @returns: Transport

mail.pop3(options) ➝ Exported

Returns a new instance of the POP3 class with the given options (if any) passed to the constructor.

• @returns: POP3

mail.imap(options) ➝ Exported

Returns a new instance of the Imap class with the given options (if any) passed to the constructor.

• @returns: Imap

mail.message() ➝ Exported

Returns a new instance of Message.

• @returns: Message

Classes

class Attachment

Attachment class is used to hold the information of attachments in the message.

@printable, @serializable

.Attachment(headers, content) ➝ Constructor

mail.Attachment constructor

• @params:
  • dict headers
  • string content

class Mail

The Mail class represents a mail message as a blade object with the following properties.

@printable, @serializable

.Mail(headers, body, attachments) ➝ Constructor

mail.Mail constructor

• @params:

  • dict headers A dictionary containing the key/value pair contained in the mail message header.

  • dict body A dictionary containing the different segments of a mail body such as its plain text and html counterpart.

  • list[Attachment] attachments A list of attachments contained in the Mail message.

class Transport

Transport class can be used to send email messages through an SMTP server.

The class constructor takes a single argument options, which should be a dictionary containing various options for the connection. If the options are not provided or are not a dictionary, the constructor will raise an exception.

The class uses the options to set various properties such as the host and port of the SMTP server, the username and password for authentication, and various options for connecting to the server such as the use of TLS, and timeout.

.Transport(options) ➝ Constructor

The Transport class accepts a dictionary that can be used to configure how it behaves. The dictionary can contain one or more of the following.

• host: The host address of the SMTP server. (Default: localhost)

• port: The port number of the SMTP server. (Default: 465)

• username: The access username for the SMTP user.

• password: The password for the connection user.

• tls: The TLS mode of the connection. One of ssl.TLS_TRY (default), ssl.TLS_CONTROL, ssl.TLS_ALL or ssl.TLS_NONE.

• debug: Whether to print debug information or not. (Default: false)

• verify_peer: If the peer certificate should be verified or not. (Default: false)

• verify_host: If the host certificate should be verified or not. (Default: false)

• proxy: The address of the proxy server if any.

• proxy_username: The username for the proxy connection.

• proxy_password: The password for the user of the proxy connection.

• verify_proxy_peer: If the peer certificate of the proxy should be verified or not. (Default: The value of verify_peer)

• verify_proxy_host: If the host certificate of the proxy should be verified or not. (Default: The value of verify_host)

• timeout: The request timeout in milliseconds. (Default: 30,000)

• @params:

  • dict? options

.add_message(message)

Adds an email message to the list of messages to be sent.

• @params:
  • Message message

• @returns: Transport

.test_connection()

Tests the connection to the SMTP server

• @returns: bool

.verify(address)

Verifies an email address

• @params:
  • string address

• @returns: bool

.send()

Send the email messages and returns true if the message was successfully sent or false otherwise.

• @returns: bool

class POP3

The POP3 class provides an interface for connecting to an POP3 (Post Office Protocol) server and interacting with the server via the POP3 protocol.

This class includes operations for creating, deleting, and renaming mailboxes, checking for new messages, permanently removing messages, setting and clearing flags searching, and selective fetching of message attributes, texts, and portions.

.POP3(options) ➝ Constructor

The POP3 class accepts a dictionary that can be used to configure how it behaves. The dictionary can contain one or more of the following.

• host: The host address of the POP3 server. (Default: localhost)

• port: The port number of the POP3 server. (Default: 110)

• username: The access username for the POP3 user.

• password: The password for the connection user.

• tls: The TLS mode of the connection. One of ssl.TLS_TRY (default), ssl.TLS_CONTROL, ssl.TLS_ALL or ssl.TLS_NONE.

• debug: Whether to print debug information or not. (Default: false)

• verify_peer: If the peer certificate should be verified or not. (Default: false)

• verify_host: If the host certificate should be verified or not. (Default: false)

• proxy: The address of the proxy server if any.

• proxy_username: The username for the proxy connection.

• proxy_password: The password for the user of the proxy connection.

• verify_proxy_peer: If the peer certificate of the proxy should be verified or not. (Default: The value of verify_peer)

• verify_proxy_host: If the host certificate of the proxy should be verified or not. (Default: The value of verify_host)

• timeout: The request timeout in milliseconds. (Default: 30,000)

• @params:

  • dict? options

.exec(command, path, no_transfer)

Executes an POP3 command.

as response response. Default false.

• @params:

  • string command The command to execute.

  • string? path The path segment of the request url.

  • bool? no_transfer Set to true if the command will return the requested data

• @returns: string The response from the server.

.list(uid)

Returns a list of dictionaries containing the uid and size of each message in the mail if the uid argument is not given or the content of the message identified by the given uid.

• @params:
  • number? uid

• @returns: list[dictionary]|string

.uid_list()

Returns a list of dictionaries containing the uid and id for every message in the mailbox based on their unique ids.

• @returns: list[dictionary]

.retr(uid)

Retrieves the whole message with the specified uid.

• @params:
  • number uid

• @returns: string

.stat()

Returns a dictionary containing the message count and size of the mailbox.

• @returns: dictionary

.delete(uid)

Instructs the POP3 server to mark the message uid as deleted. Any future reference to the message-number associated with the message in a POP3 command generates an error.
The POP3 server does not actually delete the message until the POP3 session enters the UPDATE state.

• @params:
  • number uid

.noop()

Does nothing. It merely ask the server to reply with a positive response.

@notes:

• It's useful for a keep-alive.

.rset()

Instructs the server to unmark any messages have been marked as deleted.

.top(uid, count)

Retrieves the header for the message identified by uid plus count lines of the message after the header of message.

• @params:
  • number uid
  • number? count (Default: 0)

• @returns: string

.quit()

Closes the current POP3 session and disposes all associated network handles.

.get_handle()

Returns the raw handle to the underlying networking (curl) client.

class Imap

The Imap class provides an interface for connecting to an IMAP (Internet Mail Access Protocol) server and interacting with the server via the IMAP protocol.

This class includes operations for creating, deleting, and renaming mailboxes, checking for new messages, permanently removing messages, setting and clearing flags searching, and selective fetching of message attributes, texts, and portions.

.Imap(options) ➝ Constructor

The Imap class accepts a dictionary that can be used to configure how it behaves. The dictionary can contain one or more of the following.

• host: The host address of the Imap server. (Default: localhost)

• port: The port number of the Imap server. (Default: 143)

• username: The access username for the Imap user.

• password: The password for the connection user.

• tls: The TLS mode of the connection. One of ssl.TLS_TRY (default), ssl.TLS_CONTROL, ssl.TLS_ALL or ssl.TLS_NONE.

• debug: Whether to print debug information or not. (Default: false)

• verify_peer: If the peer certificate should be verified or not. (Default: false)

• verify_host: If the host certificate should be verified or not. (Default: false)

• proxy: The address of the proxy server if any.

• proxy_username: The username for the proxy connection.

• proxy_password: The password for the user of the proxy connection.

• verify_proxy_peer: If the peer certificate of the proxy should be verified or not. (Default: The value of verify_peer)

• verify_proxy_host: If the host certificate of the proxy should be verified or not. (Default: The value of verify_host)

• timeout: The request timeout in milliseconds. (Default: 30,000)

• @params:

  • dict? options

.exec(command, path)

Executes an IMAP command.

• @params:

  • string command The command to execute.

  • string? path The path segment of the request url.

• @returns: string The response from the server.

.get_dirs(path)

Gets a list of the mailbox directories on the server.

• @params:
  • string? path

• @returns: list

.get_subscribed_dirs()

Gets a list of mailbox directories subscribed to by the current user on the server.

• @returns: list

.select(name)

Instructs the server that the client now wishes to select a particular mailbox or folder with the name name, and any commands that relate to a folder should assume this folder as the target of that command. For example, an INBOX or a subfolder such as, "To Do.This Weekend". Once a mailbox is selected, the state of the connection becomes "Selected".

@see https://www.marshallsoft.com/ImapSearch.htm for more help.

• @params:
  • string name

• @returns: dictionary

.examine(name)

This function does the exact same thing as select(), except that it selects the folder in read-only mode, meaning that no changes can be effected on the folder.

• @params:
  • string name

• @returns: dictionary

.create(name)

Creates a new mailbox or folder with the given name.

• @params:
  • string name

• @returns: list

.delete(name)

Deletes the mailbox or folder with the given name.

• @params:
  • string name

• @returns: list

.rename(old_name, new_name)

Renames a mailbox or folder with the name old_name to a the name new_name.

• @params:
  • string old_name
  • string new_name

• @returns: list

.subscribe(name)

Adds the specified mailbox name to the server's set of "active" or "subscribed" mailboxes for the current user as returned by lsub() and returns true if successful or false otherwise.

• @params:
  • string name

• @returns: bool

.unsubscribe(name)

Removes the specified mailbox name from the server's set of "active" or "subscribed" mailboxes for the current user as returned by lsub() and returns true if successful or false otherwise.

• @params:
  • string name

• @returns: bool

.list(name, pattern)

Returns a subset of names from the complete set of all names available to the client. Zero or more dictionaries are returned, containing the name attributes, hierarchy delimiter, and name.

An empty ("" string) name argument indicates that the mailbox name is interpreted as by SELECT. A non-empty name argument is the name of a mailbox or a level of mailbox hierarchy, and indicates the context in which the mailbox name is interpreted.

An empty ("" string) pattern argument is a special request to return the hierarchy delimiter and the root name of the name given in the reference.

The pattern character is a wildcard, and matches zero or more characters at this position. The character `%` is similar to, but it does not match a hierarchy delimiter. If the % wildcard is the last character of a pattern argument, matching levels of hierarchy are also returned. If these levels of hierarchy are not also selectable mailboxes, they are returned with the \Noselect pattern attribute.

The special name INBOX is included in the output from list(), if INBOX is supported by the server for the current user and if the uppercase string "INBOX" matches the interpreted reference and pattern arguments with wildcards as described above. The criteria for omitting INBOX is whether select('INBOX') will return failure; it is not relevant whether the user's real INBOX resides on the server or another.

• @params:
  • string name
  • string? pattern

• @returns: list

.lsub(name, pattern)

Same as the list() function except that it returns a subset of names.

• @params:
  • string name
  • string? pattern

• @returns: list

.status(name, attrs)

Requests the status of the indicated mailbox.

It is important to know that unlike the LIST command, the STATUS command is not guaranteed to be fast in its response. Under certain circumstances, it can be quite slow.

attrs values being one of:

• MESSAGES: The number of messages in the mailbox.
• RECENT: The number of messages with the \Recent flag set.
• UIDNEXT: The next unique identifier value of the mailbox.
• UIDVALIDITY: The unique identifier validity value of the mailbox.
• UNSEEN: The number of messages which do not have the \Seen flag set.

attrs values may be separated by space. e.g. status('INBOX', 'UIDNEXT MESSAGES').

• @params:
  • string name
  • string attrs

• @returns: bool|string

.append(folder, message)

Appends messages to a mailbox directories such as INBOX or top-level folders and returns true if it succeeds or false otherwise.

NOTE: This isn’t a copy/move command, you must supply a full message body to append.

• @params:
  • string folder
  • Message message

• @returns: bool

.check()

Requests a checkpoint of the currently selected mailbox. A checkpoint refers to any implementation-dependent housekeeping associated with the mailbox (e.g., resolving the server's in-memory state of the mailbox with the state on its disk) that is not normally executed as part of each command. A checkpoint MAY take a non-instantaneous amount of real time to complete.

If a server implementation has no such housekeeping considerations, check() is equivalent to NOOP.

• @returns: bool

.close()

Permanently removes all messages that have the \Deleted flag set from the currently selected mailbox, and returns to the authenticated state from the selected state.

No messages are removed, and no error is given, if the mailbox is selected by an examine() or is otherwise selected read-only.

• @returns: bool

.expunge(path)

Clears the deleted messages in a mailbox folder and returns true on success or false otherwise.

• @params:
  • string path

• @returns: bool

.search(query, folder)

Finds all occurrences of the query in the specified folder and return a list of message UIDs that matches the search query.

The query can contain a message sequence set and a number of search criteria keywords including flags such as ANSWERED, DELETED, DRAFT, FLAGGED, NEW, RECENT and SEEN. For more information about the search criteria please see RFC-3501 section 6.4.4 for more details.

When query is empty, it defaults to NEW. folder defaults to INBOX when empty.

@see: https://datatracker.ietf.org/doc/html/rfc9051#section-6.4.4 for more.

• @params:
  • string? query
  • string? folder

.fetch(uid, path)

Retrieves a message with the give uid in the specified mailbox path. If the uid is not given, it attempts to retrieve the message with a UID of 1. If path is not given, it will attempt to retrieve the message from the INBOX folder.

• @params:
  • number? uid
  • string? path

.copy(id, destination, path)

Copies the specified message(s) to the end of the specified destination mailbox.

@notes:

• COPYUID responses are not yet supported

• @returns: bool

.store(id, command, flags)

Alters data associated with a message in the mailbox.

suffix of .SILENT. @see https://datatracker.ietf.org/doc/html/rfc9051#section-6.4.6 for more.

@notes:

• command must be one of FLAGS, +FLAGS, or -FLAGS, optionally with a

• @returns: bool

.quit()

Closes the current IMAP session and disposes all associated network handles.

.get_handle()

Returns the raw handle to the underlying networking (curl) client.

class Message

Message class can be used to construct an email message.

The class has several methods that can be used to set various properties of the email message.

.Message() ➝ Constructor

mail.Message constructor

.from(from)

Set the sender of the email message.

• @params:
  • string from

• @returns: self

.to(to)

Add one or more recipients to the email message.

• @params:
  • string|list[string] to

• @returns: self

.cc(cc)

Add one or more Cc recipients to the email message.

• @params:
  • string|list[string] cc

• @returns: self

.bcc(bcc)

Add one or more Bcc recipients to the email message.

• @params:
  • string|list[string] bcc

• @returns: self

.reply_to(to)

Add a reply-to address to the email message.

• @params:
  • string to

• @returns: self

.subject(subject)

Set the subject of the email message.

• @params:
  • string subject

• @returns: self

.header(header)

Add one or more headers to the email message.

• @params:
  • string|list|dict header

• @returns: self

.attachment(path, name)

Add one or more attachments to the email message.

• @params:
  • string path
  • string name (Optional)

• @returns: self

.text(text)

Set the plain text body of the email message.

• @params:
  • string text

• @returns: self

.html(html)

Set the html body of the email.

• @params:
  • string html

• @returns: self