Skip to content

Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys needed — runs on your Claude or Codex subscriptions.

Add a Microsoft 365 mail provider (Microsoft Graph)

Camilo Cruz3e69a6d28986
diff --git a/.env.example b/.env.example
index 8642a25..c51697f 100644
--- a/.env.example
+++ b/.env.example
@@ -30,6 +30,17 @@ IMAP_PORT=993
IMAP_USERNAME=
IMAP_PASSWORD=
+# Option B2: Microsoft 365 / Outlook [for a mailbox on Exchange Online]
+# Set provider: microsoft in harvey.yaml. Exchange Online no longer
+# accepts passwords over IMAP, so this signs in with OAuth instead:
+# 1. entra.microsoft.com → App registrations → New registration
+# ("this organizational directory only"; redirect URI platform
+# "Public client/native", value http://localhost:8766)
+# 2. Paste the Application (client) ID and Directory (tenant) ID below
+# 3. Run: harvey microsoft auth (then: harvey microsoft test)
+M365_CLIENT_ID=
+M365_TENANT_ID=
+
# Option C: Instantly — cold email platform [legacy]
# Where to get it: https://app.instantly.ai → Settings → Integrations → API Keys
# API access requires Instantly's Growth plan or higher.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2f58d8b..b74b4c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ Notable changes to Harvey. Dates are release dates; the format follows
follow [semver](https://semver.org/), with the caveat that Harvey is pre-1.0 and
minor versions can still change behaviour.
+## [Unreleased]
+
+### Added
+
+- **Microsoft 365 mail provider.** Set `channels.email.provider: microsoft` to
+ send and read through a Microsoft 365 / Outlook mailbox via Microsoft Graph,
+ for domains whose mail lives in Exchange Online (which no longer accepts
+ passwords over IMAP). Signs in once with OAuth + PKCE (`harvey microsoft
+ auth`; no client secret, no stored password), drafts then sends so the
+ Message-ID is known, threads replies with `createReply`, reads the last 7
+ days of the inbox without marking anything read, refuses to act as any
+ mailbox other than `persona.email`, and holds sending when the inbox can't
+ be read. See [docs/microsoft365.md](docs/microsoft365.md).
+
## [0.3.0] — 2026-10-13
### Added
diff --git a/README.md b/README.md
index 3035270..8a649e5 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ Profiling and outbox draining ride along on **every** cycle regardless, because
- **Python 3.11+** — check with `python3 --version`. macOS ships 3.9; if that's what you have, `brew install [email protected]` first.
- An active **Claude Pro or Max** subscription, with the CLI logged in (`claude login`) — or, opt-in, a **ChatGPT plan with the Codex CLI** ([see below](#using-a-chatgpt-plan-instead-codex))
-- A mailbox to send from — Gmail/Workspace recommended, on a *dedicated secondary domain*
+- A mailbox to send from — Gmail/Workspace recommended, on a *dedicated secondary domain*. Microsoft 365 works too ([setup](docs/microsoft365.md))
### Easiest: let Claude set it up
@@ -390,7 +390,7 @@ persona: { name, company, role, email, tone }
product: { name, description, pricing, key_benefits, objection_responses, offer }
icp: { industries, titles, company_size, geography, hiring_signals, geo_coordinates }
channels:
- email: { provider: gmail | smtp | instantly, max_daily_sends, require_approval,
+ email: { provider: gmail | microsoft | smtp | instantly, max_daily_sends, require_approval,
send_to_risky, max_bounce_rate }
usage: { max_daily_claude_percent, heartbeat_interval_minutes, quiet_hours }
brain: { provider: claude | codex, model, reasoning_effort } # optional; claude by default
@@ -415,6 +415,7 @@ harvey outbox # review queued email
harvey export # deliverable prospects → CSV
harvey sending pause|resume # kill switch
harvey gmail auth # one-time Gmail OAuth
+harvey microsoft auth|test # one-time Microsoft 365 sign-in (docs/microsoft365.md)
```
@@ -547,7 +548,7 @@ tests/ # 242 tests
## Roadmap
-**Done:** heartbeat loop · observation data model with governed vocabulary · user-confirmed signal catalog · cohort builder · discovery provider menu with cost estimates · free HTTP profiler with agency detection · pattern-first email finding with honest status · native mail providers (Gmail API, SMTP+IMAP) · outbox approval ladder · deterministic pre-send gate · bounce detection and kill switch · reply handling with intent classification · subscription quota tracking · website trainer · web dashboard · CSV export
+**Done:** heartbeat loop · observation data model with governed vocabulary · user-confirmed signal catalog · cohort builder · discovery provider menu with cost estimates · free HTTP profiler with agency detection · pattern-first email finding with honest status · native mail providers (Gmail API, Microsoft 365 via Graph, SMTP+IMAP) · outbox approval ladder · deterministic pre-send gate · bounce detection and kill switch · reply handling with intent classification · subscription quota tracking · website trainer · web dashboard · CSV export
**Next:** people enrichment from public registries · consent-gated voice callbacks · calendar integration for auto-booking · scheduled re-observation so signal *changes* trigger outreach · multi-product support
diff --git a/docs/microsoft365.md b/docs/microsoft365.md
new file mode 100644
index 0000000..a38adc5
--- /dev/null
+++ b/docs/microsoft365.md
@@ -0,0 +1,155 @@
+# Sending from a Microsoft 365 mailbox
+
+Harvey can send and read mail through a Microsoft 365 / Outlook mailbox
+(Exchange Online) using Microsoft Graph. Use it when your sending domain's
+mail lives in Microsoft 365.
+
+## Why not SMTP + IMAP?
+
+Exchange Online no longer accepts a password for IMAP, and SMTP AUTH is off
+by default in most tenants. The `smtp` provider can sometimes still send, but
+it can't read the inbox. Harvey has to read replies to stop sequences, honor
+opt-outs and catch bounces. If it can send but can't read, it keeps emailing
+people who already answered.
+
+The `microsoft` provider signs in with OAuth (authorization code + PKCE)
+instead. Harvey never stores a password or a client secret.
+
+## Setup
+
+### 1. Register an app in Entra ID
+
+At [entra.microsoft.com](https://entra.microsoft.com), go to
+**Applications → App registrations → New registration**:
+
+| Field | Value |
+|---|---|
+| Name | `Harvey` |
+| Supported account types | *Accounts in this organizational directory only* |
+| Redirect URI, platform | **Public client/native (mobile & desktop)** |
+| Redirect URI, value | `http://localhost:8766` |
+
+From the app's **Overview**, copy the **Application (client) ID** and the
+**Directory (tenant) ID**.
+
+Don't create a client secret. Harvey is a public client.
+
+### 2. Configure Harvey
+
+`.env`:
+
+```
+M365_CLIENT_ID=<Application (client) ID>
+M365_TENANT_ID=<Directory (tenant) ID>
+```
+
+`harvey.yaml` (or `harvey.local.yaml`):
+
+```yaml
+persona:
+ email: "[email protected]" # must be the mailbox you sign in with
+channels:
+ email:
+ provider: "microsoft"
+```
+
+### 3. Sign in once
+
+```bash
+harvey microsoft auth # opens the browser; sign in as persona.email
+harvey microsoft test # → ✓ Connected as [email protected]
+```
+
+Harvey asks for four **delegated** permissions:
+
+| Permission | Why it's needed |
+|---|---|
+| `Mail.ReadWrite` | read replies, and create drafts (reply threading) |
+| `Mail.Send` | send them |
+| `User.Read` | check which mailbox the token belongs to |
+| `offline_access` | keep working without signing in again |
+
+The refresh token is stored in `data/m365_token.json` (mode 600, gitignored).
+Microsoft rotates it on every use, and Harvey saves the new one each time.
+
+### If you see "Need admin approval"
+
+Your tenant doesn't let users consent to apps themselves. An admin has to
+approve the app once:
+
+1. In Entra, open **App registrations → Harvey → API permissions**. Add the
+ four Microsoft Graph delegated permissions above, then click
+ **Grant admin consent**.
+2. Run `harvey microsoft auth` again and sign in as the **sending mailbox**,
+ not as the admin. Harvey always acts as whoever signs in.
+
+To make sure nobody else in the tenant can use the app, go to
+**Enterprise applications → Harvey**:
+
+1. **Users and groups**: assign only the sending mailbox.
+2. **Properties**: set **Assignment required?** to **Yes**. Do this after
+ step 1, or the sending mailbox is locked out too.
+
+## How it behaves
+
+- **Sending.** Harvey creates a draft and then sends it, so the email's
+ RFC `Message-ID` is known. Bounces and replies are matched on it. Bodies
+ are plain text.
+- **Replies are threaded.** Harvey answers with `createReply` on the
+ prospect's own message, so `In-Reply-To` and `References` are correct. If
+ that message was deleted, the reply goes out as a new email.
+- **Your inbox is left alone.** Each cycle, Harvey reads the last 7 days of
+ the inbox, newest first, and skips your own mail. It never marks anything
+ read, moves it or deletes it. It keeps its own record of what it has
+ handled.
+- **It only acts as the right mailbox.** If the signed-in mailbox isn't
+ `persona.email`, every read and send is refused with a message saying so.
+ This catches the common mistake of signing in as the admin who approved
+ the app.
+- **Failures hold sending.** If the inbox can't be read (expired login,
+ Graph outage, throttling), the cycle sends nothing. A reply nobody read
+ can't have stopped its follow-ups. Graph throttling (429/503 with a short
+ `Retry-After`) is retried once.
+- **Unsent drafts are cleaned up.** If a send fails, its draft is deleted
+ so it doesn't sit in your Drafts folder.
+- **The sender name is the mailbox's.** Mail goes out under the mailbox's
+ display name in Microsoft 365, not `persona.name`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Timed out waiting for the browser round-trip` | The browser never came back to `localhost:8766`. Check that nothing else uses the port, and that the redirect URI is `http://localhost:8766` under *Mobile and desktop applications* (not *Web*). |
+| `AADSTS50011` (redirect URI mismatch) | Same as above: the URI and its platform must match exactly. |
+| `Need admin approval` | See [If you see "Need admin approval"](#if-you-see-need-admin-approval). |
+| `signed in as X, but persona.email is Y` | Run `harvey microsoft auth` again and pick the right account. Use "Use another account" if the browser is already signed in as someone else. |
+| `token refresh rejected` | The login expired (90 days unused) or was revoked. Run `harvey microsoft auth` again. |
+
+To revoke Harvey's access, go to
+[myaccount.microsoft.com](https://myaccount.microsoft.com) → **Apps**, or
+delete the app registration. Then delete `data/m365_token.json`.
+
+## Deliverability notes
+
+- **Enable DKIM** for your domain in Microsoft Defender (Email
+ authentication → DKIM). Without it, mail from Exchange Online isn't
+ signed with your domain.
+- **Mind the tenant.** Exchange Online watches outbound spam for the whole
+ tenant. If you share it with an organization, its sending reputation
+ depends on yours: keep `max_daily_sends` low and `require_approval: true`.
+
+## For developers
+
+| File | What it is |
+|---|---|
+| `harvey/integrations/microsoft.py` | `MicrosoftProvider` (a `MailProvider`) and `run_auth_flow` |
+| `harvey/integrations/mail_provider.py` | Registers `microsoft` in `NATIVE_PROVIDERS` and `get_mail_provider` |
+| `harvey/cli.py` | `harvey microsoft auth\|test` |
+| `tests/test_microsoft.py` | Graph and login faked with `httpx.MockTransport`; no network |
+
+`get_replies` **raises** `GraphError` when the inbox can't be read, instead
+of returning `[]`. The handler turns that into a failed read, and the
+heartbeat holds sending.
+
+The loopback callback server listens on both `127.0.0.1` and `::1`, because
+`localhost` resolves to both and browsers differ in which one they try.
diff --git a/harvey.yaml b/harvey.yaml
index 9c57a41..f5f0926 100644
--- a/harvey.yaml
+++ b/harvey.yaml
@@ -47,7 +47,7 @@ icp:
channels:
email:
enabled: true
- provider: "gmail" # gmail (recommended) | smtp | instantly
+ provider: "gmail" # gmail (recommended) | microsoft | smtp | instantly
max_daily_sends: 50
require_approval: true # native providers: emails wait in the Outbox
send_to_risky: false # also send to catch-all domains (off = safest)
diff --git a/harvey/cli.py b/harvey/cli.py
index 7fff8e5..4495867 100644
--- a/harvey/cli.py
+++ b/harvey/cli.py
@@ -392,6 +392,28 @@ def cmd_gmail(args):
asyncio.run(_test())
+def cmd_microsoft(args):
+ """Microsoft 365 provider utilities (auth / test)."""
+ from harvey.config import load_env
+
+ env = load_env()
+ if args.microsoft_action == "auth":
+ from harvey.integrations.microsoft import run_auth_flow
+ ok = run_auth_flow(env.m365_client_id, env.m365_tenant_id)
+ sys.exit(0 if ok else 1)
+
+ if args.microsoft_action == "test":
+ from harvey.config import load_config
+ from harvey.integrations.microsoft import MicrosoftProvider
+
+ async def _test():
+ provider = MicrosoftProvider(load_config(), env)
+ ok, detail = await provider.test_connection()
+ print(f"\n {'✓' if ok else '✗'} {detail}\n")
+ sys.exit(0 if ok else 1)
+ asyncio.run(_test())
+
+
def cmd_outbox(args):
"""Review and approve queued outgoing emails."""
from harvey.state import StateManager
@@ -711,6 +733,12 @@ def main():
help="auth: one-time OAuth; test: verify connection")
sub.set_defaults(func=cmd_gmail)
+ # harvey microsoft auth|test
+ sub = subparsers.add_parser("microsoft", help="Microsoft 365 provider setup")
+ sub.add_argument("microsoft_action", choices=["auth", "test"],
+ help="auth: one-time sign-in; test: verify connection")
+ sub.set_defaults(func=cmd_microsoft)
+
# harvey outbox
sub = subparsers.add_parser("outbox", help="Review/approve queued emails")
sub.add_argument("--approve", metavar="ID", default="", help="Approve one item")
diff --git a/harvey/config.py b/harvey/config.py
index 3c3b231..6bb9dca 100644
--- a/harvey/config.py
+++ b/harvey/config.py
@@ -71,7 +71,8 @@ class ICPConfig(BaseModel):
class EmailChannelConfig(BaseModel):
enabled: bool = True
# "instantly" (legacy), "gmail" (Gmail/Workspace via API — recommended),
- # or "smtp" (any SMTP+IMAP mailbox: AgentMail, Fastmail, ...)
+ # "microsoft" (Microsoft 365 / Outlook via Graph), or "smtp" (any
+ # SMTP+IMAP mailbox: AgentMail, Fastmail, ...)
provider: str = "instantly"
max_daily_sends: int = 50
# When True, also send to catch-all ("risky") domains, not just verified
@@ -237,6 +238,9 @@ class EnvConfig(BaseModel):
imap_port: int = 993
imap_username: str = ""
imap_password: str = ""
+ # Microsoft 365 (channels.email.provider: microsoft)
+ m365_client_id: str = ""
+ m365_tenant_id: str = ""
def _format_validation_error(e: ValidationError) -> str:
@@ -347,6 +351,8 @@ def load_env() -> EnvConfig:
imap_port=int(os.getenv("IMAP_PORT", "993").strip() or 993),
imap_username=os.getenv("IMAP_USERNAME", "").strip(),
imap_password=os.getenv("IMAP_PASSWORD", "").strip(),
+ m365_client_id=os.getenv("M365_CLIENT_ID", "").strip(),
+ m365_tenant_id=os.getenv("M365_TENANT_ID", "").strip(),
)
return env
diff --git a/harvey/dashboard.py b/harvey/dashboard.py
index 054a141..fb16ef7 100644
--- a/harvey/dashboard.py
+++ b/harvey/dashboard.py
@@ -150,6 +150,11 @@ async def get_setup_status():
(PROJECT_ROOT / "data" / "gmail_token.json").is_file()
provider_help = ("Set GMAIL_CLIENT_ID/SECRET in Settings, then run "
"'harvey gmail auth' in your terminal.")
+ elif provider == "microsoft":
+ provider_done = _has("M365_CLIENT_ID") and \
+ (PROJECT_ROOT / "data" / "m365_token.json").is_file()
+ provider_help = ("Set M365_CLIENT_ID and M365_TENANT_ID in .env, then run "
+ "'harvey microsoft auth' in your terminal.")
elif provider == "smtp":
provider_done = _has("SMTP_HOST", "SMTP_USERNAME", "SMTP_PASSWORD")
provider_help = "Enter your SMTP host, username, and password in Settings."
diff --git a/harvey/integrations/mail_provider.py b/harvey/integrations/mail_provider.py
index 7813d57..24b3f7c 100644
--- a/harvey/integrations/mail_provider.py
+++ b/harvey/integrations/mail_provider.py
@@ -6,6 +6,8 @@ thread. Two native providers ship:
- ``gmail`` — a Google Workspace / Gmail mailbox via the Gmail REST API
(recommended: a real mailbox on a dedicated secondary domain is the
most deliverable way to send <50 cold emails/day).
+- ``microsoft`` — a Microsoft 365 / Outlook mailbox via Microsoft Graph
+ (OAuth; Exchange Online no longer accepts passwords over IMAP).
- ``smtp`` — any mailbox that speaks SMTP + IMAP (AgentMail, Fastmail,
a Workspace app-mailbox, self-hosted). Configuration via .env.
@@ -19,7 +21,7 @@ from dataclasses import dataclass, field
logger = logging.getLogger("harvey.mail")
-NATIVE_PROVIDERS = ("gmail", "smtp")
+NATIVE_PROVIDERS = ("gmail", "smtp", "microsoft")
@dataclass
@@ -96,4 +98,7 @@ def get_mail_provider(config, env) -> MailProvider | None:
if provider == "smtp":
from harvey.integrations.smtp_mail import SmtpImapProvider
return SmtpImapProvider(config, env)
+ if provider == "microsoft":
+ from harvey.integrations.microsoft import MicrosoftProvider
+ return MicrosoftProvider(config, env)
return None
diff --git a/harvey/integrations/microsoft.py b/harvey/integrations/microsoft.py
new file mode 100644
index 0000000..4dfdfae
--- /dev/null
+++ b/harvey/integrations/microsoft.py
@@ -0,0 +1,423 @@
+"""Microsoft 365 / Outlook mailbox provider — Microsoft Graph, no SDK.
+
+Microsoft has turned off password sign-in for IMAP in Exchange Online, so
+the SMTP+IMAP provider can't read an M365 inbox. This one uses OAuth:
+
+Setup (one-time):
+1. https://entra.microsoft.com → App registrations → New registration.
+ Name "Harvey", "Accounts in this organizational directory only".
+ Redirect URI: platform "Public client/native (mobile & desktop)",
+ value http://localhost:8766
+2. Copy the Application (client) ID and Directory (tenant) ID into .env as
+ M365_CLIENT_ID / M365_TENANT_ID. No client secret: Harvey is a public
+ client and signs in with PKCE.
+3. Run ``harvey microsoft auth`` — opens a browser, you sign in and accept
+ Mail.ReadWrite + Mail.Send, and the refresh token is stored in
+ data/m365_token.json (mode 600). Revoke it any time at
+ https://myaccount.microsoft.com → Apps.
+
+Harvey never marks your mail read or moves it: it reads the last 7 days of
+the inbox and remembers what it has handled. Mail is sent as the signed-in
+mailbox, under its own display name.
+"""
+
+import asyncio
+import base64
+import hashlib
+import http.server
+import json
+import logging
+import secrets
+import socket
+import time
+import webbrowser
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+from harvey.paths import PROJECT_ROOT
+from harvey.integrations.mail_provider import (
+ InboundMessage,
+ MailProvider,
+ SendResult,
+ looks_like_bounce,
+)
+
+logger = logging.getLogger("harvey.microsoft")
+
+TOKEN_FILE = PROJECT_ROOT / "data" / "m365_token.json"
+GRAPH = "https://graph.microsoft.com/v1.0"
+LOGIN = "https://login.microsoftonline.com"
+SCOPE = (
+ "offline_access https://graph.microsoft.com/Mail.ReadWrite "
+ "https://graph.microsoft.com/Mail.Send https://graph.microsoft.com/User.Read"
+)
+LOOPBACK_PORT = 8766
+REPLY_WINDOW_DAYS = 7
+MAX_RETRY_AFTER_SECONDS = 10
+
+TIMEOUT = httpx.Timeout(connect=10.0, read=30.0, write=30.0, pool=10.0)
+
+_SELECT = ",".join((
+ "id", "subject", "from", "body", "internetMessageId", "conversationId",
+ "receivedDateTime", "internetMessageHeaders",
+))
+
+
+class GraphError(RuntimeError):
+ pass
+
+
+def _load_token() -> dict | None:
+ try:
+ if TOKEN_FILE.is_file():
+ data = json.loads(TOKEN_FILE.read_text())
+ if isinstance(data, dict) and data.get("refresh_token"):
+ return data
+ except (OSError, json.JSONDecodeError) as e:
+ logger.warning(f"Could not read Microsoft token file: {e}")
+ return None
+
+
+def _save_token(data: dict):
+ TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
+ TOKEN_FILE.write_text(json.dumps(data, indent=2))
+ try:
+ TOKEN_FILE.chmod(0o600)
+ except OSError:
+ pass
+
+
+def _token_url(tenant: str) -> str:
+ return f"{LOGIN}/{tenant or 'organizations'}/oauth2/v2.0/token"
+
+
+class MicrosoftProvider(MailProvider):
+ name = "microsoft"
+
+ def __init__(self, config, env, transport=None):
+ self.config = config
+ self.client_id = getattr(env, "m365_client_id", "")
+ self.tenant = getattr(env, "m365_tenant_id", "") or "organizations"
+ self._transport = transport # httpx.MockTransport in tests
+ self._access_token = ""
+ self._access_expires = 0.0
+ self._me = ""
+
+ def is_configured(self) -> bool:
+ return bool(self.client_id and _load_token())
+
+ def _client(self) -> httpx.AsyncClient:
+ return httpx.AsyncClient(timeout=TIMEOUT, transport=self._transport)
+
+ async def _token(self) -> str:
+ """Valid access token. Microsoft rotates the refresh token on every
+ use, so the new one is saved each time."""
+ if self._access_token and time.time() < self._access_expires - 60:
+ return self._access_token
+ stored = _load_token()
+ if not stored:
+ raise GraphError("not authorized. Run 'harvey microsoft auth'.")
+ try:
+ async with self._client() as client:
+ resp = await client.post(_token_url(self.tenant), data={
+ "client_id": self.client_id,
+ "grant_type": "refresh_token",
+ "refresh_token": stored["refresh_token"],
+ "scope": SCOPE,
+ })
+ except httpx.HTTPError as e:
+ raise GraphError(f"token refresh failed: {e}") from e
+ if resp.status_code != 200:
+ raise GraphError(
+ f"token refresh rejected ({resp.status_code}): {resp.text[:200]}. "
+ "Re-run 'harvey microsoft auth'."
+ )
+ data = resp.json()
+ if data.get("refresh_token"):
+ _save_token({**stored, "refresh_token": data["refresh_token"],
+ "refreshed_at": int(time.time())})
+ self._access_token = data.get("access_token", "")
+ self._access_expires = time.time() + float(data.get("expires_in", 3600))
+ if not self._access_token:
+ raise GraphError("token refresh returned no access token")
+ return self._access_token
+
+ async def _request(self, method: str, path: str, *, headers=None, **kwargs) -> dict:
+ """One Graph call. Raises GraphError on failure; retries once when
+ Graph asks to slow down (429/503 with a short Retry-After)."""
+ token = await self._token()
+ all_headers = {"Authorization": f"Bearer {token}", **(headers or {})}
+ for attempt in (1, 2):
+ try:
+ async with self._client() as client:
+ resp = await client.request(
+ method, f"{GRAPH}{path}", headers=all_headers, **kwargs
+ )
+ except httpx.HTTPError as e:
+ raise GraphError(f"{method} {path} failed: {e}") from e
+ if resp.status_code in (429, 503) and attempt == 1:
+ try:
+ wait = float(resp.headers.get("Retry-After", "5"))
+ except ValueError:
+ wait = 5.0
+ if wait <= MAX_RETRY_AFTER_SECONDS:
+ await asyncio.sleep(wait)
+ continue
+ break
+ if resp.status_code >= 400:
+ raise GraphError(f"Graph {resp.status_code} on {method} {path}: {resp.text[:200]}")
+ if not resp.content:
+ return {}
+ try:
+ return resp.json()
+ except ValueError:
+ return {}
+
+ async def _my_address(self) -> str:
+ if not self._me:
+ me = await self._request("GET", "/me", params={"$select": "mail,userPrincipalName"})
+ self._me = (me.get("mail") or me.get("userPrincipalName") or "").lower()
+ return self._me
+
+ async def _check_identity(self) -> str:
+ """The signed-in mailbox must be persona.email: a token for the wrong
+ account (say, the admin who approved the app) would otherwise send
+ cold email from that account."""
+ me = await self._my_address()
+ expected = (getattr(getattr(self.config, "persona", None), "email", "") or "").strip().lower()
+ if expected and me != expected:
+ raise GraphError(
+ f"signed in as {me}, but persona.email is {expected}. Run "
+ f"'harvey microsoft auth' again and sign in as {expected}."
+ )
+ return me
+
+ async def send_email(
+ self,
+ to_email: str,
+ subject: str,
+ body: str,
+ thread_ref: str = "",
+ in_reply_to: str = "",
+ ) -> SendResult:
+ """Draft, then send, so the RFC Message-ID is known (bounces and
+ replies are matched on it). A reply is drafted with createReply on
+ the prospect's message, which sets In-Reply-To/References."""
+ content = {
+ "subject": subject,
+ "body": {"contentType": "Text", "content": body},
+ "toRecipients": [{"emailAddress": {"address": to_email}}],
+ }
+ draft = None
+ try:
+ await self._check_identity()
+ if thread_ref:
+ try:
+ draft = await self._request(
+ "POST", f"/me/messages/{thread_ref}/createReply"
+ )
+ await self._request("PATCH", f"/me/messages/{draft['id']}", json=content)
+ except GraphError as e:
+ # Their message is gone (deleted/moved): send unthreaded.
+ logger.warning(f"Microsoft: createReply failed ({e}); sending as new.")
+ if draft and draft.get("id"):
+ await self._delete_draft(draft["id"])
+ draft = None
+ if draft is None:
+ draft = await self._request("POST", "/me/messages", json=content)
+ await self._request("POST", f"/me/messages/{draft['id']}/send")
+ except (GraphError, KeyError) as e:
+ if draft and draft.get("id"):
+ await self._delete_draft(draft["id"])
+ logger.error(f"Microsoft send failed to {to_email}: {e}")
+ return SendResult(ok=False, error=str(e)[:300])
+ return SendResult(
+ ok=True,
+ message_id=draft.get("internetMessageId", ""),
+ thread_ref=draft.get("conversationId", ""),
+ )
+
+ async def _delete_draft(self, draft_id: str):
+ try:
+ await self._request("DELETE", f"/me/messages/{draft_id}")
+ except GraphError as e:
+ logger.warning(f"Microsoft: couldn't delete unsent draft {draft_id}: {e}")
+
+ async def get_replies(self, limit: int = 50) -> list[InboundMessage]:
+ """The last week of the inbox, newest first, minus your own mail.
+ Raises on failure: the heartbeat then holds sends, because an unread
+ reply can't have stopped its follow-ups."""
+ me = await self._check_identity()
+ since = (datetime.now(timezone.utc) - timedelta(days=REPLY_WINDOW_DAYS))
+ data = await self._request(
+ "GET", "/me/mailFolders/inbox/messages",
+ params={
+ "$filter": f"receivedDateTime ge {since.strftime('%Y-%m-%dT%H:%M:%SZ')}",
+ "$orderby": "receivedDateTime desc",
+ "$top": str(limit),
+ "$select": _SELECT,
+ },
+ headers={"Prefer": 'outlook.body-content-type="text"'},
+ )
+ out = []
+ for item in data.get("value", []):
+ msg = self._parse_message(item)
+ if msg and msg.from_email != me:
+ out.append(msg)
+ return out
+
+ @staticmethod
+ def _parse_message(item: dict) -> InboundMessage | None:
+ sender = ((item.get("from") or {}).get("emailAddress") or {})
+ from_email = (sender.get("address") or "").strip().lower()
+ if not from_email:
+ return None
+ subject = item.get("subject") or ""
+ headers = {
+ (h.get("name") or "").lower(): h.get("value") or ""
+ for h in item.get("internetMessageHeaders") or []
+ }
+ body = ((item.get("body") or {}).get("content") or "")
+ return InboundMessage(
+ provider_id=item.get("id", ""),
+ from_email=from_email,
+ subject=subject,
+ body=body[:5000],
+ message_id=item.get("internetMessageId", ""),
+ in_reply_to=headers.get("in-reply-to", ""),
+ # The Graph id: what createReply needs to answer this message.
+ thread_ref=item.get("id", ""),
+ date=item.get("receivedDateTime", ""),
+ is_bounce=looks_like_bounce(from_email, subject),
+ headers=headers,
+ )
+
+ async def test_connection(self) -> tuple[bool, str]:
+ if not self.client_id:
+ return False, "M365_CLIENT_ID missing from .env"
+ if not _load_token():
+ return False, "Not authorized yet — run 'harvey microsoft auth'"
+ try:
+ me = await self._check_identity()
+ await self._request(
+ "GET", "/me/mailFolders/inbox/messages",
+ params={"$top": "1", "$select": "id"},
+ )
+ except GraphError as e:
+ return False, str(e)[:300]
+ return True, f"Connected as {me}"
+
+
+def _pkce_pair() -> tuple[str, str]:
+ verifier = secrets.token_urlsafe(64)[:96]
+ challenge = base64.urlsafe_b64encode(
+ hashlib.sha256(verifier.encode()).digest()
+ ).decode().rstrip("=")
+ return verifier, challenge
+
+
+class _LoopbackServer(http.server.HTTPServer):
+ allow_reuse_address = True
+
+
+class _LoopbackServerV6(_LoopbackServer):
+ address_family = socket.AF_INET6
+
+
+def run_auth_flow(client_id: str, tenant: str = "") -> bool:
+ """One-time sign-in (authorization code + PKCE, loopback redirect).
+ Blocks until the browser round-trip completes."""
+ import threading
+ import urllib.parse
+
+ if not client_id:
+ print(" Set M365_CLIENT_ID (and M365_TENANT_ID) in .env first.")
+ print(" (entra.microsoft.com → App registrations → New registration)")
+ return False
+ tenant = tenant or "organizations"
+
+ state = secrets.token_urlsafe(16)
+ verifier, challenge = _pkce_pair()
+ redirect_uri = f"http://localhost:{LOOPBACK_PORT}"
+ auth_url = f"{LOGIN}/{tenant}/oauth2/v2.0/authorize?" + urllib.parse.urlencode({
+ "client_id": client_id,
+ "response_type": "code",
+ "redirect_uri": redirect_uri,
+ "response_mode": "query",
+ "scope": SCOPE,
+ "state": state,
+ "code_challenge": challenge,
+ "code_challenge_method": "S256",
+ "prompt": "select_account",
+ })
+
+ result: dict = {}
+ done = threading.Event()
+
+ class Handler(http.server.BaseHTTPRequestHandler):
+ def do_GET(self):
+ query = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+ if query.get("state", [""])[0] != state:
+ self.send_response(400); self.end_headers()
+ return
+ result["code"] = query.get("code", [""])[0]
+ result["error"] = (query.get("error_description") or query.get("error") or [""])[0]
+ self.send_response(200)
+ self.send_header("Content-Type", "text/html")
+ self.end_headers()
+ self.wfile.write(
+ b"<h2>Harvey is connected to Microsoft 365.</h2>You can close this tab.")
+ done.set()
+
+ def log_message(self, *args):
+ pass
+
+ # "localhost" is both 127.0.0.1 and ::1, and browsers differ in which
+ # they try: listen on both (loopback only), or the redirect can land on
+ # the one nobody is listening to.
+ servers = [_LoopbackServer(("127.0.0.1", LOOPBACK_PORT), Handler)]
+ try:
+ servers.append(_LoopbackServerV6(("::1", LOOPBACK_PORT), Handler))
+ except OSError:
+ pass # no IPv6 loopback on this machine
+ for server in servers:
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+
+ print(f"\n Opening browser for Microsoft sign-in...\n {auth_url}\n")
+ webbrowser.open(auth_url)
+ finished = done.wait(timeout=300)
+ for server in servers:
+ server.shutdown()
+ server.server_close()
+ if not finished:
+ print(" Timed out waiting for the browser round-trip.")
+ return False
+
+ if result.get("error") or not result.get("code"):
+ print(f" Authorization failed: {result.get('error') or 'no code returned'}")
+ return False
+
+ resp = httpx.post(_token_url(tenant), data={
+ "client_id": client_id,
+ "grant_type": "authorization_code",
+ "code": result["code"],
+ "redirect_uri": redirect_uri,
+ "code_verifier": verifier,
+ "scope": SCOPE,
+ }, timeout=30)
+ if resp.status_code != 200:
+ print(f" Token exchange failed ({resp.status_code}): {resp.text[:300]}")
+ return False
+ data = resp.json()
+ if not data.get("refresh_token"):
+ print(" Microsoft returned no refresh token (offline_access missing?).")
+ return False
+ _save_token({
+ "refresh_token": data["refresh_token"],
+ "tenant": tenant,
+ "scope": data.get("scope", SCOPE),
+ "obtained_at": int(time.time()),
+ })
+ print(f" ✓ Microsoft 365 authorized. Token stored at {TOKEN_FILE}")
+ return True
diff --git a/tests/test_microsoft.py b/tests/test_microsoft.py
new file mode 100644
index 0000000..65dc192
--- /dev/null
+++ b/tests/test_microsoft.py
@@ -0,0 +1,255 @@
+"""Microsoft 365 provider: token rotation, draft-then-send, threaded replies,
+reading the inbox without touching it, and failing loudly."""
+
+import json
+
+import httpx
+import pytest
+
+from harvey.integrations import microsoft
+from harvey.integrations.microsoft import GraphError, MicrosoftProvider
+
+
+class Env:
+ m365_client_id = "client-123"
+ m365_tenant_id = "tenant-abc"
+
+
+class Graph:
+ """A tiny fake of the Graph + login endpoints Harvey uses."""
+
+ def __init__(self):
+ self.requests = []
+ self.inbox = []
+ self.fail = {} # (method, path suffix) -> status
+ self.drafts = 0
+
+ def __call__(self, request: httpx.Request):
+ self.requests.append(request)
+ path = request.url.path
+ method = request.method
+ for (m, suffix), status in self.fail.items():
+ if m == method and path.endswith(suffix):
+ return httpx.Response(status, json={"error": {"code": "boom"}})
+ if request.url.host == "login.microsoftonline.com":
+ return httpx.Response(200, json={
+ "access_token": "at-1", "expires_in": 3600, "refresh_token": "rt-2",
+ })
+ if path == "/v1.0/me":
+ return httpx.Response(200, json={"mail": "[email protected]"})
+ if path == "/v1.0/me/messages" and method == "POST":
+ self.drafts += 1
+ return httpx.Response(201, json={
+ "id": f"draft{self.drafts}",
+ "internetMessageId": f"<draft{self.drafts}@sender.example>",
+ "conversationId": "conv1",
+ })
+ if path.endswith("/createReply"):
+ self.drafts += 1
+ return httpx.Response(201, json={
+ "id": f"reply{self.drafts}",
+ "internetMessageId": f"<reply{self.drafts}@sender.example>",
+ "conversationId": "conv9",
+ })
+ if method == "PATCH" or method == "DELETE":
+ return httpx.Response(200 if method == "PATCH" else 204, json={} if method == "PATCH" else None)
+ if path.endswith("/send"):
+ return httpx.Response(202)
+ if path == "/v1.0/me/mailFolders/inbox/messages":
+ return httpx.Response(200, json={"value": self.inbox})
+ return httpx.Response(404, json={"error": {"code": "notFound"}})
+
+ def calls(self):
+ return [(r.method, r.url.path) for r in self.requests
+ if r.url.host == "graph.microsoft.com"]
+
+
+def graph(tmp_path, monkeypatch):
+ token_file = tmp_path / "m365_token.json"
+ token_file.write_text(json.dumps({"refresh_token": "rt-1", "tenant": "tenant-abc"}))
+ monkeypatch.setattr(microsoft, "TOKEN_FILE", token_file)
+ return Graph()
+
+
+def provider(graph):
+ return MicrosoftProvider(config=None, env=Env(), transport=httpx.MockTransport(graph))
+
+
+async def test_refresh_token_rotates_and_is_saved(graph):
+ p = provider(graph)
+ await p._token()
+
+ [login] = [r for r in graph.requests if r.url.host == "login.microsoftonline.com"]
+ assert login.url.path == "/tenant-abc/oauth2/v2.0/token"
+ form = dict(x.split("=", 1) for x in login.content.decode().split("&"))
+ assert form["grant_type"] == "refresh_token" and form["refresh_token"] == "rt-1"
+ assert "client_secret" not in form # public client
+ saved = json.loads(microsoft.TOKEN_FILE.read_text())
+ assert saved["refresh_token"] == "rt-2"
+ assert microsoft.TOKEN_FILE.stat().st_mode & 0o777 == 0o600
+
+
+async def test_new_email_is_drafted_then_sent_as_plain_text(graph):
+ result = await provider(graph).send_email("[email protected]", "booking", "Hi Jane.")
+
+ assert result.ok
+ assert result.message_id == "<[email protected]>" # bounces match on this
+ assert graph.calls() == [
+ ("GET", "/v1.0/me"), # which mailbox the token belongs to
+ ("POST", "/v1.0/me/messages"),
+ ("POST", "/v1.0/me/messages/draft1/send"),
+ ]
+ [draft] = [json.loads(r.content) for r in graph.requests
+ if r.method == "POST" and r.url.path == "/v1.0/me/messages"]
+ assert draft["body"] == {"contentType": "Text", "content": "Hi Jane."}
+ assert draft["toRecipients"] == [{"emailAddress": {"address": "[email protected]"}}]
+
+
+async def test_reply_is_threaded_with_create_reply(graph):
+ result = await provider(graph).send_email(
+ "[email protected]", "Re: booking", "Tuesday works.",
+ thread_ref="AAMk-their-message", in_reply_to="<[email protected]>",
+ )
+
+ assert result.ok and result.message_id == "<[email protected]>"
+ assert graph.calls() == [
+ ("GET", "/v1.0/me"),
+ ("POST", "/v1.0/me/messages/AAMk-their-message/createReply"),
+ ("PATCH", "/v1.0/me/messages/reply1"),
+ ("POST", "/v1.0/me/messages/reply1/send"),
+ ]
+ [patch] = [json.loads(r.content) for r in graph.requests if r.method == "PATCH"]
+ assert patch["body"]["content"] == "Tuesday works."
+ assert patch["toRecipients"][0]["emailAddress"]["address"] == "[email protected]"
+
+
+async def test_reply_to_a_deleted_message_is_sent_unthreaded(graph):
+ graph.fail[("POST", "/createReply")] = 404
+ result = await provider(graph).send_email(
+ "[email protected]", "Re: booking", "Tuesday works.", thread_ref="gone",
+ )
+
+ assert result.ok
+ assert ("POST", "/v1.0/me/messages") in graph.calls()
+
+
+async def test_failed_send_deletes_the_draft(graph):
+ graph.fail[("POST", "/send")] = 500
+ result = await provider(graph).send_email("[email protected]", "booking", "Hi.")
+
+ assert not result.ok
+ assert ("DELETE", "/v1.0/me/messages/draft1") in graph.calls()
+
+
+async def test_inbox_is_read_without_changing_it(graph):
+ graph.inbox = [
+ {"id": "m1", "subject": "Re: booking",
+ "from": {"emailAddress": {"address": "[email protected]"}},
+ "body": {"contentType": "text", "content": "Sounds good."},
+ "internetMessageId": "<[email protected]>", "conversationId": "c1",
+ "receivedDateTime": "2026-10-14T15:00:00Z",
+ "internetMessageHeaders": [{"name": "In-Reply-To", "value": "<[email protected]>"}]},
+ {"id": "m2", "subject": "Undeliverable: booking",
+ "from": {"emailAddress": {"address": "[email protected]"}},
+ "body": {"content": "couldn't be delivered"},
+ "internetMessageHeaders": [{"name": "In-Reply-To", "value": "<[email protected]>"}]},
+ {"id": "m3", "subject": "note to self",
+ "from": {"emailAddress": {"address": "[email protected]"}}, "body": {"content": "x"}},
+ ]
+ replies = await provider(graph).get_replies()
+
+ assert [m.provider_id for m in replies] == ["m1", "m2"] # own mail skipped
+ jane, bounce = replies
+ assert jane.from_email == "[email protected]"
+ assert jane.body == "Sounds good."
+ assert jane.thread_ref == "m1" # what createReply needs
+ assert jane.in_reply_to == "<[email protected]>"
+ assert bounce.is_bounce and bounce.in_reply_to == "<[email protected]>"
+
+ listing = [r for r in graph.requests if r.url.path.endswith("/inbox/messages")][0]
+ assert listing.headers["Prefer"] == 'outlook.body-content-type="text"'
+ assert "receivedDateTime ge" in listing.url.params["$filter"]
+ assert all(m in ("GET",) for m, _ in graph.calls()) # nothing marked read
+
+
+async def test_unreadable_inbox_raises_so_sends_are_held(graph):
+ graph.fail[("GET", "/inbox/messages")] = 503
+ with pytest.raises(GraphError):
+ await provider(graph).get_replies()
+
+
+async def test_not_authorized_raises(graph):
+ microsoft.TOKEN_FILE.unlink()
+ p = provider(graph)
+ assert not p.is_configured()
+ with pytest.raises(GraphError, match="harvey microsoft auth"):
+ await p.get_replies()
+
+
+async def test_handler_holds_sends_when_graph_is_down(graph, tmp_path):
+ """End to end with the handler: a Graph outage is a failed read."""
+ import os
+ from harvey.agents.handler import Handler
+ from harvey.state import StateManager
+ from tests.test_outbox_native import Cfg, StubBrain
+
+ class E(Env):
+ instantly_api_key = ""
+
+ state = StateManager(os.path.join(tmp_path, "t.db"))
+ await state.init_db()
+ handler = Handler(brain=StubBrain(), state=state, config=Cfg(), env=E())
+ handler.provider = provider(graph)
+ graph.fail[("GET", "/inbox/messages")] = 500
+
+ assert await handler.run() is False
+
+
+def test_registry_builds_the_microsoft_provider():
+ from harvey.integrations.mail_provider import NATIVE_PROVIDERS, get_mail_provider
+ from tests.test_outbox_native import Cfg
+
+ class MsCfg(Cfg):
+ class channels(Cfg.channels):
+ class email(Cfg.channels.email):
+ provider = "microsoft"
+
+ assert "microsoft" in NATIVE_PROVIDERS
+ assert isinstance(get_mail_provider(MsCfg(), Env()), MicrosoftProvider)
+
+
+async def test_wrong_account_is_refused(graph):
+ class C:
+ class persona:
+ email = "[email protected]"
+
+ p = MicrosoftProvider(config=C(), env=Env(), transport=httpx.MockTransport(graph))
+ # The fake Graph says the token belongs to [email protected]
+ result = await p.send_email("[email protected]", "booking", "Hi.")
+ assert not result.ok and "[email protected]" in result.error
+ assert ("POST", "/v1.0/me/messages") not in graph.calls()
+ with pytest.raises(GraphError, match="signed in as [email protected]"):
+ await p.get_replies()
+ ok, detail = await p.test_connection()
+ assert not ok and "persona.email" in detail
+
+
+def test_pkce_challenge_matches_verifier():
+ import base64
+ import hashlib
+
+ verifier, challenge = microsoft._pkce_pair()
+ assert 43 <= len(verifier) <= 128
+ expected = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest())
+ assert challenge == expected.decode().rstrip("=")