Outlook refresh token import: connect and verify your mailbox

Should you import a token or sign in with Microsoft?

Use refresh-token import when you already hold an authorized token for your own mailbox and know which application it belongs to. Otherwise, choose Sign in with Microsoft. That path uses Microsoft's OAuth consent flow and avoids manually handling a refresh token.

Mailera supports Outlook.com, Hotmail, and Microsoft 365 through Microsoft Graph, using OAuth or an imported refresh token. The Microsoft provider page covers these connection options. For the broader workflow, see connecting existing email providers to agents.

Four values that aren't interchangeable

A refresh token lets an application obtain new access-token and refresh-token pairs when the current access token expires. The documented import field is refresh_token, not access_token.

A client ID identifies the application. Microsoft calls it the Application (client) ID assigned through app registration. A Mailera API key authenticates requests to Mailera, not to Microsoft's token service.

Microsoft's refresh-token documentation says refresh tokens are bound to a user-and-client combination. You cannot choose an unrelated client ID and expect the token to work. Microsoft's authorization code flow reference defines the client_id parameter and its application context.

What do you need before importing?

Start with one test mailbox you own. Have these ready:

• Permission to connect the mailbox.
• An Admin or Leader role in Mailera; only these roles can add mailboxes.
• A legitimately issued refresh token and its associated client ID.
• The destination mailbox group.

Use the application context associated with the token's original authorization. If you cannot establish that pairing, return to interactive sign-in rather than trying client IDs from examples online.

Token possession alone does not grant every mailbox operation. The Microsoft Graph permissions reference states that the user or administrator must grant the necessary permissions. Admin-restricted permissions require administrator consent, as described in Microsoft's scopes and permissions guide.

Read the import format carefully

The documented Microsoft field order is email:password:refresh_token:client_id, with one mailbox per line. These are field names, not a paste-ready example.

The password position is part of that format. It is not an instruction to create a Microsoft app password: Mailera does not connect Microsoft mailboxes through app-password authentication. Don't guess a value, insert your normal Microsoft password, or assume that leaving the field empty is acceptable. If you don't have a complete import record whose fields you understand, use Sign in with Microsoft instead.

How do you import your mailbox in Mailera?

Keep the import record private throughout this process. Don't put it in screenshots, chat messages, issue trackers, shell commands, or shared text files.

1. Open Mailboxes → Add mailbox → Bulk paste.
2. Enter one Microsoft mailbox record in the field order email:password:refresh_token:client_id. Supported separators are colon, vertical bar, semicolon, and Tab. You can also upload a .txt file; restrict access to that file while you need it.
3. Choose the destination Group.
4. Review duplicate handling. Skip leaves an existing address out of this import. Overwrite is also available, but don't select it as a routine troubleshooting step. For a first test, choose an address that isn't already connected or use Skip to avoid overwriting an existing entry.
5. Select Start import. On the progress page, inspect Successful, Errors, and Skipped rather than looking only at whether the job finished.

Tokens submitted through Bulk paste are encrypted before saving and are not shown again. That protection does not remove copies you created outside Mailera.

How do you confirm the connection actually works?

Treat import completion, Microsoft sign-in, and message access as separate checks. An import result is not a substitute for reading the mailbox.

Use GET /mailboxes/{id} to inspect data.provider, data.status, and data.last_sync_at. Then open the mailbox and look for a recent, non-sensitive message you recognize from your own Inbox.

For API verification, use a Mailera API key scoped to the mailbox's group. Grant only the permissions needed for the check. The Mailera API documentation is the reference for these routes.

The import scope is separate from read access. It is also separate from Microsoft consent: a Mailera permission controls calls to Mailera, not what Microsoft has authorized.

With $MAILERA_API_KEY and $MAILBOX_ID available in your local environment, check Microsoft sign-in:

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Then request one Inbox message:

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

Inspect data for the message, including folder, subject, and received_at. Compare it with the message you expected. If the list is empty, check the selected mailbox and folder before replacing credentials.

Keep API output private too: message subjects and previews can contain sensitive information. This guide does not check sending; don't grant send just to verify read access.

Why is your Outlook refresh token import not working?

First check the import record and duplicate handling, then Microsoft authorization and message reading.

In Microsoft's authentication error reference, invalid_grant can mean invalid, unparseable, missing, or otherwise unusable authentication material. It does not mean only “expired token.” interaction_required means user interaction is needed.

The progress page offers Export errors as CSV. Treat the export as sensitive. For support, prepare a separate note containing only the relevant error code, time, and structural details; don't attach the raw CSV or import record.

How should you protect the token after import?

Minimize local copies. Restrict access to temporary import files and remove them when no longer needed. Never submit a refresh token to a public token-checking website or paste it into a support conversation. See Mailera's security information for product security details.

If a token is exposed, stop sharing it and follow Microsoft's account-appropriate revocation guidance in its refresh-token documentation. For a work or school account, involve your administrator. Microsoft specifically says B2B refresh tokens must be revoked in the home tenant, not the resource tenant.

Do not rely on refreshing the token to neutralize the exposed copy. Microsoft says using a refresh token does not revoke the old one. After revocation, reauthenticate interactively to obtain fresh authorization.

Revoking a Mailera API key addresses that key: calls using it are rejected immediately, but it is a different credential from the Microsoft token.

If an agent will read the mailbox

Treat incoming email as untrusted data, not instructions. An email must not be allowed to tell the agent to reveal credentials or change its access controls.

Give the agent a narrowly scoped Mailera key restricted to the needed mailbox group. Leave Send messages disabled unless sending is required, and require confirmation before sending. A read-verification task does not need import or management permissions. For the access-control design, see least-privilege architecture for mailbox agents.

What Mailera does not change

Mailera connects existing mailboxes to apps and agents; it does not create Outlook accounts or email addresses. Importing a token does not replace the required Microsoft Graph permission grants. Admin-restricted permissions require administrator consent.