Mailbox

Mailbox groups the functionality of both the messages and the email folders.

These are the scopes needed to work with the MailBox and Message classes.

Raw Scope	Included in Scope Helper	Description
Mail.Read	mailbox	To only read my mailbox
Mail.Read.Shared	mailbox_shared	To only read another user / shared mailboxes
Mail.Send	message_send, message_all	To only send message
Mail.Send.Shared	message_send_shared, message_all_shared	To only send message as another user / shared mailbox
Mail.ReadWrite	message_all	To read and save messages in my mailbox
MailboxSettings.ReadWrite	mailbox_settings	To read and write user mailbox settings

Mailbox and Messages

mailbox = account.mailbox()

inbox = mailbox.inbox_folder()

for message in inbox.get_messages():
    print(message)

sent_folder = mailbox.sent_folder()

for message in sent_folder.get_messages():
    print(message)

m = mailbox.new_message()

m.to.add('to_example@example.com')
m.body = 'George Best quote: In 1969 I gave up women and alcohol - it was the worst 20 minutes of my life.'
m.save_draft()

Email Folder

Represents a Folder within your email mailbox.

You can get any folder in your mailbox by requesting child folders or filtering by name.

mailbox = account.mailbox()

archive = mailbox.get_folder(folder_name='archive')  # get a folder with 'archive' name

child_folders = archive.get_folders(25) # get at most 25 child folders of 'archive' folder

for folder in child_folders:
    print(folder.name, folder.parent_id)

new_folder = archive.create_child_folder('George Best Quotes')

Message

An email object with all its data and methods

Creating a draft message is as easy as this:

message = mailbox.new_message()
message.to.add(['example1@example.com', 'example2@example.com'])
message.sender.address = 'my_shared_account@example.com'  # changing the from address
message.body = 'George Best quote: I might go to Alcoholics Anonymous, but I think it would be difficult for me to remain anonymous'
message.attachments.add('george_best_quotes.txt')
message.save_draft()  # save the message on the cloud as a draft in the drafts folder

Working with saved emails is also easy

query = mailbox.new_query().on_attribute('subject').contains('george best')  # see Query object in Utils
messages = mailbox.get_messages(limit=25, query=query)

message = messages[0]  # get the first one

message.mark_as_read()
reply_msg = message.reply()

if 'example@example.com' in reply_msg.to:  # magic methods implemented
    reply_msg.body = 'George Best quote: I spent a lot of money on booze, birds and fast cars. The rest I just squandered.'
else:
    reply_msg.body = 'George Best quote: I used to go missing a lot... Miss Canada, Miss United Kingdom, Miss World.'

reply_msg.send()

Sending Inline Images

You can send inline images by doing this:

# ...
msg = account.new_message()
msg.to.add('george@best.com')
msg.attachments.add('my_image.png')
att = msg.attachments[0]  # get the attachment object

# this is super important for this to work.
att.is_inline = True
att.content_id = 'image.png'

# notice we insert an image tag with source to: "cid:{content_id}"
body = """
    <html>
        <body>
            <strong>There should be an image here:</strong>
            <p>
                <img src="cid:image.png">
            </p>
        </body>
    </html>
    """
msg.body = body
msg.send()

Retrieving Message Headers

You can retrieve message headers by doing this:

# ...
mb = account.mailbox()
msg = mb.get_message(query=mb.q().select('internet_message_headers'))
print(msg.message_headers)  # returns a list of dicts.

Note that only message headers and other properties added to the select statement will be present.

Saving as EML

Messages and attached messages can be saved as *.eml.

Save message as “eml”:

msg.save_as_eml(to_path=Path('my_saved_email.eml'))

Save attached message as “eml”

Careful: there’s no way to identify that an attachment is in fact a message. You can only check if the attachment.attachment_type == ‘item’. if is of type “item” then it can be a message (or an event, etc…). You will have to determine this yourself.

msg_attachment = msg.attachments[0]  # the first attachment is attachment.attachment_type == 'item' and I know it's a message.
msg.attachments.save_as_eml(msg_attachment, to_path=Path('my_saved_email.eml'))

Mailbox Settings

The mailbox settings and associated methods.

Retrieve and update mailbox auto reply settings:

from O365.mailbox import AutoReplyStatus, ExternalAudience

mailboxsettings = mailbox.get_settings()
ars = mailboxsettings.automaticrepliessettings

ars.scheduled_startdatetime = start # Sets the start date/time
ars.scheduled_enddatetime = end # Sets the end date/time
ars.status = AutoReplyStatus.SCHEDULED # DISABLED/SCHEDULED/ALWAYSENABLED - Uses start/end date/time if scheduled.
ars.external_audience = ExternalAudience.NONE # NONE/CONTACTSONLY/ALL
ars.internal_reply_message = "ARS Internal" # Internal message
ars.external_reply_message = "ARS External" # External message
mailboxsettings.save()
Alternatively to enable and disable

mailboxsettings.save()

mailbox.set_automatic_reply(
    "Internal",
    "External",
    scheduled_start_date_time=start, # Status will be 'scheduled' if start/end supplied, otherwise 'alwaysEnabled'
    scheduled_end_date_time=end,
    externalAudience=ExternalAudience.NONE, # Defaults to ALL
)
mailbox.set_disable_reply()

Outlook Categories

You can retrieve, update, create and delete outlook categories. These categories can be used to categorize Messages, Events and Contacts.

These are the scopes needed to work with the SharePoint and Site classes.

Raw Scope	Included in Scope Helper	Description
MailboxSettings.Read	—	To only read outlook settings
MailboxSettings.ReadWrite	mailbox_settings	To read and write outlook settings

Example:

from O365.category import CategoryColor

oc = account.outlook_categories()
categories = oc.get_categories()
for category in categories:
    print(category.name, category.color)

my_category = oc.create_category('Important Category', color=CategoryColor.RED)
my_category.update_color(CategoryColor.DARKGREEN)

my_category.delete()  # oops!