Mailmerge with Microsoft OAuth authentication

mailmerge is a command line mail merge tool that supports the powerful jinja2 template engine for generating email content.

An example from the docs:

TO: {{email}}
SUBJECT: Testing mailmerge
FROM: My Self <myself@mydomain.com>
BCC: myself@mydomain.com

Hi, {{name}},

Your number is {{number}}.

This post explains how to send emails with mailmerge from a Microsoft email account, where password-based authentication is disabled. Instead, authentication uses OAuth, support for which I added to mailmerge in July 2023.

The workflow below uses oauth2ms to create an OAuth token, which you then pass to the mailmerge command. The workflow assumes you have or your IT administrator has permission to create a Microsoft Azure AD application.

You will need to complete two steps first:

1. Install mailmerge by following these instructions.

2. Set up an Azure app and configure oauth2ms.

Create an Azure app and configure oauth2ms

Follow the "Azure app setup" and "config.json configuration" sections from this guide to configure oauth2ms for obtaining an OAuth token from a Microsoft identity endpoint. When creating the Azure app, keep a note of the application's client ID and client secret for your config.json file. This file should be at location $XDG_CONFIG_HOME/oauth2ms/config.json, which for me is ~/.config/oauth2ms/config.json.

When testing this, it should ask you for your Microsoft login:

After creating the config file, execute oauth2ms, it should pop up a browser window asking you to login. Once logged it, it should redirect you to a page which says “Authorization complete.”.

After this first time, the oauth2ms executable will return an OAuth token to standard output.

Subsequent fetches should use the refresh token to get the access token.

Once you have oauth2ms working (i.e. it prints your OAuth token to the terminal window), move onto the steps below.

Steps for running mailmerge with OAuth

Step 1: Set up mailmerge

Run:

mailmerge --sample

then follow these instructions to edit the generated mailmerge_template.txt and mailmerge_database.csv files.

You then need to edit the mailmerge_server.conf file to tell mailmerge to use XOAUTH. You need to specify your username and your organisation's domain name for username:

[smtp_server]
host = smtp.office365.com
port = 587
security = XOAUTH
username = YOURUSERNAME@YOURDOMAIN.COM

Step 2: Create an OAuth token

Run oauth2ms, which should return an OAuth token to the terminal window. Copy this token.

Step 3: Run mailmerge

Follow the mailmerge README to understand how to enable/disable dry runs and sending limits.

Once you are happy with the instantiated mail merge templates with --dry-run, run mailmerge to send emails to all recipients:

mailmerge --no-dry-run --no-limit

you will be asked for a password:

>>> password for YOURUSERNAME@YOURDOMAIN.COM on smtp.office365.com:

Paste the OAuth token from step 2 (from oauth2ms) into the terminal window, and hit Enter. This should now send emails to recipients listed in your mailmerge_database.csv file.