mail-address-semantics/docs/reuse-surface.md

Reuse surface

This repository is the email building block for a multimodal communication framework that is yet to be designed (INTENT.md, Mode reference implementation). This page says what such a framework can depend on, and how stable each part is.

Depend on these

Part	Where	Stability
MAS address spec	mas-v0.1-spec/ (v0.1.1), mas-v0.2-spec/	v0.1.1 and v0.2 final (v0.2: 2026-10-19, two independent implementations)
Mode contract	mas-modes-v0.1-spec/	v0.1 final (2026-10-19), with two independent email sides. Changes are versioned; messages carry mas_modes_version
Gateway event	mas-modes-v0.1-spec/schema/mas-event-v0.1.schema.json	v0.1. Events carry mas_event_version
Conformance corpora	the bundles' conformance/	Normative for their version. Consume them unchanged
mas_core	parse (no I/O), discover (exact host), resolve (pure), generate / for_destination	Python reference library
mas_gateway	MTA pipe and provider webhook → event	Reference adapter. The event is the interface, not the code
Postfix profile	integrations/postfix/	Tested against Postfix 3.7 (tests/test_postfix_profile.py)

Integrating as an outside master

Configure the resource type as slave (mas_modes.email_mode.RoleConfig), point master_url at your system, set master_peer to your peer id, and exchange a key with the email operator. Every request in both directions is signed (CONTRACT.md section 7; mas_modes.signing, standard library only). You then:

• receive case.intake and case.message, each carrying a gateway event;
• answer case.assign with your own case id; email adopts it as TYPE=ID@domain;
• send replies with mail.send (in_reply_to a recorded message); principle 10 can refuse them, and over the deployment's one send cap they are held (held: true) instead of sent;
• decide per case on autonomous_send and transfers: block, or a mode webhook with that mode's peer. The peer must be one the email operator has a key for;
• own every timeout; end a handoff with handoff.cancel.

Integrating a mode

Implement the mode endpoint in CONTRACT.md: accept handoff.request, handoff.update and handoff.cancel only when signed by email, and post handoff.status, signed with your peer id, to exactly the status_url of that handoff (it carries a per-handoff token), with an increasing seq. Never send timed-out. mas_modes/stubs/callback.py is a complete example.

Ordinary product mail stays in email-connect

A product integrates with this facility by speaking the mode contract. It does not send MAS syntax through the email-connect transactional receiver. docs/mas-email-evidence-v0.1.json maps one gateway event into email-connect's evidence ceiling: the MX accepted the message, the message is a bounce, or the message is a non-automatic reply. The ceiling refuses the claim that a person read it. mas_gateway.email_evidence is the reference function. Tickets and statutes stay here. Templates and the product ledger stay in email-connect.

Examples only, not products

• examples/ticket_service/: the reference ticket service, used as the store for email-mastered cases.
• mas_modes/stubs/: the callback stub and the stub outside master. They never contact a person or a service.
• mas_modes/email_mode.py: the reference email side. It authenticates every peer (section 7), but it is single-process with SQLite, has no key rotation, and serves plain HTTP. Put it behind TLS before exposing it beyond loopback. The contract is the interface.