Class Documentation

Mailbox

class django_mailbox.models.Mailbox(id, name, uri, from_email, active, last_polling)[source]
Parameters:
  • id (AutoField) – Id
  • name (CharField) – Name
  • uri (CharField) – Example: imap+ssl://myusername:mypassword@someserver Internet transports include ‘imap’ and ‘pop3’; common local file transports include ‘maildir’, ‘mbox’, and less commonly ‘babyl’, ‘mh’, and ‘mmdf’. Be sure to urlencode your username and password should they contain illegal characters (like @, :, etc).
  • from_email (CharField) – Example: MailBot <mailbot@yourdomain.com>’From’ header to set for outgoing email.If you do not use this e-mail inbox for outgoing mail, this setting is unnecessary.If you send e-mail without setting this, your ‘From’ header will’be set to match the setting DEFAULT_FROM_EMAIL.
  • active (BooleanField) – Check this e-mail inbox for new e-mail messages during polling cycles. This checkbox does not have an effect upon whether mail is collected here when this mailbox receives mail from a pipe, and does not affect whether e-mail messages can be dispatched from this mailbox.
  • last_polling (DateTimeField) – The time of last successful polling for messages.It is blank for new mailboxes and is not set for mailboxes that only receive messages via a pipe.
exception DoesNotExist
exception MultipleObjectsReturned
active

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

active_mailboxes = <django_mailbox.models.ActiveMailboxManager object>
archive

Returns (if specified) the folder to archive messages to.

folder

Returns (if specified) the folder to fetch mail from.

from_email

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

get_connection()[source]

Returns the transport instance for this mailbox.

These will always be instances of django_mailbox.transports.base.EmailTransport.

get_new_mail(condition=None)[source]

Connect to this transport and fetch new messages.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

last_polling

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

location

Returns the location (domain and path) of messages.

messages

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django_mailbox.models.MailboxManager object>
password

Returns the password to use for fetching messages.

port

Returns the port to use for fetching messages.

process_incoming_message(message)[source]

Process a message incoming to this mailbox.

record_outgoing_message(message)[source]

Record an outgoing message associated with this mailbox.

type

Returns the ‘transport’ name for this mailbox.

uri

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

use_ssl

Returns whether or not this mailbox’s connection uses SSL.

use_tls

Returns whether or not this mailbox’s connection uses STARTTLS.

username

Returns the username to use for fetching messages.

Message

class django_mailbox.models.Message(id, mailbox, subject, message_id, in_reply_to, from_header, to_header, outgoing, body, encoded, processed, read, eml)[source]
Parameters:
  • id (AutoField) – Id
  • mailbox_id (ForeignKey to Mailbox) – Mailbox
  • subject (CharField) – Subject
  • message_id (CharField) – Message id
  • in_reply_to_id (ForeignKey to Message) – In reply to
  • from_header (CharField) – From header
  • to_header (TextField) – To header
  • outgoing (BooleanField) – Outgoing
  • body (TextField) – Body
  • encoded (BooleanField) – True if the e-mail body is Base64 encoded
  • processed (DateTimeField) – Processed
  • read (DateTimeField) – Read
  • eml (FileField) – Original full content of message
exception DoesNotExist
exception MultipleObjectsReturned
address

Property allowing one to get the relevant address(es).

In earlier versions of this library, the model had an address field storing the e-mail address from which a message was received. During later refactorings, it became clear that perhaps storing sent messages would also be useful, so the address field was replaced with two separate fields.

attachments

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

body

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

delete(*args, **kwargs)[source]

Delete this message and all stored attachments.

eml

The descriptor for the file attribute on the model instance. Return a FieldFile when accessed so you can write code like:

>>> from myapp.models import MyModel
>>> instance = MyModel.objects.get(pk=1)
>>> instance.file.size

Assign a file object on assignment so you can do:

>>> with open('/path/to/hello.world') as f:
...     instance.file = File(f)
encoded

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

from_address

Returns the address (as a list) from which this message was received

Note

This was once (and probably should be) a string rather than a list, but in a pull request received long, long ago it was changed; presumably to make the interface identical to that of to_addresses.

from_header

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

get_body()[source]

Returns the body field of this record.

This will automatically base64-decode the message contents if they are encoded as such.

get_email_object()[source]

Returns an email.message.EmailMessage instance representing the contents of this message and all attachments.

See [email.message.EmailMessage] for more information as to what methods and properties are available on email.message.EmailMessage instances.

Note

Depending upon the storage methods in use (specifically – whether DJANGO_MAILBOX_STORE_ORIGINAL_MESSAGE is set to True, this may either create a “rehydrated” message using stored attachments, or read the message contents stored on-disk.

[email.message.EmailMessage]Python’s email.message.EmailMessage docs (https://docs.python.org/3/library/email.message.html)
get_next_by_processed(*, field=<django.db.models.fields.DateTimeField: processed>, is_next=True, **kwargs)
get_previous_by_processed(*, field=<django.db.models.fields.DateTimeField: processed>, is_next=False, **kwargs)
html

Returns the message body matching content type ‘text/html’.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

in_reply_to

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

in_reply_to_id
incoming_messages = <django_mailbox.models.IncomingMessageManager object>
mailbox

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

mailbox_id
message_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>
outgoing

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

outgoing_messages = <django_mailbox.models.OutgoingMessageManager object>
processed

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

read

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

replies

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

reply(message)[source]

Sends a message as a reply to this message instance.

Although Django’s e-mail processing will set both Message-ID and Date upon generating the e-mail message, we will not be able to retrieve that information through normal channels, so we must pre-set it.

set_body(body)[source]

Set the body field of this record.

This will automatically base64-encode the message contents to circumvent a limitation in earlier versions of Django in which no fields existed for storing arbitrary bytes.

subject

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

text

Returns the message body matching content type ‘text/plain’.

to_addresses

Returns a list of addresses to which this message was sent.

to_header

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

unread_messages = <django_mailbox.models.UnreadMessageManager object>

Message Attachment

class django_mailbox.models.MessageAttachment(id, message, headers, document)[source]
Parameters:
  • id (AutoField) – Id
  • message_id (ForeignKey to Message) – Message
  • headers (TextField) – Headers
  • document (FileField) – Document
exception DoesNotExist
exception MultipleObjectsReturned
delete(*args, **kwargs)[source]

Deletes the attachment.

document

The descriptor for the file attribute on the model instance. Return a FieldFile when accessed so you can write code like:

>>> from myapp.models import MyModel
>>> instance = MyModel.objects.get(pk=1)
>>> instance.file.size

Assign a file object on assignment so you can do:

>>> with open('/path/to/hello.world') as f:
...     instance.file = File(f)
get_filename()[source]

Returns the original filename of this attachment.

headers

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

items()[source]
message

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

message_id
objects = <django.db.models.manager.Manager object>