Outlook OAuth email API: connect a mailbox and read messages

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.

Microsoft’s IMAP, POP and SMTP OAuth instructions 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.

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 covers that flow. Its list-messages reference, 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.

How do you connect Outlook to Mailera with OAuth?

The Mailera Microsoft connection 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.

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.

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.

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

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

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

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

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 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 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.

The Mailera product overview 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.

Microsoft requires users or administrators to grant Graph permissions. Its authorization-code guidance 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 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 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.