TailoredApps.Shared.Email.Office365¶
Description¶
An IEmailProvider implementation that reads email from Microsoft 365 using IMAP with OAuth2 authentication (client credentials flow). The library authenticates with Azure AD as a confidential client application — supporting both client secret and certificate authentication.
This allows you to receive messages from an Office 365 mailbox without storing a user password. The library automatically handles token acquisition and caching via Microsoft Identity.
SendMail — not implemented
The SendMail method throws NotImplementedException. This library supports reading only via IMAP. For sending, use SmtpEmailProvider or Microsoft Graph integration.
Installation¶
DI registration¶
// Program.cs
using TailoredApps.Shared.Email.Office365;
builder.Services.RegisterOffice365Provider();
appsettings.json configuration¶
{
"Mail": {
"Providers": {
"Office365": {
"Instance": "https://login.microsoftonline.com/{0}",
"Tenant": "your-tenant-id-or-domain.onmicrosoft.com",
"ClientId": "your-application-client-id",
"MailBox": "shared-mailbox@yourdomain.com",
"ClientSecret": "your-client-secret"
}
}
}
}
Instance is optional - the value above is its default. AuthenticationConfig also binds ApiUrl (default https://graph.microsoft.com/), but the provider does not use it: it always connects over IMAP to outlook.office365.com:993 and requests a token for https://outlook.office365.com/.default.
Azure AD configuration¶
The application in Azure AD needs application permissions (not delegated ones):
IMAP.AccessAsApp— IMAP access as an application- Administration:
New-ServicePrincipalAllowedToUseAppfor the specific mailbox
Usage example¶
public class MailboxMonitorService
{
private readonly IEmailProvider _emailProvider;
public MailboxMonitorService(IEmailProvider emailProvider)
{
_emailProvider = emailProvider;
}
public async Task<ICollection<MailMessage>> GetNewOrdersAsync()
{
// Get the messages from the last 24 hours from a specific sender
var messages = await _emailProvider.GetMail(
folder: "Orders", // a sub-folder of the Inbox (Inbox/Orders)
sender: "orders@partner.com",
fromLast: TimeSpan.FromHours(24)
);
return messages;
}
public async Task<ICollection<MailMessage>> GetAllFromInboxAsync()
{
// Get all messages from the inbox (read and unread)
return await _emailProvider.GetMail();
}
}
folder names a sub-folder of the Inbox; an empty value (the default) means the Inbox itself, so folder: "Inbox" would look for Inbox/Inbox. The folder is opened read-only. sender and recipent are "contains" filters and fromLast limits the result to messages delivered after now minus that time span; without filters every message in the folder is downloaded.
API Reference¶
| Type | Kind | Description |
|---|---|---|
Office365EmailProvider |
Class | IEmailProvider implementation over IMAP + OAuth2 |
Office365EmailProvider.GetMail(folder, sender, recipent, fromLast, cancellationToken) |
Method | The same as the interface's GetMail, but cancellable: the token covers acquiring the OAuth2 token and every IMAP round trip. On the provider class (the IEmailProvider interface has no token) |
AuthenticationConfig |
Class | Azure AD configuration (tenant, clientId, secret/cert) |
AuthenticationConfig.Instance |
Property | AAD instance URL (Azure Public by default) |
AuthenticationConfig.ApiUrl |
Property | Bound from configuration (default https://graph.microsoft.com/) but not used by the provider |
AuthenticationConfig.Tenant |
Property | Tenant ID or domain |
AuthenticationConfig.ClientId |
Property | Application ID in Azure AD |
AuthenticationConfig.MailBox |
Property | Address of the mailbox to work with |
AuthenticationConfig.ClientSecret |
Property | Client secret (alternative to the certificate) |
AuthenticationConfig.Certificate |
Property | Certificate (CertificateDescription) |
Office365EmailProviderExtensions.RegisterOffice365Provider |
Ext. method | Registers the provider in DI |
🔒 Security and correctness¶
- Attachments in
MailMessage.Attachementsare keyed by file name (duplicates get a(2)suffix) and the content is decoded from its MIME transfer encoding before being base64-encoded - previously the key was the MIME type (two PDFs threw) and the data was base64-of-base64. - The
IMAP.AccessAsApppermission grants access to every mailbox in the tenant unless an Exchange Online Application Access Policy restricts it.
🤖 AI Agent Prompt¶
## TailoredApps.Shared.Email.Office365 - instructions for an AI agent
You are using the TailoredApps.Shared.Email.Office365 library in a .NET project.
### Registration
```csharp
builder.Services.RegisterOffice365Provider();
```
### appsettings.json
```json
"Mail": { "Providers": { "Office365": {
"Tenant": "tenant-id",
"ClientId": "app-client-id",
"MailBox": "mailbox@domain.com",
"ClientSecret": "secret"
}}}
```
### Usage
```csharp
// Read only — SendMail throws NotImplementedException!
var messages = await _emailProvider.GetMail(
folder: "Orders", // sub-folder of the Inbox; "" (default) = the Inbox itself
sender: "filter@domain.com",
fromLast: TimeSpan.FromHours(24)
);
```
### Rules
- SendMail() is not implemented — use SmtpEmailProvider for sending
- folder is a sub-folder of the Inbox - never pass "Inbox"; leave it empty to read the Inbox
- ApiUrl is bound but unused; the IMAP host (outlook.office365.com:993) is not configurable
- GetMail is asynchronous end to end (from 3.0 also opening the folder, searching and downloading the messages): always await it, never .Result or .Wait(); it downloads whole messages, so narrow the query with folder, sender and fromLast
- When the caller can give up (an aborted HTTP request, a host shutting down), inject Office365EmailProvider and use the GetMail(folder, sender, recipent, fromLast, cancellationToken) overload
- Requires the IMAP.AccessAsApp application permission in Azure AD
- OAuth2 tokens are cached automatically by MSAL
- Configuration section: "Mail:Providers:Office365"
- Restrict the Azure AD application to specific mailboxes with an Application Access Policy