---
title: "Outlook OAuth email API: connect a mailbox and read messages"
description: "Connect Outlook.com or Microsoft 365 with OAuth, then read messages through Mailera's API. Understand Graph tokens, scoped keys and consent errors."
url: https://mailera.app/en/blog/outlook-oauth-email-api
published: 2026-10-25
updated: 2026-10-25
---

# Outlook OAuth email API: connect a mailbox and read messages

Connect an existing Outlook.com or Microsoft 365 mailbox through Microsoft sign-in, then read it with a scoped Mailera API key. Keep Graph tokens, protocol OAuth and application credentials separate.

## Which Outlook email API should you use?

Use Microsoft Graph for this walkthrough, either directly or through Mailera’s Graph-backed connection. OAuth is the authorization mechanism, not the mail protocol: choosing OAuth does not tell your application whether to call Graph or connect through IMAP/SMTP.

| Path | Interface your app uses | Credential your app supplies | Integration responsibility |
| --- | --- | --- | --- |
| Direct Microsoft Graph | Graph REST API | Microsoft Graph access token | You implement Microsoft authorization and Graph requests |
| IMAP/SMTP with OAuth | IMAP/SMTP with SASL XOAUTH2 | Microsoft access token for the relevant protocol resource | You implement authorization and the protocol client |
| Mailera | Mailera REST API; Graph behind the Microsoft connection | Scoped Mailera API key | Mailera handles the Graph connection; you call Mailera |

Microsoft’s [IMAP, POP and SMTP OAuth instructions](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth) require full scopes containing Outlook resource URLs and SASL XOAUTH2 for transmitting the token. Those instructions are not a Graph request recipe. Don’t mix their scopes and protocol authentication with Graph endpoints.

For a broader comparison of these interfaces, see [IMAP, Graph and SMTP for agent builders](https://mailera.app/en/blog/email-protocols-for-ai-agents).

For direct Graph, the basic sequence is:

1. Register your application with Microsoft Entra ID.
2. Request delegated authorization from the user.
3. Redeem the authorization code for an access token.
4. Use that token to make a Graph mail request.

Microsoft’s [delegated Graph authorization guide](https://learn.microsoft.com/en-us/graph/auth-v2-user) covers that flow. Its [list-messages reference](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0), read on Oct 25, 2026, documents `GET /me/messages` and lists `Mail.ReadBasic` as the least privileged delegated permission for that operation for both personal and work or school accounts. That permission table describes direct Graph access, not Mailera key permissions.

Choose direct Graph when you want to implement that Microsoft integration yourself. Choose Mailera when you want your application to call its API against an existing connected mailbox. For other providers, see the [guide to connecting existing email providers](https://mailera.app/en/blog/email-provider-api-integration).

## How do you connect Outlook to Mailera with OAuth?

The [Mailera Microsoft connection](https://mailera.app/en/providers/microsoft) supports Outlook.com, Hotmail and Microsoft 365. Start with a mailbox you own or are authorized to access.

1. As an Admin or Leader, open **Mailboxes → Add mailbox**. Other roles cannot add mailboxes.
2. Select **Sign in with Microsoft**.
3. Complete sign-in at Microsoft and review the requested consent before approving it. If Microsoft requires administrator approval, involve your administrator rather than trying another authentication method to get around the requirement.
4. Return to **Mailboxes**. Verify that the intended Microsoft mailbox appears, inspect its status and last sync, and check initial message loading.

![Mailera Add mailbox page with Sign in with Microsoft selected.](https://mailera.app/media/b12cb977e2574d90/mcp-gmail-outlook-imap-add-test-mailbox-ja-1200.jpg)
_Start the Microsoft OAuth connection from Sign in with Microsoft._

The sign-in flow above does not ask you to register your own Entra application. That is different from building a direct Graph integration, where app registration is part of Microsoft’s setup.

Mailera also supports importing an existing Microsoft refresh token, but that is a separate connection path. Use **Sign in with Microsoft** for the interactive flow described here; Microsoft mailboxes are not connected to Mailera with an app password.

There are two authorization boundaries after connection. Microsoft authorizes Mailera’s Graph access to the mailbox. Your application then authenticates to Mailera with a separate API key. A key that permits a Mailera request is not a Microsoft Graph access token.

![Microsoft consent authorizes Mailera’s Graph connection, while a separate Mailera API key authorizes the application’s REST requests.](https://mailera.app/media/cb897bef356b82fc/outlook-oauth-email-api-connect-a-mailbox-and-read-messages-en-1200.jpg)
_Microsoft tokens and Mailera API keys authorize different connections._

## How do you read the first message through the API?

Create a key for this read-only task before making requests:

1. Open **Settings → API key tab → Create key**.
2. Enter a **Descriptive name** that identifies the application.
3. Set **Mailbox scope** to the group containing your test mailbox. Admins can select all groups, but this walkthrough only needs one.
4. Select **Read**. Leave sending and management permissions off.
5. Set **Expiration** and, where appropriate, **IP restrictions (optional)**.
6. Copy the key when **Key created — copy it now** appears. It is shown only once, so store it securely.

![Mailera API key creation dialog with one mailbox group and Read permission selected.](https://mailera.app/media/40319144ad5af928/outlook-oauth-email-api-connect-a-mailbox-and-read-messages-en-1200.jpg)
_Scope the first-read key to the mailbox group it needs._

The base URL is `https://mailera.app/api/public/v1`. Every request below uses `Authorization: Bearer $MAILERA_API_KEY`. Make the key available in your local shell as `MAILERA_API_KEY` through your normal secret-handling process; don’t paste it into source files or shared terminal transcripts.

### 1. Find your mailbox

```bash
curl --silent --show-error \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes?provider=microsoft"
```

Find the intended mailbox in `data` and set `MAILBOX_ID` to its `id`. Use the address to identify your mailbox, but keep personal addresses out of shared logs. The response also includes `provider`, `protocol` and synchronization fields such as `last_sync_at`.

If you cannot find the mailbox, check the key’s group scope before changing the Microsoft connection. Listing mailboxes requires the `read` scope.

### 2. Check Microsoft sign-in

```bash
curl --silent --show-error \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status"
```

For Microsoft mailboxes, this endpoint directly checks whether mailbox sign-in still works, not whether a particular new message has synchronized.

### 3. List Inbox messages

```bash
curl --silent --show-error \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1"
```

Inspect the returned message’s `subject`, `from`, `folder` and `received_at`. Set `MESSAGE_ID` to the message’s `id` from `data`, not its `graph_message_id`. The Mailera message endpoint takes the Mailera message identifier.

An empty list does not confirm that you can read a message. Confirm the mailbox and folder, then look for a non-sensitive test message in that mailbox.

### 4. Retrieve its content

```bash
curl --silent --show-error \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID"
```

The message response includes `data.body.text` and `data.body.html`. Inspect the content of your test message. A working sign-in check followed by a successful content retrieval establishes that the mailbox is connected and that message is readable through your scoped key.

The direct-Graph counterpart for listing messages is `GET https://graph.microsoft.com/v1.0/me/messages`. It requires a Microsoft Graph access token and the appropriate Microsoft permissions. Do not send your Mailera key there, and do not substitute a Graph token in the Mailera requests above.

See the [Mailera API documentation](https://mailera.app/en/docs) for the endpoint reference. Sending is separate: Mailera’s send endpoint requires the `send` scope, exposed as **Send messages** when creating a key. A Read-only key is the right starting point for this workflow.

## What happens after the mailbox is connected?

Mailera receives new Microsoft mail through Graph change notifications, with periodic background checks as a fallback. Microsoft’s [Outlook change notification documentation](https://learn.microsoft.com/en-us/graph/outlook-change-notifications-overview) explains the underlying subscription mechanism.

Background checks run more often for mailboxes in active use and less often for idle ones. Inactive mailboxes can sleep and wake on use. Don’t build your application around an assumed fixed arrival time.

Keep sign-in health and message freshness separate. The status endpoint checks Microsoft sign-in; message listings and synchronization timestamps help you inspect what Mailera has loaded. A successful status check is not a delivery receipt for a specific message.

![Connected Microsoft mailbox in Mailera with its status and last sync visible.](https://mailera.app/media/0a4464668fab1b96/outlook-oauth-email-api-connect-a-mailbox-and-read-messages-en-1200.jpg)
_Inspect connection status and synchronization separately._

The [Mailera product overview](https://mailera.app/en/product) describes its role as a connection layer for existing mailboxes. Mailera does not create Outlook addresses or new mailboxes, and it does not offer bulk or marketing sending.

## What are the common connection and API mistakes?

First identify where the failure occurs: Microsoft consent, Mailera API authentication, or message retrieval. Changing credentials at the wrong boundary won’t resolve the underlying problem.

| Symptom | Check | Next action |
| --- | --- | --- |
| Microsoft asks for administrator approval or blocks consent | Whether the requested access needs administrator approval | Ask your organization’s administrator to review the request; don’t bypass its policy |
| A Graph token is being used with Mailera | The credential in the Bearer header | Replace it with a Mailera API key |
| The expected mailbox is missing | The mailbox’s group and the key’s Mailbox scope | Use a key scoped to the correct group |
| Read requests fail | Whether the key includes Read and remains valid | Check its permissions, expiration, IP restrictions and revocation state |
| Setup is asking for a Microsoft app password | Whether you chose the intended connection path | Return to Sign in with Microsoft |
| Microsoft authorization was revoked | Whether the status endpoint still reports working sign-in | Review the Microsoft connection and restore authorized access before retrying reads |
| Sign-in works, but a new message is absent | The folder and synchronization state | Check message loading separately from authentication; allow for background synchronization |

Microsoft requires users or administrators to grant Graph permissions. Its [authorization-code guidance](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow) directs requests for admin-restricted scopes to a Global Administrator. Administrator approval is a consent issue, not a reason to swap Graph for an app password.

## How should an app or AI agent handle mailbox access safely?

Treat incoming email as untrusted data, not instructions. A message can ask an agent to reveal a key, ignore application rules or contact another address. Those requests must not override your application’s policies. Keep message content separate from the instructions that control the agent.

Use a Read-only key restricted to the relevant mailbox group. Apply expiration and IP restrictions where appropriate. Keep API keys and Microsoft tokens out of browser code, screenshots, logs and source control. Mailera’s [security information](https://mailera.app/en/security) provides further product context.

If you later enable sending, require confirmation before the agent sends a message. Don’t grant **Send messages** or **Manage mailboxes** merely to retrieve email. Microsoft likewise recommends [requesting the least privileged Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference) needed for an application.

Plan revocation at both boundaries. Revoking a Mailera key immediately rejects calls using that key. Microsoft authorization controls the separate Graph connection. Treat stopping an application’s API access and withdrawing Microsoft authorization as distinct actions.

**Connect your first mailbox in 2 minutes** — Add an Outlook, Gmail or IMAP mailbox and read email messages in the app or via the API. [Connect mailbox](https://mailera.app/auth?mode=signup)