YouGotMail – build digital co-workers in MS Outlook

• 🤖 easy-to-use library for retrieving and sending emails with MS Outlook's API
• 🤖 AI tools to automate retrieval and sending of emails
• 📨 walkthrough + tools to build digital co-workers: spin up an AI agent running an inbox inside AWS Lambda

• 🐍 Python
• 🧠 OpenAI
• 📧 MS Outlook API
• 🗄️ MongoDB
• ☁️ AWS

• 📬 over 1/3rd of hours spent in every job is email-based
• 📧 buidling digital co-workers requires building digital email-users
• ✨ AI + Email = 🔥

• status: all methods listed below are (or should be) working. However I haven't had time to unit test them and write proper error handling. The docs below outline which methods have been tested and which haven't. I will be updating the version and status over the upcoming weeks
• current version: 0.0.12
• last update: 2025-07-08

You will first need to set-up MS email credentials for your inbox. See Getting MS credentials and setting up your inbox for instructions. If you have those credentials, you can run the code below.

• 📖 Introduction
• 🔑 Getting MS credentials and setting up your inbox
  • Step 1: Login to Microsoft Entra
  • Step 2: Go into Applications & Retrieve the Tenant Id
  • Step 3: Under Applications, go into App registrations
  • Step 4: Retrieve the client_id
  • Step 5: Create a new secret
  • Step 6: Grant your app permissions to the email API
  • Step 7: Run Quickstart code
• 🤖 Quickstart #2: Structured Outputs from emails with OpenAI
• 📤 Quickstart #3: Sending emails
• 📨 Retrieving Emails
  • Retrieving Emails
  • Retrieving Conversations
• 📤 Sending Emails
  • Send emails
• 📧 Email Operations
  • Send emails
  • Reply to emails
• 🗄️ Storage
  • Note on dependencies needed for storage
  • Local deployment example

Microsoft Outlook is one of the most popular email clients among enterprises and business users. In some roles - handling email is almost the entire job. People receive emails, extract data from them, pass that data to other systems, retrieve data from those systems and send it via email. And so it goes.

Hence, building AI solutions that can

Furthermore, emails are a natural communication method that humans know and use daily. Creating AI Agents that can live in an email environment offers a natural way of interacting with AI systems. For example an AI CC'd into a conversation could easily perform tasks that the parties of the email thread want handled.

Building integrations into MS Outlook is particularly painful. because (as all things Microsoft) the API has many rules that make it time-consuming to build anything.

This library is meant to facilitate that. At the same time it will offer 3 types of AI solutions:

• a set of AI helper functions meant to facilite the work with email retrieval and email sending (e.g. structured outputs from emails)
• an AI Agent that lives in your inbox and handles email work for you
• an AI agent that acts as a standalone inbox operatord can be used as an AI interface

The goal is to provide:

• easy way to build an AI agent working on actual emails (ie. your personal inbox)
• easily spin up Outlook native agents with a few pre-defined instructions from users: turn an email address into a logistics dispatcher, a lawyer, a contract manager, a customer support specialist or more

To initialize the YouGotMail class to work with your Outlook inbox we need to do 3 things:

1. Create a new "app" in Azure Entra
2. Grant this app permissions to access the various MS email APIs (read, draft, send)
3. Retrieve 3 unique ids that will be used to authenticate access to the inbox:
   • client_id
   • client_secret
   • tenant_id

You can use your normal MS login. Ideally you should be the admin user in your org. If not that's ok, you will need to ask the admin to authorize the authorization.

Once logged in, you can go into Applications. In the main Applications Dashboard you should see the tenant id for your org. You can copy it from here and store it.

Click on "New registration" to create a new app.

You can select "Accounts in this organizational directory only (Your Organization Name only - Single tenant)"

Once created, you can grab the "Application (client) ID" from the application's dashboard. This is our "client_id".

Almost there - 2 down - 1 to go!

In the sidebar of the application (not your Entra sidebar) you have "Certificates & secrets". In there you can click on "New client secret". You can leave the Description blank.A new secret will be created - you can copy the id in the "Value" columne (NOT one in the "Secret ID" - thanks Microsoft for this create UX!). You have now your "client_secret" that we will use to instatiate the YouGotEmail class. Success!

Note: the secret will expire after 6 months. The date is shown in the Expires column. Make a note of it and set-up some calendar reminders.

The final thing we need to do is grant your app permissions to the email API. From the app's sidebar click on "API permissions". Then "Add a permission". Select MS Graph.

Select "Application permissions".

Chose "Application permissions".

From the list of API permissions select all related to email. You can type "Mail" in the search bar. Including MailboxFolder, MailboxItem, Mailbox Settings, Mail, User-Mail.

Finally, each permission requires Admin access. If you're the Admin you can click on the button at the top of the permissions table. If you're not, you need to send a request to your admin. Click on "Grant admin consent for ".

You can now run the Quickstart code by passing your credentials to the YouGotMail class.

You can pass your OpenAI API key to the YouGotMail class and call the ai_get_emails_with_structured_output() method to retrieve emails from MS Outlook and have OpenAI structured output from the email body. You will need to pass a schema of the info you want extracted from the email body.

The AI features rely on OpenAI. The OpenAI SDK is listed in dependencies as optional. In order to run ygm with OpenAI you will need to install it first:

Then run the code below:

The get_emails() method allows to retrieve emails from your inbox using multiple filters.

This query should return a list of emails that looks like this for each inbox query:

In case of multiple inboxes, the query will return a list of inboxes with the emails found in each inbox.

⚠️ This method is not fully tested yet.

Conversations in MS Outlook are a collection of emails that are related to a single topic. Think all emails in a thread.

If you already retrieve emails, you can use the conversation_id for the given email to retrieve the conversation containing that email.

The retrieved conversation should look like this:

You can also retrieve that conversation by using other filters such as date, subject, sender, etc. Unlike the retrieve emails query, the conversation query is meant to find only 1 conversation in 1 inbox. So it accepts strings instead of lists.

For sending emails the library offers 3 methods:

• send_email() - sends a new email to specific recipients
• draft_email() - drafts an email to the recipients (stored in draft folder)
• reply_to_email() - replies to an email (stored in sent folder)

⚠️ This method is not fully tested yet.

The get_emails() and get_conversation() methods have a storage parameter that allows to store the emails in a MongoDB database and/or in an AWS S3 bucket. These are pre-configured MongoDB and AWS S3 workflows that allow you to store the emails in a MongoDB database and/or in an AWS S3 bucket.

Using storage requires the following 2 dependencies:

• pymongo (for MongoDB)
• boto3 (for AWS)

Those are optional and do not install by default when running pip install yougotmail.

The code currently handles 3 deployment scenarios which affect the needed dependencies:

• no storage: no extra dependencies required (pip install yougotmail and use storage=None)
• local deployment with storage: you will need both pymongo and boto3 installed (pip install "yougotmail[pymongo]" and pip install "yougotmail[boto3]" and use storage="emails" or storage="emails_and_attachments")
• AWS Lambda deployment with storage: you will need to install pymongo but not boto3 as it comes pre-installed in AWS Lambda environments (pip install "yougotmail[pymongo]" and use storage="emails" or storage="emails_and_attachments")

Install dependencies:

Initiate YouGotMailclass with appropriate variables:

Run the get_emails() or get_conversation() method with storage enabled.

storage="emails" will store only emails in the MongoDB database and nothing in the S3 bucket. storage="emails_and_attachments" will store emails in the MongoDB database and attachments in the S3 bucket.

MS Graph offers the possiblity to create webhook sending a notification to your specificied URL whenever a new email is received. You Got Mail offers 4 methods to create and manage those webhooks.

• create_microsoft_graph_webhook() - creates a new webhook
• get_active_subscriptions_for_inbox() - gets all active webhooks for an inbox
• renew_subscriptions() - renews all active webhooks for an inbox
• delete_subscription() - deletes a webhook

Microsoft Graph allows you to subscribe to changes in a mailbox (like receiving new emails). When a matching event occurs:

• Microsoft sends a POST notification to your specified webhook URL.
• This webhook must respond quickly (within 10 seconds) and validate a special validationToken on initial setup.
• Each subscription is valid for up to 3 days, so you must renew it periodically to keep it active.
• This module provides a clean interface for:
  • Creating new subscriptions
  • Listing active ones
  • Renewing before expiration
  • Deleting them if no longer needed

To use MS Graph webhooks, you must expose a public HTTPS URL for Microsoft to call.

1. Create a Lambda function that:
   • Accepts GET (for validation) and POST (for notifications)
   • Responds with the validationToken if provided in the query
2. Add API Gateway in front of the Lambda to expose it via a public URL.
3. Use this URL as the notificationUrl when calling create_microsoft_graph_webhook().

💡 Make sure the Lambda responds to validation requests with:

• 200 OK
• Content-Type: text/plain
• Plain validationToken in the body

Run this code to create a webhook.

Once you create a webhook (MS calls it a subscription for your inbox) you can check all active subscriptions for an inbox. This will display the subscription id and its validity date. By default MS allows a subscription to be active for a maximum of 3 days, so you have to renew it before it expires.

You will get a response like this:

You can renew all subscriptions for an inbox by running this code. The renewal is set to work if you run it within 24 hours before the subscription expires. It will then renew the subscription for an extra 3 days (from the date the subscription was originally set to expire). You can run as a daily cron job to renew the subscriptions automatically.

For an example of how to run this code in AWS Lambda to renew the subscriptions automatically, see the webhook_renewal/README.md file.

If you want to delete a subscription you can do so by running this code. You will need the subscription id that you can obtain from the get_active_subscriptions_for_inbox() method.

This can be useful if you want to re-use the same URL for a new inbox/subscription or if by accident you created too many subscriptions for one inbox (MS allows it, but I don't recommend it as it becomes a mess to manage in production).