Skip to content

Outlook Ingestion on macOS

This guide shows how to pull selected Microsoft Outlook messages into SecondBrain on a local Mac.

The intended workflow is:

  1. Mark messages in Outlook with a category like SecondBrain.
  2. Optionally flag them for follow-up.
  3. Run an outlook_mail integration in SecondBrain.
  4. Let SecondBrain write markdown artifacts and ingest them into search/indexing.

What this uses

  • Outlook on macOS for message selection
  • An Outlook/Microsoft Graph MCP server reachable from SecondBrain
  • SecondBrain's sb integrations add-outlook-mail command

SecondBrain will write artifacts under:

  • vault/02_sources/outlook_mail/<integration_name>/

1. Configure an Outlook mail MCP server

You need an MCP server that can search Outlook mail.

Two supported shapes:

  • Microsoft Agent 365 official server: mcp_MailTools
  • A community Outlook/Graph MCP server that exposes a compatible mail search tool

Edit your config at ~/.config/secondbrain/config.yaml.

Example for the Microsoft Agent 365 mail server:

control_plane:
  mcp_servers:
    - name: mcp_MailTools
      protocol: mcp
      protocol_version: "2025-11-25"
      transport: streamable_http
      url: "https://agent365.svc.cloud.microsoft/mcp/environments/<envId>/servers/mcp_MailTools"
      auth_token_env: OUTLOOK_MCP_TOKEN
      enabled: true

If you are using a community MCP server instead, use that server name and URL in the same mcp_servers section.

2. Export the auth token in your shell

SecondBrain reads the MCP auth token from the environment variable referenced by auth_token_env.

Example:

export OUTLOOK_MCP_TOKEN="..."

If you launch sb from a terminal, export the token in that shell first.

3. Mark messages in Outlook

In Outlook on your Mac:

  1. Create a category named SecondBrain.
  2. Apply that category to any message you want to ingest.
  3. Optionally flag the same messages if you want a tighter selector.

Recommended convention:

  • Category SecondBrain means "eligible for ingestion"
  • Flagged means "high-priority ingestion"

4. Create the SecondBrain integration

Create an integration that selects those messages.

Example:

sb integrations add-outlook-mail outlook_flagged \
  --server mcp_MailTools \
  --query "follow up OR decision OR action" \
  --category SecondBrain \
  --flagged-only \
  --max-results 200 \
  --json

Meaning of the flags:

  • --server mcp_MailTools: use the configured Outlook mail MCP server
  • --query ...: pass a search query to the mail server
  • --category SecondBrain: keep only messages tagged with that Outlook category
  • --flagged-only: keep only flagged messages
  • --max-results 200: retrieve more messages before local filtering

Important:

  • Category and flag filters are applied locally after retrieval.
  • If your mailbox is large or your query is broad, increase --max-results.
  • At least one of --query, --category, or --flagged-only must be provided.

5. Test the integration

Run a preflight test:

sb integrations test outlook_flagged --json

This checks:

  • integration status
  • configured MCP server presence
  • selector presence
  • a dry-run sync probe

6. Preview the messages before writing anything

Dry-run the sync first:

sb integrations sync outlook_flagged --dry-run --json

Useful fields in the result:

  • total_files: matched messages after filtering
  • candidate_files: messages that would produce new or changed markdown artifacts

7. Run the real ingestion

When the dry-run looks right:

sb integrations sync outlook_flagged --json

This does three things:

  1. Pulls matching mail through MCP
  2. Writes one markdown artifact per message under vault/02_sources/outlook_mail/outlook_flagged/
  3. Runs the normal SecondBrain ingest/index path on those files

8. Inspect the generated artifacts

Open the generated folder:

  • vault/02_sources/outlook_mail

Each message artifact contains:

  • source metadata
  • sender
  • received timestamp
  • category list
  • flag state
  • web link if present
  • raw message JSON

9. Run it on a cadence

If you want this to become part of your normal intake flow, leave the integration active and run due integrations periodically:

sb integrations run-due --json

Or run the integration watch loop:

sb integrations watch --json

If you want a tighter manual workflow, just run:

sb integrations sync outlook_flagged

after marking messages in Outlook.

Suggested daily workflow

  1. In Outlook, apply category SecondBrain
  2. Flag anything urgent
  3. Run sb integrations sync outlook_flagged
  4. Use the ingested material from search, briefing, and drafting flows

Troubleshooting

Integration test says the server is not configured

Check ~/.config/secondbrain/config.yaml and make sure:

  • the server name matches --server
  • enabled: true is set
  • the URL is present

Sync returns zero messages

Check:

  • Outlook category name matches exactly
  • the messages are actually flagged if using --flagged-only
  • your query is not too restrictive
  • --max-results is large enough

MCP auth failures

Check:

  • the token env var exists in the same shell session
  • the token is valid for the configured server
  • the MCP server itself is reachable