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.
Centre for Advanced Research Computing, University College London (arc.collaborations@ucl.ac.uk)
- 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.
- store the necessary credentials in a
.envrcfile
The credentials should be stored in a .envrc file in the root directory of the project. The file should container the following information:
# 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 fordirenvto export the environment variablesCLIENT_ID: ID of the app created in AzureCLIENT_SECRET: secret used by the app to authenticate to the email serverTENANT_ID: ID of the organisation in AzureACCOUNT: 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 senderAUTHOR: emails address to send email from. Can be different toACCOUNTif, for example, sending from a shared mailboxSCOPE: scope of the account (e.g. https://outlook.office365.com/.default)SERVER: server forexchanglibconfiguration (e.g. outlook.office365.com)
- [recommended] install and configure
direnvto automatically export the credentials as environment variables
Install direnv and then grant it permission to load your .envrc file:
direnv allow .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
python -m pip install git+https://github.com/UCL-MIRSG/azure-mail.gitAlternatively create a local clone of the repository with
git clone https://github.com/UCL-MIRSG/azure-mail.gitand then install in editable mode by running
python -m pip install -e .import azure_mail
# Create a meeting invite to send as an attachment in your email
attachments = azure_mail.create_calendar_ics(
subject="Meeting",
description="Very important all-day meeting",
date="January 1, 1970",
start_hour=9,
start_minute=0,
duration_hours=8,
duration_minutes=0,
timezone="Europe/London",
)
message = azure_mail.create_email(
recipients={'person1@mail.com', 'someone-else@mail.com'},
body=exchangelib.HTMLBody(
"<html><body>Hello, there's a meeting invite attached</body></html>",
),
subject='Meeting invite',
attachments=attachments,
)
# Save email in Drafts folder
message.save()
# Send email to recipients
message.send()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.
Tests can be run across all compatible Python versions in isolated environments
using tox by running
toxTo run tests manually in a Python environment with pytest installed run
pytest testsagain from the root of the repository.
The MkDocs HTML documentation can be built locally by running
tox -e docsfrom 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
mkdocs serve