Diff: services/service-email.es
From 1ef6cba to 1ef6cba
+0 / −1 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "service-email: Email Transport Bridge" | title: "service-email: Email Transport Bridge" |
| slug: service-email | slug: service-email |
| category: services | category: services |
| type: topic | type: topic |
| quality: complete | quality: complete |
| short_description: "service-email is the Ring 1 boundary-ingest service that polls a Microsoft 365 mailbox via the Microsoft Graph API, extracts raw email payloads, and writes them to a local queue without interpreting their content." | short_description: "service-email is the Ring 1 boundary-ingest service that polls a Microsoft 365 mailbox via the Microsoft Graph API, extracts raw email payloads, and writes them to a local queue without interpreting their content." |
| status: active | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| last_edited: 2026-04-30 | last_edited: 2026-04-30 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| cites: [] | cites: [] |
| paired_with: service-email.es.md | paired_with: service-email.es.md |
| --- | --- |
| # service-email: Email Transport Bridge | |
| > service-email is the Ring 1 boundary-ingest service that polls a Microsoft 365 mailbox via the Microsoft Graph API, extracts raw email payloads, and writes them to a local queue without interpreting their content. | > service-email is the Ring 1 boundary-ingest service that polls a Microsoft 365 mailbox via the Microsoft Graph API, extracts raw email payloads, and writes them to a local queue without interpreting their content. |
| **service-email** is a Ring 1 boundary-ingest service in the PointSav three-ring architecture. It functions as a transport interceptor: it authenticates against the Microsoft Graph API, retrieves inbound email messages, and writes the raw payloads to a local temporary queue for downstream processing by Ring 2 services. The service deliberately maintains no knowledge of message content or semantic meaning — its only job is reliable, authenticated extraction across the cloud boundary. | **service-email** is a Ring 1 boundary-ingest service in the PointSav three-ring architecture. It functions as a transport interceptor: it authenticates against the Microsoft Graph API, retrieves inbound email messages, and writes the raw payloads to a local temporary queue for downstream processing by Ring 2 services. The service deliberately maintains no knowledge of message content or semantic meaning — its only job is reliable, authenticated extraction across the cloud boundary. |
| ## Architectural Baseline | ## Architectural Baseline |
| The service addresses a structural limitation of IMAP and SMTP: both protocols require maintaining a persistent connection and expose message state management through legacy mechanisms. service-email uses OAuth2 authentication against the Microsoft Graph API instead, making each polling cycle a discrete, authenticated HTTP exchange. This approach confines the cloud-trust boundary to a single well-defined point in the pipeline. | The service addresses a structural limitation of IMAP and SMTP: both protocols require maintaining a persistent connection and expose message state management through legacy mechanisms. service-email uses OAuth2 authentication against the Microsoft Graph API instead, making each polling cycle a discrete, authenticated HTTP exchange. This approach confines the cloud-trust boundary to a single well-defined point in the pipeline. |
| ## Ring and Role | ## Ring and Role |
| service-email occupies **Ring 1 — Boundary Ingest** in the three-ring architecture. Ring 1 services are per-tenant and implement an MCP (Model Context Protocol) server interface. Each Ring 1 service handles one inbound channel; service-email handles the email channel. Other Ring 1 services cover filesystem, people records, and structured input. No Ring 1 service processes content semantically — that is Ring 2's scope. | service-email occupies **Ring 1 — Boundary Ingest** in the three-ring architecture. Ring 1 services are per-tenant and implement an MCP (Model Context Protocol) server interface. Each Ring 1 service handles one inbound channel; service-email handles the email channel. Other Ring 1 services cover filesystem, people records, and structured input. No Ring 1 service processes content semantically — that is Ring 2's scope. |
| ## Structural Organization of Components | ## Structural Organization of Components |
| The extraction loop operates in three steps: | The extraction loop operates in three steps: |
| 1. **Authenticate.** An OAuth2 handshake against the Microsoft Graph API produces a bearer token scoped to mail read operations for the configured mailbox. | 1. **Authenticate.** An OAuth2 handshake against the Microsoft Graph API produces a bearer token scoped to mail read operations for the configured mailbox. |
| 2. **Extract.** The service polls for unread messages (excluding drafts stored only in the local UI). It retrieves the raw OData JSON payload for each message found. | 2. **Extract.** The service polls for unread messages (excluding drafts stored only in the local UI). It retrieves the raw OData JSON payload for each message found. |
| 3. **Write and mark.** The payload is written to the local temporary queue at `assets/tmp-maildir/`. The service then issues an authorized `PATCH` request to mark each extracted message as read on the remote server, preventing re-extraction on the next polling cycle. | 3. **Write and mark.** The payload is written to the local temporary queue at `assets/tmp-maildir/`. The service then issues an authorized `PATCH` request to mark each extracted message as read on the remote server, preventing re-extraction on the next polling cycle. |
| The service surrenders execution to the downstream parser (`service-extraction`) once the payload lands in the queue. No parsing, classification, or content inspection occurs within service-email. | The service surrenders execution to the downstream parser (`service-extraction`) once the payload lands in the queue. No parsing, classification, or content inspection occurs within service-email. |
| ## Configuration | ## Configuration |
| | Parameter | Purpose | | | Parameter | Purpose | |
| |---|---| | |---|---| |
| | OAuth2 credentials | Client ID and secret for the registered Microsoft Graph application | | | OAuth2 credentials | Client ID and secret for the registered Microsoft Graph application | |
| | Mailbox address | The Microsoft 365 mailbox to monitor | | | Mailbox address | The Microsoft 365 mailbox to monitor | |
| | Poll interval | How often the extraction loop runs | | | Poll interval | How often the extraction loop runs | |
| | Queue path | Local filesystem path for the temporary maildir queue | | | Queue path | Local filesystem path for the temporary maildir queue | |
| ## See Also | ## See Also |
| - [[service-extraction]] | - [[service-extraction]] |
| - [[service-people]] | - [[service-people]] |
| - [[service-slm]] | - [[service-slm]] |
| - [[trajectory-substrate]] | - [[trajectory-substrate]] |
| ## References | ## References |
| - §XI — Ring 1 boundary-ingest architecture | - §XI — Ring 1 boundary-ingest architecture |
| - `pointsav-monorepo/service-email/` — implementation crate | - `pointsav-monorepo/service-email/` — implementation crate |
| - SYS-ADR-07 — structured data never routes through AI (governs downstream handling of service-email output) | - SYS-ADR-07 — structured data never routes through AI (governs downstream handling of service-email output) |
| --- | --- |
| *Copyright © 2026 Woodfine Capital Projects Inc. Licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).* | *Copyright © 2026 Woodfine Capital Projects Inc. Licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).* |
| *Woodfine Capital Projects™, Woodfine Management Corp™, PointSav Digital Systems™, Totebox Orchestration™, and Totebox Archive™ are trademarks of Woodfine Capital Projects Inc., used in Canada, the United States, Latin America, and Europe. All other trademarks are the property of their respective owners.* | *Woodfine Capital Projects™, Woodfine Management Corp™, PointSav Digital Systems™, Totebox Orchestration™, and Totebox Archive™ are trademarks of Woodfine Capital Projects Inc., used in Canada, the United States, Latin America, and Europe. All other trademarks are the property of their respective owners.* |