mail-address-semantics/mas-v0.1-spec/SPECIFICATION.md

Mail Address Semantics (MAS) v0.1

1. Status and normative language

This document defines MAS v0.1.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in BCP 14 when, and only when, they appear in uppercase.

MAS is an overlay on ordinary email addressing. It does not replace SMTP, establish identity, grant authority, define delivery topology, or create contractual commitments.

2. Scope

MAS v0.1 standardizes:

1. non-structural naming hints for people, actors, and functions;
2. structured resource targets using =;
3. facets using +;
4. an optional interaction profile using !;
5. exact-host statute discovery;
6. conservative equivalence behavior;
7. parser and generator conformance.

$ and ^ are reserved. They have no MAS v0.1 meaning.

3. Profiles

3.1 Profile P1 — Naming + Resource

P1 is the base v0.1 profile.

• . MAY be used as a person-style naming separator.
• - MAY be used as an actor-style naming separator.
• _ MAY be used as a function-style naming separator.
• = structurally binds a resource type to a resource identifier.
• + structurally adds one facet.

., -, and _ never classify an address by themselves.

3.2 Profile P2 — Interaction

P2 extends P1 with !.

TARGET!MODE requests that the addressed endpoint continue the interaction using MODE as the preferred interaction mode.

The address does not state which party initiates a non-email leg and does not constitute acceptance. Acceptance is external to the address.

3.3 Profile P3 — Economic

P3 is not defined in v0.1.

$ and ^ are reserved so that later profiles may define consideration and conditions without creating v0.1 parsing ambiguity.

4. Canonical ASCII local-part

The normative v0.1 machine grammar is the ABNF in grammar/mas-v0.1.abnf.

Canonical MAS v0.1 local-parts are unquoted ASCII dot-atom-like strings. Quoted local-parts and SMTPUTF8 local-parts are outside the canonical v0.1 machine grammar.

A MAS-aware implementation MAY transport such non-canonical email addresses as ordinary email, but MUST NOT claim that they are canonical MAS v0.1 addresses.

4.1 Target

A target is non-empty.

A target without = is opaque. Its semantic kind MUST NOT be inferred from ., -, or _.

If a target contains =, the target is a resource target:

• text before the first = is resource-type;
• text after the first = is resource-id;
• neither may be empty;
• subsequent = characters are resource-id data.

Examples:

ticket=PR42
invoice=RE=2026-4711

The second example has resource type invoice and resource id RE=2026-4711.

4.2 Facet

A facet is introduced by +.

+ MAY occur at most once and its value MUST be non-empty.

ticket=PR42+comments

The base target remains meaningful if a mail system strips the facet. MAS therefore treats facet loss as graceful degradation:

ticket=PR42+comments  ->  ticket=PR42

This is a semantic design property, not a preservation guarantee.

4.3 Interaction

An interaction preference is introduced by !.

! MAY occur at most once and its value MUST be non-empty.

P2 examples:

ticket!callback
ticket=PR42!web

Canonical operator order is:

TARGET [+FACET] [!INTERACTION]

Non-canonical order is invalid MAS syntax. A conforming parser MUST reject it and MUST NOT silently reorder it.

4.4 Composition rule

A parser implementing P2 MUST be able to parse the canonical combined form:

TARGET+FACET!INTERACTION

A v0.1 generator MUST NOT emit both + and ! in the same generated local-part. Implementations requiring both semantics SHOULD move one of them to external metadata.

This deliberately makes receivers slightly more tolerant than generators while retaining one canonical parse.

4.5 Reserved characters

Within canonical MAS v0.1 structured values:

+ ! $ ^

are reserved.

MAS v0.1 defines no escaping mechanism.

A percent-looking sequence such as %2B is ordinary data in v0.1 and MUST NOT be percent-decoded by the MAS parser.

5. Naming semantics

The following are style conventions only:

bernd.worsch@example.org       person-like
research-companion@example.org actor-like
invoice_ingest@example.org     function-like

They are not classifier rules.

Examples such as these remain opaque without statute metadata:

anne-marie.schmidt@example.org
support@example.org
happy-helper.v2@example.org

A domain registry or statute metadata determines semantic kind.

6. Resource semantics

A resource address identifies a communication endpoint associated with a resource.

ticket=PR42@example.org

It does not grant access to, mutation of, or knowledge about the resource.

Resource addressability and resource mutability are independent.

A closed resource MAY remain addressable. A receiver MAY archive the mail, reject mutation, return lifecycle information, or create a linked follow-up resource.

6.1 Resource types

A statute SHOULD enumerate resource types it recognizes.

Unknown resource types MUST NOT acquire application semantics solely because they use = syntax.

6.2 Resource identifiers

Resource identifiers are correlation identifiers, not credentials.

Predictable identifiers are enumerable. Deployments SHOULD prefer non-guessable external identifiers when addresses are widely forwarded or exposed and enumeration is undesirable.

High entropy does not transform an identifier into an authorization token.

7. Interaction semantics

The recommended P2 initiation pattern is:

ticket!callback@great-service.example

followed by creation or disclosure of a resource:

ticket=GS-41872@great-service.example

The first address expresses interaction intent. The second names the resource created or selected by the service.

!callback is a preference/request, not a command, guarantee, SLA, or proof of acceptance.

8. Address equivalence

MAS does not impose case folding, dot folding, alias folding, or Unicode normalization in the absence of a successfully discovered statute.

If no statute is available, comparison is exact over the presented canonical ASCII local-part.

A statute MAY declare:

• exact local-part comparison;
• ascii-insensitive local-part comparison;
• dot folding for explicitly named address kinds or registry entries.

Dot folding MUST NOT be assumed by default.

A-label/U-label domain processing follows the underlying IDNA-aware HTTPS and DNS stack; MAS does not invent a second IDN mapping algorithm.

9. Unicode

SMTPUTF8 allows non-ASCII local-parts, but MAS v0.1 does not define a canonical Unicode local-part grammar.

A statute may declare unicode_local_part: true for experimental/private extensions. Such addresses MUST NOT be advertised as canonical MAS v0.1 machine syntax.

A future MAS version may define NFC normalization and Unicode comparison rules. v0.1 deliberately avoids doing so.

10. Statute discovery

The intended discovery URI is:

https://HOST/.well-known/mas

where HOST is the exact domain appearing after @.

For:

anna.mueller@acme.coulomb.social

the lookup host is:

acme.coulomb.social

A client MUST NOT walk to parent domains implicitly.

10.1 Registration caveat

RFC 8615 requires applications minting a new well-known URI suffix to register it for general Internet use.

Therefore /.well-known/mas is a candidate MAS discovery location in this draft. General public deployment SHOULD wait for the required registration. Controlled deployments MAY use it by agreement.

10.2 Retrieval

A statute-aware client:

1. constructs the HTTPS URI for the exact host;
2. performs an HTTPS GET;
3. requires a successful 2xx response;
4. requires a document conforming to the v0.1 statute schema;
5. verifies that namespace equals the queried host after normal domain-name canonicalization;
6. otherwise treats discovery as failed.

Discovery failure does not make the email address invalid. It means MAS semantics are unconfirmed.

10.3 Redirects

Clients SHOULD NOT follow cross-origin redirects for statute discovery.

Same-origin redirects MAY be followed.

A cross-origin policy transfer requires an explicit future delegation mechanism and is not defined in v0.1.

10.4 Inheritance

No parent-domain inheritance is implicit.

A child statute MAY contain an inherits URI. v0.1 inheritance is defaults-only:

• the parent document is fetched and validated independently;
• the child remains authoritative for its exact namespace;
• child values override inherited defaults;
• address registry entries are never inherited;
• resource types and interaction modes MAY be inherited;
• an inheritance cycle is invalid.

Implementations MAY choose not to implement inheritance. If they do not, they MUST ignore inherits rather than walking DNS parents.

11. Statute document

The normative schema is:

schema/mas-statute-v0.1.schema.json

The document describes:

• namespace and version;
• enabled profiles;
• accepted resource types;
• accepted interaction modes;
• equivalence policy;
• optional explicit address classification;
• optional inheritance.

The statute is metadata, not an authorization database.

12. Deliverability and rewriting

RFC-validity is weaker than ecosystem compatibility.

Mailing lists, SRS, VERP, gateways, web forms, validators, and security products may reject or rewrite otherwise legal local-parts.

Deployments MUST NOT assume preservation of MAS syntax through arbitrary rewriting.

+ is intentionally degradation-friendly: loss of a facet leaves the base target.

! is intended primarily for cooperating environments where all relevant systems are known to preserve it.

13. Length

An SMTP local-part is limited to 64 octets.

Generators MUST enforce the underlying transport limit after encoding.

Because the budget is small, v0.1 permits at most one facet and one interaction, and generators MUST NOT emit both simultaneously.

14. Security

1. MAS identifiers are not credentials.
2. Resource knowledge grants no authority.
3. Interaction selectors are not commands.
4. Dynamic addresses MUST define handling for bounces, unknown resources, expired resources, verification traffic, and abuse.
5. Receivers MUST avoid backscatter behavior.
6. Syntax-derived classifications MUST NOT substitute for statute metadata.
7. $ and ^ MUST NOT be rendered as payment/contract semantics in v0.1.
8. Authentication remains external to MAS.
9. A statute endpoint is security-relevant configuration and SHOULD be protected with the same care as other origin-wide metadata.

15. Conformance classes

15.1 P1 parser

A P1 parser:

• validates canonical ASCII syntax;
• parses resource binding and facet;
• rejects !, $, and ^ as MAS operators;
• does not classify opaque target kind by punctuation.

15.2 P2 parser

A P2 parser additionally parses !.

15.3 Generator

A generator:

• emits only canonical operator order;
• emits no empty component;
• emits no reserved operator within a value;
• emits at most one +;
• emits at most one !;
• MUST NOT emit both + and ! in v0.1;
• enforces the SMTP local-part octet limit.

15.4 Statute-aware implementation

A statute-aware implementation additionally validates the discovery document against the normative schema and applies only explicitly declared equivalence and classification rules.

16. Reserved future work

Future specifications may define:

• Unicode canonical grammar;
• escaping;
• signed statutes and signed semantic assertions;
• interaction negotiation;
• service discovery;
• economic request/offer/acceptance/settlement;
• condition tokens;
• IANA registrations.

17. One-sentence definition

Mail Address Semantics is a voluntary convention for naming people, actors and functions, and for addressing resources, facets, and optional interaction preferences through ordinary email addresses while keeping classification, authority, authentication, equivalence, and delivery implementation explicit and external to the address syntax.