Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (testpypi.python.org).
Help us improve Python packaging - Donate today!

A Python module for connecting to the Outlook REST API, without the hassle of dealing with the JSON formatting for requests/responses and the REST endpoints and their varying requirements

Project Description
|PyPI version| |Code Health| |coverage report|

|PyPI| |PyPI| |Documentation Status|

Maintained on GitLab
====================

This project is maintained on
`GitLab <https://gitlab.com/jensastrup/pyOutlook>`__ and mirrored to
`GitHub <https://github.com/JensAstrup/pyOutlook>`__. Issues opened on
the latter are still addressed.

pyOutlook
=========

A Python module for connecting to the Outlook REST API, without the
hassle of dealing with the JSON formatting for requests/responses and
the REST endpoints and their varying requirements

The most up to date documentation can be found on `pyOutlook's pypi docs
page <http://pythonhosted.org/pyOutlook>`__.

Instantiation
-------------

Before anything can be retrieved or sent, an instance of OutlookAccount
must be created. The only parameter required is the access token for the
account.

Note that this module does not handle the OAuth process, gaining an
access token must be done outside of this module.

.. code:: python

from pyOutlook import *

token = 'OAuth Access Token Here'
my_account = OutlookAccount(token)

# If our token is refreshed, or to ensure that the latest token is saved prior to calling a method.
my_account.access_token = 'new access token'

Retrieving Messages
-------------------

get\_messages()
~~~~~~~~~~~~~~~

This method retrieves the five most recent emails, returning a list of
Message objects. You can optionally specify the page of results to
retrieve - 1 is the default.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')
account.get_messages()
account.get_messages(2)

get\_message(message\_id)
~~~~~~~~~~~~~~~~~~~~~~~~~

This method retrieves the information for the message matching the id
provided

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

email = account.get_message('message_id')
print(email.body)

inbox()
~~~~~~~

This method is identical to get\_messages(), however it returns only the
ten most recent message in the inbox (ignoring messages that were put
into seperate folders by an Outlook rule, junk email, etc)

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

account.inbox()

Identical methods for additional folders: ``sent_messages()``,
``deleted_messages()``, ``draft_messages()``.

Interacting with Message objects
--------------------------------

Message objects deal with the JSON returned by Outlook, and provide only
the useful details. These Messages can be forwarded, replied to,
deleted, etc.

forward(to\_recipients, forward\_comment)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This method forwards a message to the list of recipients, along with an
optional 'comment' which is sent along with the message. The
forward\_comment parameter can be left blank to just forward the
message.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

email = account.get_message('id')
email.forward([Contact('John.Adams@domain.com'), Contact('Nice.Guy@domain.com')])
email.forward(['John.Smith@domain.com'], 'Read the message below')

reply(reply\_comment)
~~~~~~~~~~~~~~~~~~~~~

This method allows you to respond to the sender of an email with a
comment appended.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

email = account.get_message(id)
email.reply('That was a nice email Lisa')

reply\_all(reply\_comment)
~~~~~~~~~~~~~~~~~~~~~~~~~~

This method allows you to respond to all recipients an email with a
comment appended.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

email = account.get_message(id)
email.reply_all('I am replying to everyone, which will likely annoy 9/10 of those who receive this')

move\_to\* You can move a message from one folder to another via several methods. For default folders, there are specific methods - for everything else there is a method to move to a folder designated by its id - or you can pass a ``Folder`` instance.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

message = Message()

message.move_to_inbox()
message.move_to_deleted()
message.move_to_drafts()
message.move_to('my_folder_id')

folders = account.get_folders()

message.move_to(folders[0])

delete()
~~~~~~~~

Deletes the email. Note that the email will still exist in the user's
'Deleted Items' folder.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

message = account.inbox()[0]

message.delete()

Sending Emails
--------------

There are a couple of ways to create new emails. You can either use
``new_email()`` to get a ``Message()`` instance, which you can alter
before sending. Alternatively, you can use ``send_email()`` where you
pass in commonly used parameters and the email gets sent once called.

Example:

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

test_email = account.new_email('This is a test body. <br> Best, <br> John Smith', 'This is a test subject', [Contact('anEmailAccount@gmail.com')])
test_email.attach('FILE_BYTES_HERE', 'FileName.pdf')
test_email.send()

Or:

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

account.send_email(
"I'm sending an email through Python. <br> Best, <br> Me",
'A subject',
to=['myemail@domain.com'],
# or to=[Contact('myemail@domain.com']
)

Folders
-------

Folders can be created, retrieved, moved, copied, renamed, and deleted.
You can also retrieve child folders that are nested within another
folder. All Folder objects contain the folder ID, the folder name, the
folder's unread count, the number of child folders within it, and the
total items inside the folder.

'Well Known' Folders
~~~~~~~~~~~~~~~~~~~~

Folder ID parameters can be replaced with the following strings where
indicated: 'Inbox', 'Drafts', 'SentItems', or 'DeletedItems'

get\_folders()
~~~~~~~~~~~~~~

This methods returns a list of Folder objects representing each folder
in the user's account.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folders()[0]
print(folder.name)
>>> 'Inbox'

get\_folder\_by\_id(folder\_id)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have the id of a folder, you can get a Folder object for it with
this method

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folder_by_id('id')
print(folder.name)
>>> 'My Folder'

Note that you can replace the folder ID parameter with the name of a
'well known' folder such as: 'Inbox', 'Drafts', SentItems', and
'DeletedItems'

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folder_by_id('Drafts')
print(folder.name)
>>> 'Drafts'

The Folder Object
-----------------

rename(new\_folder\_name)
~~~~~~~~~~~~~~~~~~~~~~~~~

This method renames the folder object in Outlook, and returns a new
Folder object representing that folder.

::

from pyOutlook import *
account = OutlookAccount('')

folder = my_account.get_folders()[0]
folder = folder.rename('My New Folder v2')
folder.name
>>> 'My New Folder v2'

get\_subfolders()
~~~~~~~~~~~~~~~~~

Returns a list of Folder objects, representing all child Folders within
the Folder provided.

.. code:: python

for subfolder in folder.get_subfolders():
print(subfolder.name)

>>> 'My New Folder v2'
>>> 'Some Other Folder'

delete()
~~~~~~~~

Self-explanatory, deletes the provided folder in Outlook

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folders()[0]
folder.delete()
# and now it doesn't exist

move\_into(destination\_folder)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Move the Folder provided into a new folder.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folders()[0]
folder_1 = account.get_folders()[1]

folder.move_into(folder_1)

copy(destination\_folder)
~~~~~~~~~~~~~~~~~~~~~~~~~

Copies the folder and its contents to the designated folder which can be
either a folder ID or well known folder name.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folders()[0]
folder_1 = account.get_folders()[1]

folder.copy_into(folder_1)

create\_child\_folder(new\_folder\_name)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This creates a `folder within a
folder <http://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2014/03/1394332737Go-Deeper-Inception-Movie.jpg>`__,
with a title provided in the ``new_folder_name`` argument.

.. code:: python

from pyOutlook import *
account = OutlookAccount('')

folder = account.get_folders()[0]
new_folder = folder.create_child_folder('New Folder')
new_folder.unread_count
>>> 0

.. |PyPI version| image:: https://badge.fury.io/py/pyOutlook.svg
:target: https://badge.fury.io/py/pyOutlook
.. |Code Health| image:: https://landscape.io/github/JensAstrup/pyOutlook/master/landscape.svg?style=flat
:target: https://landscape.io/github/JensAstrup/pyOutlook/master
.. |coverage report| image:: https://gitlab.com/jensastrup/pyOutlook/badges/master/coverage.svg
:target: https://gitlab.com/jensastrup/pyOutlook/commits/master
.. |PyPI| image:: https://img.shields.io/pypi/status/pyOutlook.svg?maxAge=2592000
:target:
.. |PyPI| image:: https://img.shields.io/pypi/pyversions/pyOutlook.svg?maxAge=2592000
:target:
.. |Documentation Status| image:: https://readthedocs.org/projects/pyoutlook/badge/?version=latest
:target: http://pyoutlook.readthedocs.io/en/latest/?badge=latest


Release History

Release History

This version
History Node

4.0.0

History Node

4.0.0a4

History Node

4.0.0a3

History Node

4.0.0a2

History Node

4.0.0a1

History Node

0.1.0a0

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pyOutlook-4.0.0-py3-none-any.whl (18.7 kB) Copy SHA256 Checksum SHA256 py3 Wheel Jul 28, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting