]> Stalwart Labs LLC

1309 Coffeen Avenue, Suite 1200 Sheridan WY 82801 United States of America mauro@stalw.art https://stalw.art

SMTP MTA mail filtering JSON Patch This document specifies MTA Hooks, an HTTP-based protocol that lets Mail Transfer Agents (MTAs) delegate message processing decisions to external services. The MTA sends a JSON or Concise Binary Object Representation (CBOR) description of the SMTP session, envelope, and message to a registered service at defined stages of reception and delivery. The service answers with a JSON Patch that changes the description, and the MTA acts on the resulting state. The same mechanism covers filtering at SMTP time, routing before delivery, and reacting to delivery outcomes, and the MTA controls exactly which changes each service may make.

Introduction Mail Transfer Agents need extensible mechanisms to integrate external services for spam filtering, virus scanning, policy enforcement, routing, and compliance. Existing mechanisms each cover a part of the problem: content filter protocols such as Milter see only message reception, lookup tables receive a single key, and delivery outcomes are mostly recovered by parsing logs. MTA Hooks covers the whole life of a message with one protocol. At each processing stage the MTA describes the current state as a single JavaScript Object Notation (JSON) object: the SMTP session, the envelope with the status of every recipient, the message, and the delivery attempts. A scanner answers with a JSON Patch against that object. Accepting, rejecting, adding a header, discarding a recipient, choosing a route, or suppressing a delivery status notification (DSN) are all expressed the same way: as a change to the state. The MTA decides which parts of the object each scanner may change, and by default a scanner may only make processing stricter. Making it more permissive, such as overriding a rejection or lowering a TLS requirement, has to be granted explicitly by the MTA operator. The protocol uses ordinary HTTP , so existing client and server libraries, load balancers, proxies, and monitoring systems work unchanged.

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

MTA:

A Mail Transfer Agent as described in .

Scanner:

An HTTP service that receives hook requests from an MTA and returns changes.

Registration:

The state, held by the scanner, that records which stages, properties, and changes an MTA has agreed to exchange with it.

Subscription:

A part of a registration that applies to the messages and stages matching its filter.

Stage:

A point in mail processing at which the MTA invokes scanners.

Hook request:

The object describing the current state that the MTA sends to a scanner.

Grant:

A permission, given by the MTA, to change a part of the hook request.

Property path:

A JSON Pointer into the hook request, in which the reference token "*", used in place of an array index, matches any index.

Data Types

String:

A JSON string.

UnsignedInt:

An integer in the range 0 <= value <= 2^53-1.

Boolean:

A JSON boolean.

UTCDate:

A "date-time" string as defined in whose time-offset is "Z".

Bytes:

Binary data. In JSON it is a base64 string (); in CBOR it is a byte string.

A[] denotes an array of A, and String[A] denotes an object whose keys are strings and whose values are of type A. When sent, a property whose type includes null MAY be omitted, which is equivalent to null, and a property with a stated default MAY be omitted, which is equivalent to the default.

Protocol Overview

Architecture The MTA is always the HTTP client. It discovers a scanner, registers with it, and then sends it hook requests during mail processing. The MTA exposes no HTTP endpoint.

| | | | POST registration | | | MTA |-------------------------------------->| Scanner | | | POST hook request | | | |-------------------------------------->| | | |<--------------------------------------| | +-----+ JSON Patch +---------+ ]]>

Optionally, the MTA retrieves the scanner's discovery document (). The MTA registers, stating the stages, properties, and grants for each subscription (). At each subscribed stage the MTA sends a hook request (). The scanner returns a JSON Patch, which the MTA validates against the grants and applies ().

Serialization Discovery, registration, and error responses use JSON. Hook requests and responses use JSON or CBOR , chosen at registration. In CBOR, the data model is that of JSON, with text strings as map keys, except that Bytes values are byte strings, which avoids the size increase of base64 for message content. JSON Pointer and JSON Patch apply unchanged, and a "test" operation compares byte strings octet for octet.

Stages Stage Invoked connect When a client connects, before the greeting is sent; on a port with implicit TLS , after the TLS handshake. ehlo After each EHLO or HELO command, including the one that follows STARTTLS. mail After each MAIL command. rcpt After each RCPT command. data After the message content has been received, before the final reply. route Each time the MTA takes recipients from the queue for a delivery attempt, before resolving or connecting to the next hop. transmit Before each SMTP transaction of a delivery attempt, once its envelope is final and before the message is transmitted. delivery After the delivery attempts of a delivery job have completed. dsn Before the MTA sends a delivery status notification it generated. The first five stages are inbound stages and the last four are outbound stages. Each inbound stage request carries the state accumulated so far in the session, subject to the subscription's properties, so a scanner that subscribes only to "data" receives the connection, TLS, authentication, envelope, and message in a single request and can still reject the message at SMTP time. A delivery job is a set of recipients of one message that the MTA attempts in one processing cycle. How recipients are grouped into jobs is implementation-defined, except as constrained by routing ().

Scanner Chains When several registrations subscribe to the same stage, the MTA invokes them sequentially in a configured order. Each scanner receives the state as changed by the previous scanners, including the current action and which scanner set it. The chain ends early when a scanner sets a terminal action (). Each registration is identified in hook requests by a label that the MTA operator assigns to it, for example "spam" or "archive", and that the MTA sends in the registration request. The label is not chosen by the scanner, is stable across re-registration, and is unique within the MTA. It has the syntax of the registration identifier (), with at most 64 characters. The reserved label "mta" denotes the MTA itself.

State Changes A scanner changes processing by returning a JSON Patch that is applied to the hook request. The MTA then acts on the resulting state. There is no other way to influence processing, so every effect a scanner can have corresponds to a path in the hook request, and every permission is a grant on a path.

Discovery A scanner MAY publish a discovery document at "/.well-known/mta-hooks". The MTA retrieves it with GET. Discovery is optional: the MTA may instead be configured with the registration URL. The discovery document has the following properties:

version: String

The protocol version, "1.0" for this specification. An MTA MUST NOT register with a scanner whose version it does not support.

registration: String

URL of the registration endpoint, an absolute URL or a relative reference resolved against the URL of the discovery document ().

serialization: String[]

Media types of the supported serializations for hook requests: "application/json", "application/cbor", or both.

stages: String[]

Stages the scanner can process.

properties: String[]

Property paths the scanner wants to receive.

grants: Grant[]

Changes the scanner may want to make ().

maxMessageSize: UnsignedInt|null

Largest message, in octets, the scanner accepts. The MTA does not send a request for a larger message and instead treats the invocation as a failure of the scanner ().

timeoutMs: UnsignedInt|null

Time, in milliseconds, the scanner needs to answer a typical request.

Registration The MTA registers by POSTing a registration request to the registration endpoint. The MTA builds the request from its configuration; it states what the MTA will send and what it will allow. The scanner can accept it, narrow it, or refuse it, but never widen it.

Registration Request

name: String

Human-readable name of the MTA instance.

label: String

The label of this registration in hook requests ().

softwareVersion: String|null

MTA software version.

timeoutMs: UnsignedInt

Longest time, in milliseconds, the MTA waits for a hook response.

expiresAt: UTCDate|null

Requested expiration. The scanner MAY assign a different one.

serialization: String

Media type of the serialization for hook requests and responses. A scanner that does not support it refuses the registration with 422 UNSUPPORTED_SERIALIZATION.

subscriptions: Subscription[]

The subscriptions, in order. MUST NOT be empty.

A Subscription object has the following properties:

stages: String[]

Stages this subscription applies to.

filter: FilterOperator|FilterCondition|null

Which messages and connections this subscription applies to (). Null matches everything.

properties: String[]

Property paths the MTA will send. A path includes everything below it.

grants: Grant[]

Changes the scanner may make ().

onFailure: String

What the MTA does when the scanner fails (): "continue" or "tempfail". Default "continue".

For each stage, the MTA uses the first subscription, in order, that lists the stage and whose filter matches. If none matches, the scanner is not invoked. Different parts of the mail stream can therefore receive different properties, permissions, and failure handling. At the "route" and "delivery" stages, subscriptions are matched per recipient, with envelopeTo evaluated against that recipient alone. When recipients of a job match different subscriptions of the same registration, the MTA invokes the scanner once for each of those subscriptions, in subscription order, with only the recipients it matches, so each subscription's grants and onFailure apply only to its own recipients. At the "transmit" and "dsn" stages the transaction or DSN is matched as a whole, because its changes apply to a single copy.

Filters A filter uses the FilterOperator and FilterCondition syntax of with the Email filter conditions of , except those that depend on mailbox or thread state: inMailbox, inMailboxOtherThan, before, after, hasKeyword, notKeyword, allInThreadHaveKeyword, someInThreadHaveKeyword, and noneInThreadHaveKeyword. The following conditions are added. Their String values MAY contain "*", which matches zero or more characters. Domains are compared case-insensitively; local parts and logins are compared exactly.

envelopeFrom: String

The MAIL FROM address matches.

envelopeTo: String

The address of any recipient whose status is not "failed", "deferred", or "discarded" matches.

clientIp: String

The client IP address is within the given address or Classless Inter-Domain Routing (CIDR) prefix (, ).

serverPort: UnsignedInt

The client connected to this port.

tls: Boolean

Whether the session uses TLS.

authenticated: Boolean

Whether the client authenticated.

authLogin: String

The authenticated login matches.

A condition that refers to information not available at the stage being evaluated, such as the subject at the "rcpt" stage or the client address of a locally submitted message, evaluates to false, so its negation evaluates to true. The filter is evaluated by the MTA. It is included in the registration so the scanner knows which traffic it will see.

Grants A Grant object has the following properties:

path: String

A property path. The grant covers the locations it matches and everything below them.

values: String[]|null

If not null, every String value at or below the path that differs after the patch MUST match one of these values, which MAY contain the "*" wildcard of .

max: UnsignedInt|null

If not null, a number at the path MUST NOT exceed it after the patch; any other value at the path MUST NOT exceed it in size, in octets, in the negotiated serialization.

relax: Boolean

Whether the scanner may change ordered properties in the permissive direction (). Default false.

A change to a location not covered by a grant is not permitted. When several grants cover a location, the most specific one applies: the one whose path has the most reference tokens and, among those, the one with a literal token where the others have "*". A narrower grant can thus restrict part of a broader one. Examples:

Registration Response On success the scanner returns 201 Created with a Location header field giving the registration URL, and a Registration object:

id: String

Registration identifier, with the syntax of .

expiresAt: UTCDate|null

Expiration time, or null for none.

hookEndpoint: String

URL to which hook requests are sent, an absolute URL or a relative reference resolved against the registration URL.

An absolute URL in "registration" or "hookEndpoint" MUST have the same origin as the URL it is resolved against, unless the MTA's configuration allows the other origin. The MTA MUST NOT follow redirects for registration and hook requests; a 3xx status is a failure.

serialization: String

Confirmed serialization media type.

subscriptions: Subscription[]

The subscriptions as accepted. The scanner MAY remove properties and grants it does not need, but MUST NOT otherwise change the subscriptions, because removing a stage or a subscription would let traffic fall through to a later subscription. A scanner that cannot serve a subscription refuses the registration with 422. The MTA MUST NOT send properties or honor changes beyond what is confirmed here.

In this response, which echoes the two requested subscriptions unchanged, they are abbreviated. The HTTP examples in this document omit Content-Length.

Authentication The MTA MUST authenticate every request it makes to the scanner other than retrieval of the discovery document. Implementations MUST support bearer tokens in the Authorization header field, and MAY support TLS client certificates instead. Credentials are issued by the scanner operator to each MTA through an out-of-band channel. The scanner MUST reject unauthenticated requests with 401, including a WWW-Authenticate header field as requires, and requests from an MTA not authorized for the registration with 403.

Registration Lifecycle The MTA MAY retrieve the current Registration object with GET on the registration URL. It deregisters with DELETE on that URL, to which the scanner answers 204 (No Content). After deregistration the MTA MUST NOT start new hook requests for the registration. Hook requests already in flight MAY complete. A registration that expires or is terminated by the scanner causes subsequent requests to fail with 404 REGISTRATION_NOT_FOUND. The MTA MUST treat that response on a previously active registration as a signal to register again. The MTA SHOULD register again before expiresAt, and when its configuration for the scanner changes. Each registration has a new identifier; once the new registration is active, the MTA SHOULD delete the one it replaces. A scanner SHOULD continue to accept hook requests for a replaced registration for a short grace period. Scanner instances behind a load balancer MUST share registration state or partition it by registration identifier.

Hook Request

HTTP Request The MTA sends each hook request with POST to the hookEndpoint, with a Content-Type of "application/json" or "application/cbor" and the following header fields:

MTA-Hooks-Registration:

REQUIRED. The registration identifier.

MTA-Hooks-Request-Id:

REQUIRED. Identifies the logical invocation. It MUST be the same on every retry of an invocation. Scanners SHOULD use it to deduplicate.

MTA-Hooks-Context:

OPTIONAL. An opaque value that is the same for all requests about the same session at inbound stages, and about the same message at outbound stages, so that load balancers can route related requests to the same scanner instance without parsing the body. Scanners MUST NOT depend on such affinity.

Their values have the following syntax, using ABNF and the "unreserved" rule of :

Properties The hook request is an object whose properties are listed below. "stage", "timestamp", and "timeoutMs" are always sent, and "action", "decidedBy", and "response" are always sent at inbound stages. The others are sent when they are covered by the subscription's properties and available at the stage.

stage: String

The current stage.

action: String

Inbound stages only: what the MTA will do unless changed ().

decidedBy: String

Inbound stages only: label of the registration that last changed the action, or "mta".

response: SmtpResponse

Inbound stages only: the SMTP reply the MTA will send for the current command.

timestamp: UTCDate

When the stage began.

timeoutMs: UnsignedInt

Milliseconds the scanner has to answer this request: the registration's timeoutMs, reduced by any budget the MTA's configuration assigns to the stage or the chain and by time already spent on earlier attempts of this invocation. Answers arriving later are discarded.

traceId: String|null

Opaque identifier that correlates the message across the MTAs of an administrative domain. How it is obtained and propagated between MTAs is outside the scope of this document. It SHOULD be globally unique, for example a version 7 Universally Unique Identifier (UUIDv7) . A scanner with a grant MAY set it while it is null; once set, it cannot be changed.

session: Session|null

The session in which the message was received ().

capabilities: String[String|null]

At the "ehlo" stage, the SMTP service extensions the MTA will announce, keyed by upper-case keyword, with the parameters as a space-separated string or null ().

envelope: Envelope

Sender and recipients ().

message: Email

The parsed message ().

rawMessage: Bytes

The message in Internet Message Format .

senderAuth: SenderAuth

Sender authentication results ().

queue: Queue

The queued message ().

ext: String[Object]

Extension data ().

A property is not sent when the MTA does not have its information, such as the envelope before MAIL, the message before the end of DATA, the queue before the MTA assigns an identifier, or the session and senderAuth at outbound stages when the MTA did not retain them. At the "transmit" stage, envelope and message describe the transaction about to be performed. At the "dsn" stage, envelope, message, and rawMessage describe the DSN about to be sent; queue identifies the message the DSN reports on.

Session A Session object describes an SMTP session. For a message submitted by other means, such as the JSON Meta Application Protocol (JMAP) or a local submission program, it describes that submission as far as applicable; for example, "auth" identifies the submitting account and "client" is null for local submission.

id: String

Unique identifier of the session, stable across its stages and transactions.

startedAt: UTCDate

When the connection was accepted.

client: ClientInfo|null

The client.

server: ServerInfo|null

The address the client connected to.

tls: TlsInfo|null

TLS negotiated or attempted on the session, or null.

auth: SmtpAuth|null

Authentication of the client, or null.

counters: String[UnsignedInt]

Session counters and measurements, keyed by names from the registry in . The MTA includes those it maintains.

A ClientInfo object has the following properties:

ip: String

Client IP address.

port: UnsignedInt

Client port.

ptr: String|null

Host name from the PTR record of the IP address.

ehlo: String|null

Argument of the most recent EHLO or HELO command.

asn: UnsignedInt|null

Autonomous System Number (ASN) of the IP address.

country: String|null

Alpha-2 country code of the IP address.

activeConnections: UnsignedInt|null

Concurrent connections from this IP address.

proxy: ProxyInfo|null

How the client identity was conveyed, if not taken from the socket.

The client properties carry the effective client identity. When it was conveyed by a proxy mechanism that the MTA trusts, "proxy" describes that mechanism; when the mechanism is not trusted, the MTA ignores it and the request contains the socket identity without a "proxy" property. A ProxyInfo object has the following properties:

protocol: String

"proxy-v1" or "proxy-v2" for the PROXY protocol , "xclient" for XCLIENT , or "xforward" for XFORWARD .

ip: String

IP address of the proxy, the socket peer.

port: UnsignedInt

Port of the proxy.

overridden: String[]

Property paths of the session values that came from the proxy, for example "/session/client/ip" or "/session/server/port".

A ServerInfo object has the following properties:

name: String

Host name the MTA uses on this connection.

ip: String

IP address the client connected to.

port: UnsignedInt

Port the client connected to.

A TlsInfo object has the following properties:

version: String|null

TLS version: "TLSv1.2" or "TLSv1.3", or null if no handshake completed.

cipher: String|null

Name of the cipher suite as listed in the IANA "TLS Cipher Suites" registry, or null if no handshake completed.

peerCertificate: Certificate|null

The certificate presented by the peer: the client certificate at inbound stages, the server certificate at outbound stages. Null if none was presented.

policy: String|null

Outbound only: the policy type applied, as defined for "policy-type" in .

failure: String|null

Outbound only: why TLS failed, as a "result-type" value of , or null.

A Certificate object has the following properties:

chain: Bytes[]

The certificates as presented, encoded with the Distinguished Encoding Rules (DER) , end-entity certificate first.

verification: String

"pass" if the MTA verified the certificate, using PKIX or DNS-Based Authentication of Named Entities (DANE) ; "none" if it did not attempt verification; otherwise why verification failed, as one of the "result-type" values "certificate-expired", "certificate-not-trusted", "certificate-host-mismatch", or "validation-failure" of .

The certificate is reported whether or not it could be verified. A certificate that did not verify is an unauthenticated assertion by the peer; it is useful for recognizing a peer, but not as proof of its identity. An SmtpAuth object has the following properties:

login: String

Authenticated identity.

method: String|null

Name of the Simple Authentication and Security Layer (SASL) mechanism used with SMTP AUTH , or null for authentication by other means.

Envelope and Recipients An Envelope object has the following properties:

from: Address

The reverse-path.

to: Recipient[]

The recipients.

An Address object has the following properties:

address: String|null

The address, or null for the null reverse-path.

parameters: String[String|null]

All Extended SMTP (ESMTP) parameters given with the address, keyed by upper-case name, with null for a parameter without a value. Values that their extension encodes as xtext, such as ENVID and the address in ORCPT , are decoded. Examples are SIZE, BODY, SMTPUTF8, REQUIRETLS, RET, ENVID, NOTIFY, and ORCPT.

A Recipient object has the properties of Address, where address is not null, and the following:

status: String

See below.

response: SmtpResponse|null

The reply that determined the status: the reply given to the RCPT command at inbound stages, or the reply of the next hop at outbound stages.

decidedBy: String

Label of the registration that last changed the status, or "mta".

expansion: String[]|null

Inbound only: the addresses this recipient resolves to after alias expansion and rewriting, when the MTA has already resolved it.

originalRecipient: String|null

Outbound only: the address as given in RCPT TO, when this recipient resulted from expansion or rewriting.

attempts: UnsignedInt

Outbound only: delivery attempts made for this recipient.

nextAttemptAt: UTCDate|null

Outbound only: when the next attempt is scheduled.

nextDsnAt: UTCDate|null

Outbound only: when the next delay DSN is scheduled.

route: Route

Outbound only: the route used for the next attempt (). Its null properties take the MTA's defaults.

lastAttempt: Attempt|null

Outbound only: the most recent delivery attempt.

The status of a recipient is one of: Status Meaning pending The recipient of the RCPT command being processed. accepted Accepted at RCPT and not yet attempted. deferred Temporarily failed: a 4xx reply at RCPT, or an outbound attempt to be retried. failed Permanently failed: a 5xx reply at RCPT, or an outbound failure for which a DSN is due. delivered Delivered to the next hop. discarded Dropped without delivery and without a DSN. At inbound stages, recipients appear in the order of their RCPT commands, including those rejected or deferred. At the "rcpt" stage the last recipient is the one of the current command, with status "pending". At outbound stages, the array contains the recipients that the invocation covers: those of the delivery job matched by the subscription, those of the transaction at the "transmit" stage, or the recipient of the DSN at the "dsn" stage. An Attempt object has the following properties:

at: UTCDate

When the attempt was made.

remote: RemoteHost|null

The host the MTA connected to, or null if no connection was made.

sourceIp: String|null

The local IP address used.

tls: TlsInfo|null

TLS on the connection, or null if TLS was not attempted.

A RemoteHost object has the following properties:

host: String

Host name of the next hop, such as the MX name.

ip: String

IP address connected to.

port: UnsignedInt

Port connected to.

Message The "message" property is the Email object of , without the metadata properties of other than "size", and with the "blobId" of each EmailBodyPart replaced by a "blob" property of type Bytes holding the part's content after decoding its Content-Transfer-Encoding . The "rawMessage" property is the message octet for octet, which signature verification and archiving require. A scanner can request either or both. Header changes are made through "/message/headers"; the convenience properties derived from headers, such as "subject" and "from", cannot be changed. Body changes are made through "bodyValues" and "bodyStructure", or by replacing "rawMessage" with a complete new message. A patch that changes both "message" and "rawMessage" is invalid. After a change, the MTA presents both consistently to the following scanners.

Sender Authentication A SenderAuth object has the following properties, each holding a result value of the corresponding Authentication-Results method , or null if not evaluated:

iprev: String|null

Reverse DNS check of the client address (forward-confirmed reverse DNS).

spfHelo: String|null

Sender Policy Framework (SPF) for the HELO identity.

spfMailFrom: String|null

SPF for the MAIL FROM identity.

dkim: String|null

DomainKeys Identified Mail (DKIM) .

dkim2: String|null

DKIM2 , with the result values of .

dmarc: String|null

Domain-based Message Authentication, Reporting, and Conformance (DMARC) .

Queue A Queue object has the following properties:

id: String

Identifier of the message in the MTA's queue.

expiresAt: UTCDate|null

When the MTA gives up delivering the message. Present at outbound stages.

The queue identifier MUST be the same at every stage and every delivery job of the message, from "data" to the last "delivery" or "dsn", and MUST be unique within the MTA for the lifetime of the message. Scanners can therefore keep the state they collected at inbound stages until expiresAt.

Extension Data The "ext" object holds data outside this specification. Each key is a namespace named by a reverse domain name controlled by its definer, for example "org.example.spam", and its value is an object whose content that definer specifies. Extension data is written by the MTA and by scanners, and exchanged like any other property: the subscription's properties decide which namespaces a scanner receives, and its grants decide which it can write. A namespace written by one scanner and sent to another is how scanners pass results along a chain without adding header fields to the message. Recipients of a request MUST ignore namespaces they do not understand. Extension data is kept with the message for as long as the message is in the MTA, so data written at the "data" stage is available again at the "route", "delivery", and "dsn" stages. Data written before the MAIL command is kept with the session and copied to each of its transactions. The MTA SHOULD limit the size of each namespace through the "max" of the grant.

SMTP Response An SmtpResponse object has the following properties:

code: UnsignedInt

The reply code.

enhancedCode: String|null

The enhanced status code .

message: String

The reply text.

delayMs: UnsignedInt|null

Milliseconds the MTA waits before sending the reply. At the "connect" stage this delays the greeting, which reveals clients that send commands before it. The MTA MUST cap it, normally through the "max" of the grant, below the 5-minute timeouts that SMTP clients apply ().

EHLO Capabilities At the "ehlo" stage, a scanner can only withhold what the MTA offers: it may remove keywords, remove space-separated parameters from a value, or lower a numeric value such as that of SIZE. Other changes to "capabilities" are invalid regardless of grants. This allows, for example, offering AUTH only on some networks or withholding PIPELINING and CHUNKING from suspicious clients.

Examples An inbound request at the "data" stage, with the message abbreviated:

"}, {"name": "To", "value": " bob@example.com"}, {"name": "Subject", "value": " Meeting Tomorrow"} ], "bodyValues": { "1": {"value": "Let's meet tomorrow at 10am.", "isEncodingProblem": false, "isTruncated": false} } }, "senderAuth": {"iprev": "pass", "spfMailFrom": "pass", "dkim": "pass", "dkim2": "none", "dmarc": "pass"} } ]]>

An outbound request at the "route" stage:

Hook Response

Structure A scanner answers with 200 and a JSON Patch in the negotiated serialization, or with 204 and no body when it has no changes. An empty patch also means no changes. In JSON the Content-Type is "application/json-patch+json"; in CBOR it is "application/cbor" and the patch is the CBOR encoding of the same array. The patch is applied to the hook request as held by the MTA, which can include properties that were not sent. A scanner can, for example, add a header field with "add" at "/message/headers/0" without receiving the message, or append a recipient at "/envelope/to/-". In that state, every property defined for an object that exists at the stage is present, with the value null when it has none, so "replace" and "test" behave the same whether or not a null property was sent. The "/envelope/to" array is the one the request carries, in the same order.

Validation and Application The MTA applies the patch to a copy of the state. The patch is valid only if: it applies successfully according to , including all "test" operations; the "from" of every "copy" and "move" operation, and the "path" of every "test" operation, is covered by the subscription's properties; every location whose value differs between the original and the resulting state is covered by a grant of the subscription, and satisfies the "values" and "max" of the grant that applies (); it does not change "stage", "timestamp", "timeoutMs", any "decidedBy", or a non-null "traceId", which no grant covers; the resulting state respects the ordering of unless that grant relaxes it; and the resulting state is otherwise valid: values have the types defined in this document, actions and statuses are permitted at the stage (, ), at most one of "message" and "rawMessage" changed, and header fields, addresses, and message content are well formed (). Because validation compares states, it does not depend on which operations produced the result. A valid patch replaces the state, after which the MTA sets "decidedBy" of the action and of each changed recipient to the label of the registration. An invalid patch is discarded as a whole, is logged with the request identifier, and counts as a failure of the scanner ().

Ordering Some properties are ordered from permissive to strict. Without "relax", a scanner may only keep them, move them in the strict direction, or move them between equally strict values: Property Permissive to strict /action accept, quarantine, then reject, discard, and disconnect (all equally strict) /envelope/to/*/route/tls none, opportunistic, required, verified A null "tls" ranks as the requirement the MTA would otherwise apply. With "relax", the scanner may, for example, accept a message that the MTA's own policy rejected or that an earlier scanner quarantined. Such a grant makes the scanner the final authority for the property (). When several scanners with "relax" change the same property, the last one in the chain prevails.

Actions At inbound stages, the action applies to the command being processed: Action Meaning accept Continue normally. quarantine Accept the message and quarantine it instead of delivering it. Not permitted at the "connect" and "ehlo" stages. reject Send "/response", a 4xx or 5xx reply. At the "connect" stage it replaces the greeting and MUST be a 554 reply (); a temporary refusal of the connection is expressed with "disconnect". At the "rcpt" stage it rejects the recipient. discard At the "mail" and "data" stages: accept the message and drop it. At the "rcpt" stage: accept the recipient and set it to "discarded". Not permitted at the "connect" and "ehlo" stages. disconnect Send "/response", a 421 reply (), and close the connection. The terminal actions are "reject", "discard", and "disconnect": after a scanner sets one, the MTA invokes no further scanners for that stage. At the "rcpt" stage, "reject" and "discard" apply only to the current recipient, and processing of the transaction continues. At the start of each inbound stage, the action is the one the MTA's own policy assigns to the command, except that a "quarantine" set at the "mail" or "rcpt" stage, or a "discard" set at the "mail" stage, applies to the message and is kept for the later stages of the transaction. The chain runs even if that initial action is terminal, so that a scanner with "relax" can override it. Outbound stages have no action: their outcome is the status of each recipient (). The chain ends early when every recipient of the invocation has been discarded. "accept", "quarantine", and "discard" require a 2xx reply, or the intermediate reply SMTP requires for the command; "reject" requires a 4xx or 5xx reply; and "disconnect" requires a 421 reply. If "/response" does not satisfy this, the MTA uses its default reply for the action.

Recipient Changes Recipients cannot be removed from "/envelope/to"; a recipient is dropped by setting its status to "discarded". Recipients can be added at the "data" stage, with status "accepted". The status of a recipient can be changed as follows: Stage From To data accepted discarded route, transmit, delivery accepted, deferred deferred, failed, discarded delivery failed discarded dsn accepted discarded Setting a failed recipient to "discarded" suppresses its DSN, and discarding the recipient of a DSN at the "dsn" stage suppresses that DSN. A scanner that sets a recipient to "failed" or "deferred" MAY also set its "response", which the MTA reports in the DSN; otherwise the MTA uses a default reply. At the "route" and "delivery" stages, "nextAttemptAt" and "nextDsnAt" can be changed for recipients that remain deferred. Discarding a message or a recipient after accepting it, and suppressing a DSN, depart from and are subject to the cautions of . MTAs SHOULD log them, and operators SHOULD grant them only for unwanted mail or where the sender is notified by other means. At the "rcpt" stage the outcome of the current recipient is set through "/action" and "/response", and the MTA records it in the recipient's status. Per-recipient outcomes after the DATA command are limited to "discarded" because SMTP gives a single reply to the message.

Routing At the "route" stage, a scanner can choose how each recipient of the job is delivered by changing its "route". A Route object has the following properties:

name: String|null

A route the MTA has configured, such as a queue or transport name, carrying its own next hop, TLS, source address, credential, and throttling settings. The names a scanner may use are given by the "values" of its grant.

nextHop: String|null

Host name or IP address to deliver to, overriding the route's next hop.

port: UnsignedInt|null

Port to connect to.

mxLookup: Boolean|null

Whether "nextHop" is a domain whose MX records are resolved (true) or a host to connect to directly (false).

sourceIp: String|null

Local IP address to connect from.

tls: String|null

Minimum TLS requirement: "none", "opportunistic", "required" (TLS without authentication of the server), or "verified" (TLS with the server authenticated by DANE , SMTP MTA Strict Transport Security (MTA-STS) , or PKIX ).

A null property takes its value from the named route, or from the MTA's default routing when "name" is null as well. Two routes are different when any of their properties differ after null properties have been resolved. Because each property can be granted separately, an MTA can let a scanner choose only among predefined routes, or give it complete control over next hops, source addresses, and TLS. Credentials are never carried in a route; they belong to the named route. The MTA MUST NOT deliver recipients with different routes in the same SMTP transaction. Otherwise, how recipients are batched remains implementation-defined. A route change persists for the recipient until changed again, and the "route" stage runs before every attempt, so a scanner can fail over based on "attempts" and "lastAttempt". The "delivery" stage runs once for the job, after all of its partial deliveries. A grant that relaxes "tls" lets the scanner lower the requirement below the policy published by the destination, as a "TLS-Required: No" header field does (), for example to deliver a TLS report to a domain whose TLS is broken; lowering it to "none" also skips STARTTLS. Like that header field, it does not apply to a message sent with the REQUIRETLS parameter (). The MTA SHOULD log every route change together with the registration label and the recipient, and MUST apply its loop detection to scanner-chosen next hops.

Transmission The "transmit" stage runs once for each SMTP transaction, after the MTA has grouped the recipients of the job into transactions, so the request carries the exact reverse-path and recipients that will be sent. A scanner can change the message for this transaction only, for example to add signatures that cover the envelope of each hop, such as DKIM2 signatures . Within the envelope, only recipient status can be changed. Status changes are kept; changes to the message apply to this transaction only and are not kept in the queue. The stage runs again for every attempt, so signatures carry the time and envelope of the attempt that uses them. A DSN is changed the same way at the "dsn" stage.

Examples Add header fields and pass a score to later scanners:

Reject a message:

Slow down a suspicious client at the "connect" stage:

Route the first recipient through a virtual private network (VPN), but only if no other scanner has already routed it:

Drop a failed recipient without a DSN at the "delivery" stage:

Error Responses A scanner that cannot process a request returns a 4xx or 5xx status with the error body of : 401: Credentials missing or invalid. The MTA MUST NOT retry with the same credentials. 403: Credentials not authorized for the registration. The MTA MUST NOT retry. 404: Registration unknown. The MTA registers again. 413: Request body larger than the scanner accepts. The MTA MUST NOT retry it. 422: The request uses unsupported properties or values. The MTA MUST NOT retry it. 429: Rate limited. The MTA SHOULD NOT send further requests under the registration until the time given by Retry-After, if any, and applies onFailure to invocations meanwhile. 5xx: Transient error. The MTA MAY retry (). Any other status is a failure that the MTA MUST NOT retry. MTAs SHOULD alert their operators to 401, 403, 413, and 422, which persist until the configuration changes; with "tempfail" they can hold mail until the message expires.

Transport

HTTP and TLS Implementations MUST support HTTP/1.1 and SHOULD support HTTP/2 ; they MAY support HTTP/3 . MTAs SHOULD reuse connections to a scanner. All MTA Hooks traffic MUST use TLS 1.2 or later and follow the recommendations of ; implementations SHOULD support TLS 1.3 . The MTA MUST validate the scanner's certificate; private certificate authorities may be configured, but validation SHOULD NOT be disabled.

Retries On a network error or a 5xx status, the MTA MAY retry within the request's timeoutMs, with exponential backoff and jitter.

Failure Handling A scanner fails when it does not answer within timeoutMs, when all retries fail, when it returns a status other than 200 or 204, or when its patch is invalid (). The MTA then leaves the state unchanged and acts according to the subscription's onFailure:

continue:

Proceed with the next scanner, as if the scanner had made no changes.

tempfail:

At the "connect" and "ehlo" stages, answer with a 421 4.3.0 reply and close the connection; at the other inbound stages, answer the current command with a 451 4.3.0 reply (). At the "route" and "transmit" stages, leave the invocation's accepted and deferred recipients deferred and retry them later; a transaction skipped this way does not count as an attempt. At the "dsn" stage, keep the DSN queued and retry it later. At the "delivery" stage, outcomes are already final, so the failure only means the scanner's changes are lost; a scanner that must reliably suppress DSNs does so at the "dsn" stage.

"tempfail" is appropriate where a missing decision must not let mail through, such as mandatory routing or mandatory archiving. It can stop the affected mail flow while the scanner is unavailable, so scanners used this way SHOULD be deployed redundantly, and subscription filters SHOULD limit it to the mail that requires it. MTAs SHOULD temporarily stop calling a scanner that fails repeatedly, and apply its onFailure in the meantime.

Implementation Status Note to the RFC Editor: please remove this section, and the reference to , before publication. This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.

Stalwart Mail Server:

Organization: Stalwart Labs LLC, with which the author is affiliated. Role: MTA. Coverage: an earlier revision of this specification (-01). Licensing: AGPL-3.0 for the open-source edition. Contact: mauro@stalw.art.

Security Considerations

Trust Model The MTA acts only as an HTTP client and exposes no endpoint to scanners. This removes attacks such as registration floods against the MTA and request forgery through callbacks. The scanner operator decides which MTAs may register and issues credentials; the MTA operator decides which scanners to call and what each may change.

Authority of Scanners A scanner can only change what its grants cover, and by default only toward stricter processing. Grants that relax ordered properties, change routes, or rewrite content make the scanner part of the trusted base for those decisions: a compromised scanner with full routing authority can redirect or exfiltrate mail, and one with "relax" on "/action" can let malicious mail through. Operators SHOULD give such grants only to scanners they trust accordingly, limit them with subscription filters, and log their use. The MTA MUST enforce grants itself and MUST NOT rely on scanners respecting them. Scanner-chosen next hops and ports can also direct the MTA's connections at internal services. An MTA SHOULD restrict them by configuration, for example through the "values" of the grant on "nextHop", and MUST apply to them the same address restrictions it applies to next hops found in the DNS.

Credentials Credentials SHOULD be issued per MTA instance, rotated, revoked when an instance is decommissioned, and kept out of logs and diagnostics. Bearer tokens MUST have at least 128 bits of entropy, and the security considerations of apply. Scanners SHOULD apply authorization per MTA identity at registration and SHOULD rate limit registrations per identity. The discovery document is unauthenticated and SHOULD be rate limited.

Denial of Service Slow or failing scanners can tie up MTA resources. MTAs MUST enforce timeouts and SHOULD limit concurrent requests per scanner. Delayed replies hold SMTP connections open; besides capping delayMs (), the MTA SHOULD limit how many delayed replies it serves at once. Recipients added at the "data" stage can amplify a message, so MTAs SHOULD limit how many a patch may add. Scanners SHOULD limit request rate, concurrency, and body size per registration.

Injection The MTA MUST validate everything a patch writes: header field names and values MUST NOT allow injection of a carriage return (CR) or line feed (LF), or malformed encoded words ; added or changed addresses MUST be syntactically valid and subject to the MTA's relay and recipient policy; and body changes MUST produce well-formed MIME .

Unverified Data Certificates that did not verify, proxy information, and client-supplied values such as the EHLO argument are assertions by the peer. Scanners MUST NOT treat them as authenticated identities. A trace identifier received from outside the MTA's administrative domain can be chosen by an attacker to link unrelated mail, so MTAs MUST NOT accept one from untrusted sources.

Privacy Considerations Hook requests can contain message content, addresses, client IP addresses, and authentication identities. MTAs SHOULD send only the properties a scanner needs, and the subscription mechanism makes this possible per stage and per part of the mail stream. Scanner operators SHOULD avoid logging content and personal data, and SHOULD limit retention to what their function requires.

IANA Considerations

Well-Known URI IANA is requested to register the following well-known URI : URI suffix: mta-hooks Change controller: IETF Specification document: this document Status: permanent

HTTP Field Names IANA is requested to register the following field names in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" (), with status "permanent", no structured type, and this document as the reference: MTA-Hooks-Registration, MTA-Hooks-Request-Id, MTA-Hooks-Context.

MTA Hooks Registries IANA is requested to create a new registry group named "MTA Hooks" containing the four registries below. For all of them, new registrations require Specification Required , and the change controller of the initial entries is the IETF. The designated experts SHOULD check that a name is a short identifier in the style of the existing entries and does not duplicate the semantics of an existing entry. For a stage, they SHOULD check that the specification defines when it is invoked, what the request contains, and which changes are permitted. For an action, they SHOULD check that its meaning is defined at every stage where it is permitted, and its place in the ordering of .

MTA Hooks Stages Each entry gives the name, the direction (inbound or outbound), when the stage is invoked, the reference, and the change controller. Name Direction Invoked Reference connect inbound Client connected, before the greeting RFC XXXX ehlo inbound After each EHLO or HELO command RFC XXXX mail inbound After each MAIL command RFC XXXX rcpt inbound After each RCPT command RFC XXXX data inbound After the message content RFC XXXX route outbound Before each delivery attempt of a job RFC XXXX transmit outbound Before each SMTP transaction RFC XXXX delivery outbound After the attempts of a job RFC XXXX dsn outbound Before sending a generated DSN RFC XXXX

MTA Hooks Actions Each entry gives the name, whether the action is terminal, its rank in the ordering of (higher is stricter), the reference, and the change controller. The meaning of each initial entry at each stage is given in . Name Terminal Rank Reference accept no 0 RFC XXXX quarantine no 1 RFC XXXX reject yes 2 RFC XXXX discard yes 2 RFC XXXX disconnect yes 2 RFC XXXX

MTA Hooks Session Counters Each entry gives the name, its meaning, the reference, and the change controller. The reference of every initial entry is RFC XXXX. Name Meaning commands SMTP commands received errors Commands answered with a 4xx or 5xx reply invalidCommands Commands that were unknown or syntactically invalid rsets RSET commands transactions MAIL commands accepted, including the current transaction messagesAccepted Messages accepted for delivery messagesRejected Messages rejected after DATA pregreetBytes Octets the client sent before the greeting pipeliningViolations Commands sent ahead of a reply without PIPELINING, or across a synchronization point bareLineEnds Lines ended by a bare LF or bare CR firstCommandDelayMs Milliseconds between the greeting and the first command

MTA Hooks Error Codes Each entry gives the code, the HTTP status it is used with, its meaning, the reference, and the change controller. The initial entries are those of , each with the reference RFC XXXX.

This initial document specifies the various headers used to describe the structure of MIME messages. [STANDARDS-TRACK] This particular document is the third document in the series. It describes extensions to RFC 822 to allow non-US-ASCII text data in Internet mail header fields. [STANDARDS-TRACK] This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. This memo defines an extension to the Simple Mail Transfer Protocol (SMTP) service, which allows an SMTP client to specify (a) that Delivery Status Notifications (DSNs) should be generated under certain conditions, (b) whether such notifications should return the contents of the message, and (c) additional information, to be returned with a DSN, that allows the sender to identify both the recipient(s) for which the DSN was issued, and the transaction in which the original message was sent. [STANDARDS-TRACK] This document defines a set of extended status codes for use within the mail system for delivery status reports, tracking, and improved diagnostics. In combination with other information provided in the Delivery Status Notification (DSN) delivery report, these codes facilitate media and language independent rendering of message delivery status. [STANDARDS-TRACK] A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This specification defines the addressing architecture of the IP Version 6 (IPv6) protocol. The document includes the IPv6 addressing model, text representations of IPv6 addresses, definition of IPv6 unicast addresses, anycast addresses, and multicast addresses, and an IPv6 node's required addresses. This document obsoletes RFC 3513, "IP Version 6 Addressing Architecture". [STANDARDS-TRACK] The Simple Authentication and Security Layer (SASL) is a framework for providing authentication and data security services in connection-oriented protocols via replaceable mechanisms. It provides a structured interface between protocols and mechanisms. The resulting framework allows new protocols to reuse existing mechanisms and allows old protocols to make use of new mechanisms. The framework also provides a protocol for securing subsequent protocol exchanges within a data security layer. This document describes how a SASL mechanism is structured, describes how protocols include support for SASL, and defines the protocol for carrying a data security layer over a connection. In addition, this document defines one SASL mechanism, the EXTERNAL mechanism. This document obsoletes RFC 2222. [STANDARDS-TRACK] This memo discusses the strategy for address assignment of the existing 32-bit IPv4 address space with a view toward conserving the address space and limiting the growth rate of global routing state. This document obsoletes the original Classless Inter-domain Routing (CIDR) spec in RFC 1519, with changes made both to clarify the concepts it introduced and, after more than twelve years, to update the Internet community on the results of deploying the technology described. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] This document defines a Simple Mail Transport Protocol (SMTP) extension whereby an SMTP client may indicate an authentication mechanism to the server, perform an authentication protocol exchange, and optionally negotiate a security layer for subsequent protocol interactions during this session. This extension includes a profile of the Simple Authentication and Security Layer (SASL) for SMTP. This document obsoletes RFC 2554. [STANDARDS-TRACK] Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] This document is a specification of the basic protocol for Internet electronic mail transport. It consolidates, updates, and clarifies several previous documents, making all or parts of most of them obsolete. It covers the SMTP extension mechanisms and best practices for the contemporary Internet, but does not provide details about particular extensions. Although SMTP was designed as a mail transport and delivery protocol, this specification also contains information that is important to its use as a "mail submission" protocol for "split-UA" (User Agent) mail reading systems and mobile environments. [STANDARDS-TRACK] This document specifies the Internet Message Format (IMF), a syntax for text messages that are sent between computer users, within the framework of "electronic mail" messages. This specification is a revision of Request For Comments (RFC) 2822, which itself superseded Request For Comments (RFC) 822, "Standard for the Format of ARPA Internet Text Messages", updating it to reflect current practice and incorporating incremental changes that were specified in other RFCs. [STANDARDS-TRACK] This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation (JSON) document; it is suitable for use with the HTTP PATCH method. The "application/json-patch+json" media type is used to identify such patch documents. This memo describes a downgrade-resistant protocol for SMTP transport security between Message Transfer Agents (MTAs), based on the DNS-Based Authentication of Named Entities (DANE) TLSA DNS record. Adoption of this protocol enables an incremental transition of the Internet email backbone to one using encrypted and authenticated Transport Layer Security (TLS). JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. A number of protocols exist for establishing encrypted channels between SMTP Mail Transfer Agents (MTAs), including STARTTLS, DNS- Based Authentication of Named Entities (DANE) TLSA, and MTA Strict Transport Security (MTA-STS). These protocols can fail due to misconfiguration or active attack, leading to undelivered messages or delivery over unencrypted or unauthenticated channels. This document describes a reporting mechanism and format by which sending systems can share statistics and specific information about potential failures with recipient domains. Recipient domains can then use this information to both detect potential attacks and diagnose unintentional misconfigurations. SMTP MTA Strict Transport Security (MTA-STS) is a mechanism enabling mail service providers (SPs) to declare their ability to receive Transport Layer Security (TLS) secure SMTP connections and to specify whether sending SMTP servers should refuse to deliver to MX hosts that do not offer TLS with a trusted server certificate. This document specifies a message header field called "Authentication-Results" for use with electronic mail messages to indicate the results of message authentication efforts. Any receiver-side software, such as mail filters or Mail User Agents (MUAs), can use this header field to relay that information in a convenient and meaningful way to users or to make sorting and filtering decisions. This document obsoletes RFC 7601. This document specifies a protocol for clients to efficiently query, fetch, and modify JSON-based data objects, with support for push notification of changes and fast resynchronisation and for out-of- band binary data upload/download. This document specifies a data model for synchronising email data with a server using the JSON Meta Application Protocol (JMAP). Clients can use this to efficiently search, access, organise, and send messages, and to get push notifications for fast resynchronisation when new messages are delivered or a change is made in another client. The SMTP STARTTLS option, used in negotiating transport-level encryption of SMTP connections, is not as useful from a security standpoint as it might be because of its opportunistic nature; message delivery is, by default, prioritized over security. This document describes an SMTP service extension, REQUIRETLS, and a message header field, TLS-Required. If the REQUIRETLS option or TLS-Required message header field is used when sending a message, it asserts a request on the part of the message sender to override the default negotiation of TLS, either by requiring that TLS be negotiated when the message is relayed or by requesting that recipient-side policy mechanisms such as MTA-STS and DNS-Based Authentication of Named Entities (DANE) be ignored when relaying a message for which security is unimportant. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced latency by introducing field compression and allowing multiple concurrent exchanges on the same connection. This document obsoletes RFCs 7540 and 8740. Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are used to protect data exchanged over a wide range of application protocols and can also form the basis for secure transport protocols. Over the years, the industry has witnessed several serious attacks on TLS and DTLS, including attacks on the most commonly used cipher suites and their modes of operation. This document provides the latest recommendations for ensuring the security of deployed services that use TLS and DTLS. These recommendations are applicable to the majority of use cases. RFC 7525, an earlier version of the TLS recommendations, was published when the industry was transitioning to TLS 1.2. Years later, this transition is largely complete, and TLS 1.3 is widely available. This document updates the guidance given the new environment and obsoletes RFC 7525. In addition, this document updates RFCs 5288 and 6066 in view of recent attacks. This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs. This document obsoletes RFC 7807. This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document obsoletes RFC 8446, which specified TLS 1.3. This document obsoletes RFC 5246 (specifying TLS 1.2) and RFCs 5077, 6961, 7627, and 8422, all of which pertain to TLS 1.2 or earlier, and updates RFCs 5705 and 6066. This document also specifies new requirements for TLS 1.2 implementations. ISO ITU-T In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. DomainKeys Identified Mail (DKIM) permits a person, role, or organization that owns the signing domain to claim some responsibility for a message by associating the domain with the message. This can be an author's organization, an operational relay, or one of their agents. DKIM separates the question of the identity of the Signer of the message from the purported author of the message. Assertion of responsibility is validated through a cryptographic signature and by querying the Signer's domain directly to retrieve the appropriate public key. Message transit from author to recipient is through relays that typically make no substantive change to the message content and thus preserve the DKIM signature. This memo obsoletes RFC 4871 and RFC 5672. [STANDARDS-TRACK] Email on the Internet can be forged in a number of ways. In particular, existing protocols place no restriction on what a sending host can use as the "MAIL FROM" of a message or the domain given on the SMTP HELO/EHLO commands. This document describes version 1 of the Sender Policy Framework (SPF) protocol, whereby ADministrative Management Domains (ADMDs) can explicitly authorize the hosts that are allowed to use their domain names, and a receiving host can check such authorization. This document obsoletes RFC 4408. This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice. This specification outlines current recommendations for the use of Transport Layer Security (TLS) to provide confidentiality of email traffic between a Mail User Agent (MUA) and a Mail Submission Server or Mail Access Server. This document updates RFCs 1939, 2595, 3501, 5068, 6186, and 6409. The QUIC transport protocol has several features that are desirable in a transport for HTTP, such as stream multiplexing, per-stream flow control, and low-latency connection establishment. This document describes a mapping of HTTP semantics over QUIC. This document also identifies HTTP/2 features that are subsumed by QUIC and describes how HTTP/2 extensions can be ported to HTTP/3. This specification defines UUIDs (Universally Unique IDentifiers) -- also known as GUIDs (Globally Unique IDentifiers) -- and a Uniform Resource Name namespace for UUIDs. A UUID is 128 bits long and is intended to guarantee uniqueness across space and time. UUIDs were originally used in the Apollo Network Computing System (NCS), later in the Open Software Foundation's (OSF's) Distributed Computing Environment (DCE), and then in Microsoft Windows platforms. This specification is derived from the OSF DCE specification with the kind permission of the OSF (now known as "The Open Group"). Information from earlier versions of the OSF DCE specification have been incorporated into this document. This document obsoletes RFC 4122. This document describes the Domain-based Message Authentication, Reporting, and Conformance (DMARC) protocol. DMARC permits the owner of an email's Author Domain to enable validation of the domain's use to indicate the Domain Owner's or Public Suffix Operator's message handling preference regarding failed validation and to request reports about the use of the domain name. Mail-receiving organizations can use this information when evaluating handling choices for incoming mail. This document obsoletes RFCs 7489 and 9091. Yahoo Google Fastmail Pty Ltd DomainKeys Identified Mail v2 (DKIM2) permits a person, role, or organization that owns a signing domain to document that it has handled an email message by associating their domain with the message. This is achieved by providing a hash value that has been calculated on the current contents of the message and then applying a cryptographic signature that covers the hash values and other details about the transmission of the message. Verification is performed by querying an entry within the signing domain's DNS space to retrieve an appropriate public key. As a message is transferred from author to recipient, systems that alter the body or header fields will provide details of their changes and calculate new hash values. Further signatures will be added to provide a "chain" that receivers can validate. This permits verifiers to identify the nature of changes made by intermediaries and apply a reputation to the systems that made changes. DKIM2 also allows recipients to detect when messages have been unexpectedly "replayed" and will ensure that Delivery Status Notifications are only sent to entities that were involved in the transmission of a message. Fastmail Pty Ltd DomainKeys Identified Mail Signatures v2 (DKIM2) produces a verification result for an email message. This document defines how that result is reported in the Authentication-Results header field, registering the "dkim2" authentication method, the result values it can take, and two properties which identify the signing domain and the point in the chain at which verification failed. Diagnostic detail about each hop is carried in a human-readable comment. Proofpoint, Inc. HAProxy Technologies The Postfix Project The Postfix Project

Error Codes Error responses are Problem Details with the media type "application/problem+json", whatever serialization the registration uses, and an extension member "code" holding one of the codes below:

Status Code Meaning 400 INVALID_REQUEST Malformed body or missing required fields 400 INVALID_FILTER Filter is syntactically invalid 400 MISSING_REQUEST_ID MTA-Hooks-Request-Id is missing 401 AUTHENTICATION_REQUIRED No credentials were provided 401 INVALID_CREDENTIALS Credentials are invalid or expired 403 REGISTRATION_DENIED The MTA may not register 403 REGISTRATION_MISMATCH Credentials are not bound to the registration 404 REGISTRATION_NOT_FOUND No such registration 409 REGISTRATION_LIMIT_REACHED Too many registrations for this MTA 413 REQUEST_TOO_LARGE Request body larger than the scanner accepts 422 UNSUPPORTED_SERIALIZATION The serialization is not supported 422 UNSUPPORTED_STAGE A stage is not supported 422 UNSUPPORTED_PROPERTY A property is not supported 422 UNSUPPORTED_FILTER A filter condition is not supported 429 RATE_LIMITED Too many requests 500 INTERNAL_ERROR Unexpected error 503 UNAVAILABLE Temporarily unable to process requests

Acknowledgments The author thanks the operators of mailbox.org for their detailed proposals on routing, observability, and inbound signals, and the developers and operators of existing mail filtering systems whose experience informed this design.

Changes [[This section to be removed by RFC Editor]] draft-degennaro-mta-hooks-02 Responses are JSON Patch documents (RFC 6902), applied atomically; the custom set/add/delete format and its ordering rules are removed. Registrations consist of ordered subscriptions, each with its own filter, properties, grants, and failure policy. Filters gain connection conditions. Replaced updateProperties with grants that can restrict values and sizes. Ordered properties can only become stricter unless a grant relaxes them, which replaces the downgrade rule. The discovery document lists the changes a scanner wants as grants, replacing its actions and updates lists. Actions apply to inbound stages only. Outbound outcomes, including DSN suppression, are expressed through recipient status, replacing "continue" and "cancel". Removed the "defer" stage, which duplicated "delivery". At the "route" and "delivery" stages subscriptions are matched per recipient, so grants and failure handling apply only to the recipients a subscription matches. Added the "route" stage with per-recipient routes, and the "transmit" stage, which runs per SMTP transaction so scanners can sign each copy with its final envelope, as DKIM2 requires. Removed ARC, which the DMARC working group proposes to move to Historic, from sender authentication and added DKIM2. Bearer tokens (RFC 6750) are mandatory to implement. Error responses use Problem Details (RFC 9457). Header field values have a defined syntax. Serializations are named by media type; removed the serialization registry. The registration request carries the registration's label, and no longer carries metadata. A scanner can only narrow a registration by removing properties and grants. Certificates report a verification failure using RFC 8460 result types. Sessions also describe non-SMTP submissions. One Recipient object across all stages with a common status set and a decidedBy attribution; rejected recipients remain in the array; "failed-silent" became "discarded". Properties are no longer split by direction. Client, TLS, and authentication data are grouped into a Session object, which is available at outbound stages when the MTA knows it. Added session identifier and counters, proxy information, EHLO capabilities, certificate chains with verification result, per-attempt remote host and TLS details using RFC 8460 values, delayMs, a per-request timeoutMs, traceId, and extension data with message lifetime. Clarified ESMTP parameters and queue identifier stability. Added iprev to sender authentication. Dropped the "X-" prefix from header fields (RFC 6648) and added MTA-Hooks-Context. Simplified the registration lifecycle to GET and DELETE on the registration URL; removed the status endpoint, its statistics, the registration status and creation time, and the maxRegistrations limit. draft-degennaro-mta-hooks-01 Inverted the registration model: the MTA is now exclusively the HTTP client. Required a registration identifier and request identifier on every hook request. Specified authentication, error responses, and action precedence. draft-degennaro-mta-hooks-00 Initial version