Azure Mail

A Python package for sending emails in Office 365 via an Azure app

This project is developed in collaboration with the Centre for Advanced Research Computing, University College London.

About

Project Team

MIRSG

Research Software Engineering Contact

Centre for Advanced Research Computing, University College London (arc.collaborations@ucl.ac.uk)

Getting Started

Pre-requisites

1. create an app in Azure for sending emails

Before using azure-mail, you will need to create an app in Azure with the necessary permissions to send emails on behalf of a user. For example, EWS.AccessAsUser.All Delegated permission within Office 365 Exchange Online scope should allow emails to be sent. This permission is described as "Access mailboxes as the signed-in user via Exchange Web Services" in the Azure portal.

1. store the necessary credentials in a .envrc file

The credentials should be stored in a .envrc file in the root directory of the project. The file should container the following information:

shell # layout python export CLIENT_ID= export CLIENT_SECRET= export TENANT_ID= export ACCOUNT= export USERNAME= export USER_PASSWORD= export AUTHOR= export SCOPE= export SERVER=

Here's a brief explanation of each line above: - layout python: required for direnv to export the environment variables - CLIENT_ID: ID of the app created in Azure - CLIENT_SECRET: secret used by the app to authenticate to the email server - TENANT_ID: ID of the organisation in Azure - ACCOUNT : account to send emails from (e.g. abcdef@ucl.ac.uk) - USERNAME: username of sender (if at UCL, your UCL ID e.g. abcdefg) - USER_PASSWORD: password of sender - AUTHOR: emails address to send email from. Can be different to ACCOUNT if, for example, sending from a shared mailbox - SCOPE: scope of the account (e.g. https://outlook.office365.com/.default) - SERVER: server for exchanglib configuration (e.g. outlook.office365.com)

1. [recommended] install and configure direnv to automatically export the credentials as environment variables

Install direnv and then grant it permission to load your .envrc file:

bash direnv allow .

Installation

We recommend installing in a project specific virtual environment created using a environment management tool such as Conda. To install the latest development version of azure-mail using pip in the currently active environment run

sh python -m pip install git+https://github.com/UCL-MIRSG/azure-mail.git

Alternatively create a local clone of the repository with

sh git clone https://github.com/UCL-MIRSG/azure-mail.git

and then install in editable mode by running

sh python -m pip install -e .

Usage Example

```python import azure_mail

Create a meeting invite to send as an attachment in your email

attachments = azuremail.createcalendarics( subject="Meeting", description="Very important all-day meeting", date="January 1, 1970", starthour=9, startminute=0, durationhours=8, duration_minutes=0, timezone="Europe/London", )

message = azuremail.createemail( recipients={'person1@mail.com', 'someone-else@mail.com'}, body=exchangelib.HTMLBody( "Hello, there's a meeting invite attached", ), subject='Meeting invite', attachments=attachments, )

Save email in Drafts folder

message.save()

Send email to recipients

message.send() ```

Overview

The ClientApplication from python msal library is used to connect to an app installed in Microsoft Azure with the relevant permissions. An access token is acquired through acquire_token_by_username_password firstly and then the access token is cached so acquire_token_silent to be used in future uses of this package. This provides the necessary credentials and configuration to access the UCL account from which the emails are sent.

Running Tests

Tests can be run across all compatible Python versions in isolated environments using tox by running

sh tox

To run tests manually in a Python environment with pytest installed run

sh pytest tests

again from the root of the repository.

Building Documentation

The MkDocs HTML documentation can be built locally by running

sh tox -e docs

from the root of the repository. The built documentation will be written to site.

Alternatively to build and preview the documentation locally, in a Python environment with the optional docs dependencies installed, run

sh mkdocs serve