Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
What it is
The core of the Email feature: threads/messages orchestration, scheduling and reminders/followups, calendar-invitation extraction, and the AI email tools — hexagonal, heavily feature-gated.
Start here
src/domain/service.rs+src/domain/ports.rs: the domain service and the traits its adapters implement.src/inbound/axum.rs: HTTP routes (featureaxum);src/inbound/toolset.rs: the AI email tools (featureai_tools).src/outbound/email_pg_repo.rs,src/outbound/invitation_pg.rs: Postgres adapters (featureoutbound);src/outbound/email_service_http.rs: calls intoemail_service;src/outbound/s3_draft_attachment_storage.rs: staged draft attachments (features3);src/outbound/sqs_enqueuer.rs: theEmailMessageEnqueueradapter forsqs_client::SQS(featuresqs).
Scope
- Owns: email/thread domain logic, scheduled delivery, reminders/followups,
calendar invitation extraction and resolution, adding a forwarded
event (
METHOD:PUBLISH) to the viewer's calendar (domain/invitation_import.rs), and forwarding one of the viewer's events from the inbox holding their copy (domain/event_forward.rs): that same file, or, for an organizer outside Google, a real invitation (METHOD:REQUEST) sent as the message's calendar body to the recipients and the organizer, whichever the calendar decides. - Not here: raw provider API calls →
email_api_client; HTML parsing/sanitization →email_utils; SQLx queries over email tables →email_db_client.
Boundaries
- Depends on:
entity_access,entity_access_management,email_utils,crm,frecency,item_filters,lexical_client,macro_event_broker,calendar_events(optional, featurecalendar_invitations),sqs_client(optional, featuresqs; it must not depend back on this crate). - Used by: many crates and services, including
ai_tools,graphql_email,teams,databases_sql,attention_feed,calendar_service,email_service,email_scheduled_handler,search_processing_service.
Recipes
- Add a route:
src/inbound/axum.rs→src/domain/service.rs→ the relevantsrc/outbound/*.rsadapter. - Add an AI tool:
src/inbound/toolset.rs→src/domain/service.rs. - Add a feature-gated adapter: add the optional dependency and a feature in
Cargo.toml→src/outbound/<name>.rs→ declare it insrc/outbound.rs.
Checks
cargo test -p email --all-features(SQLX_OFFLINEunset; theoutboundfeature's tests need a local MacroDB —just setup_macrodb).
Gotchas
The send route refuses an agent's program (
refuse_program_send, 403), and the schedule route admits one only with a quoteduser_confirmation: a program sends through a session review, the harness's confirmed send (SendEmail/SendConfirmedEmail), or a confirmed draft schedule. Keep any new route that sends or schedules mail behind the same check.Focus's
decideandsignalsare versioned: bumpFOCUS_RULE_VERSIONindomain/focus/rule.rswhen either changes, or stored rows keep the old verdict until new mail arrives. The worker's sweep re-decides older rows from their storedscores, without calling Jev.rule/experiment.csvholds the expected verdicts for 643 real threads; report how far a rule change moves them. A new question's answer is#[serde(default)], so storedscoresstill decode, and needs no bump when it decides nothing at 0.Nothing reclassifies a Focus thread as it ages, so
focus_pgapplies the wait and the calendar hold when it reads:awaiting_replyandcalendar_hold_untilare stored,FOLLOW_UP_AFTER_DAYSand the time are passed in.focus_thread_idsandfocus_for_threadsrestate the same tests; change both.focus_for_threadsalso moves importance when it reads, withdomain/focus/importance.rs:importance_rateis stored and the clock starts atclassified_message_ts. The storedimportanceis the base, and the floors indomain/focus/rule.rsonly set that base. Importance never decides membership, sofocus_thread_idsdoesn't read it.In Focus, Calendar only means a change whose event isn't over: the read sets it from
calendar_hold_until, and the storedcategoryis what the thread reads as afterwards. A stored Calendar is a new invite or RSVP left out, andNEW_INVITES_STAY_OUTindomain/focus/rule.rsis the switch for new invites.stale_threadsrestatesdomain/focus/calendar.rs's test for a change in SQL; change both.A Focus thread's
due_onis read when new mail is classified, only for a thread withis_focusorawaiting_reply, and never on the re-decide path: that path keeps the stored date and calls no model, sosavewrites back whatStoredClassificationread. A failed or timed-out read stores no date and never fails the classification.input.rsgives the extractor each of the latest messages' own words, never quoted history, so a relative date counts from the message that wrote it. A message's day is its writer's: the owner's own mail in their calendar zone, anyone else's at itsDateheader's offset, each falling back on the other, then UTC. Store no mail text or extracted span.A thread holding only the owner's sent mail stays out of Focus on purpose: it has
inbox_visiblefalse, which the client reads as Done, Mark Done cannot change it, and there is no inbound mail for the rule to judge.Treat DATE property literals as non-matches; apply ordinary boolean negation and keep non-date email filtering unchanged.
All Mail excludes present messages in spam/junk or trash before pagination; canonical cached previews and non-draft baselines use the same rule for Gmail labels and Outlook mailbox facts. Mixed threads show their latest eligible message. Synced Macro drafts in junk/trash must not advance All Mail timestamps. Filtered and unfiltered All Mail share the dynamic builder and its per-inbox ordered, limited scans; do not add a separate whole-mailbox sort.
Spam and Trash seed candidates from indexed provider labels/folder state plus pending positive moves, then recheck canonical mailbox facts before pagination. Order by the latest matching message date; metadata touches and unrelated replies must not move folder rows. Only Trash relaxes the default trash exclusion.
Restore Outlook junk drafts to Drafts without Inbox membership; continue rejecting attempts to mark clean drafts as junk.
Reconcile deferred message deletion before claiming scheduled work; unresolved sends retain their message, attachments, and delivery job.
Durable send admission supports Gmail and Outlook; Outlook delivery stays with its provider coordinator.
Carry the captured
draft_generationthrough every draft mutation; advance it on send acceptance/cancellation under the message lock and preserve attempt tombstones after message deletion.Gmail thread label writes stage each thread's DB change, then enqueue one provider write per inbox holding only the messages whose labels changed (
stage_thread_labels/commit_thread_label_writeindomain/service/thread_labels.rs); route new label actions through them.Recompute thread metadata inside staged Gmail SPAM/TRASH writes so restored All Mail previews, ordering, and signal state do not wait for the provider worker.
.emldownloads go throughdomain/message_source.rs, which authorizes like attachment reads and fetches the provider's original RFC 822 bytes (Gmailformat=raw, Graph$value); drafts and unsynced messages have no source.An attachment links to its document before the bytes reach storage, and a link stops sync from offering it again.
AttachmentReadService::documentstores the bytes again when a linked document is still awaiting its upload, and DSS signs a new upload for that reuse; DOCX is left out because it stays pending while it converts.Forwarded attachments register through
domain/draft_attachments.rsand resolve bytes throughdomain/attachment_access.rs; scheduled delivery also rechecks source inbox access indomain/forwarded_attachments.rs, including legacy jobs.A send with files staged before delivery goes through
StagedAttachmentSender(domain/service/attachments.rs): draft, staged attachment rows, then the send.DraftAttachmentSenderadds Macro documents as the source of those files forSendEmail; a caller that already holds the bytes, such as an event forward's.ics, usessend_with_files. ASourcedAttachmentwithis_inline(no Content-ID) is staged inline and becomes the message'stext/calendarbody at delivery (seeemail_api_client'sSendRequest::build_mime); use it only for an invitation's calendar part.Saved invitation snapshots are JSONB and never re-extracted.
recurrenceisNoneon snapshots saved before it was recorded, where a series looks like a single event, so those cannot be added to a calendar.The feature matrix (
ports/inbound/outbound/http_client/s3/gmail_token/ai_tools/attachment/calendar_invitations/axum) gates most modules; checkCargo.toml's[features]block for which one a new dependency belongs under before wiring it in.domain/ports.rsdefines the traits adapters implement — call through the domain service, never an outbound adapter directly from another crate.EmailRepo::stage_thread_label_changereads which messages change, applies the change and marks the changed provider messages (exactly whatcommit_thread_label_writeenqueues) in one transaction holding the thread's label-write lock. The enqueue carries the write's id; a group that can't be queued goes back throughEmailRepo::revert_staged_label_change, which restores the state an older write still on its way left (or the original), never a newer write's change.A reply target outside the caller's inboxes is admitted only through
SharedThreadReplyAccess(edit access to its thread; wired indocument_storage_servicewithwith_shared_thread_replies). The reply starts a thread in the caller's inbox; other hosts keepNoSharedThreadReplies.Sender discovery authorizes the inbox first. Gmail aliases use the sender provider; Outlook exposes its verified primary address without a Gmail lookup.
Outlook links have no system label rows. Move a thread in or out of the inbox through
set_thread_inbox, and read Outlook inbox, trash, and junk state fromemail_message_mailbox_facts, never from labels.Read receipts (
domain/read_receipts.rs) own pixel policy for every send path: strip existing Macro pixels, track only HTML bodies, never block delivery on a tracking failure, and count opens only for sent messages. Tokens are stored per message, so a retried send or Outlook draft revision rebuilds the same URL; keep it that way or the draft fingerprints drift.Outlook sync telemetry (
domain/mailbox/telemetry.rs,progress.rs) is a contract the Outlook sync monitors ininfra/stacks/monitoringread: each claimed unit ofMailboxSyncServiceandMailboxProjectionServiceopens one rootoutlook.sync.*span (idle polls open none) and recordsoutlook.outcome,outlook.defer_reasonandoutlook.defer_secondsthroughrecord_done/record_deferred/record_failed. The mailbox loops log their own deferrals withlink_id(gate refusals at DEBUG), so the worker must not log them again. Add a new defer reason indefer_reason.Map database errors in
mailbox_pgwithdb_error(orwrapped_db_errorforemail_db_clientcalls) so the SQLSTATE reaches the log; keepMailboxError::Persistencefor stored data that cannot be decoded.MailboxError::Effect(defer_reason=effect) is for a projection effect that fails outside the database; email-service'sMailboxEffectsmaps its database steps withdatabase_failedand everything else withfailed."outlook import completed" fires from
settle_import(mailbox_pg.rs) under the link lock, once per import run: the folder-catalog stream'simport_completed_atis stamped when every folder is enumerated and no import row is left. A resync must resetimport_started_atandimport_completed_atand log "outlook import started", asoutbound/mailbox_pg/lifecycle.rsdoes.Import counts for the health snapshot stay in memory (
ImportTally) and are flushed once a minute toemail_mailbox_import_minutes; never write per imported message for telemetry.Outlook organization commands only run in their link's current
sync_generation. Anything that bumps it must rebind unfinished commands aspending, since claims skipconfirmingones while those still block later commands, as reconnect (email_servicemailbox_init.rs) andrebind_workinoutbound/mailbox_pg/lifecycle.rsdo; thread operations omit older generations.
Related
Rules:
.agents/rules/rust/architecture.mdPersist agent correlation with scheduled delivery and organization projection payloads, then restore it when publishing delayed activity.