MTA Hooks: An HTTP-Based Mail Processing Protocol

1.1. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

The following terms are used throughout this document:¶

• MTA (Mail Transfer Agent): A software component responsible for transferring electronic mail messages between hosts, as described in [RFC5321].¶

• Hook Endpoint: An HTTP server endpoint that receives hook invocations from an MTA and returns processing instructions.¶

• Scanner: A service that registers with an MTA to receive hook invocations. Scanners perform functions such as spam filtering, virus scanning, or policy enforcement. The terms "scanner" and "hook endpoint" are used interchangeably when referring to the service receiving hook requests.¶

• Registration: The process by which a scanner establishes a relationship with an MTA, including capability negotiation and callback URL configuration.¶

• Inbound Processing: Hook invocation during message reception, when the MTA accepts a message from a remote SMTP client.¶

• Outbound Processing: Hook invocation during message delivery, when the MTA transmits a message to a remote SMTP server.¶

• Stage: A specific point in mail processing at which the MTA invokes registered hooks. Different stages provide access to different message properties.¶

• Action: An instruction from a scanner indicating how the MTA should proceed with message processing.¶

• Modification: A change to message properties requested by a scanner, expressed as operations on the hook request object.¶

1.3. Data Types

This specification defines several object types used throughout the protocol. The following primitive types are used:¶

String

A JSON string value.¶

Int

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

UnsignedInt

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

Boolean

A JSON boolean value (true or false).¶

UTCDate

A string in "date-time" format as defined in [RFC3339], where the time-offset component MUST be "Z" (UTC time). For example, "2024-12-21T15:30:00Z".¶

2.1. Architecture

The protocol architecture consists of three primary components:¶

1. The MTA, which initiates HTTP requests to scanner endpoints at configured processing stages.¶

2. Scanner services, which receive requests, perform analysis, and return responses containing actions and modifications.¶

3. A registration mechanism through which scanners declare their capabilities and subscribe to specific processing stages.¶

+-------+                              +---------+
|       |  1. Discovery Request        |         |
|       |----------------------------->|         |
|       |  2. Discovery Response       |         |
|       |<-----------------------------|         |
|       |                              |         |
|       |  3. Registration Request     |         |
|  MTA  |----------------------------->| Scanner |
|       |  4. Registration Response    |         |
|       |<-----------------------------|         |
|       |                              |         |
|       |  5. Hook Request             |         |
|       |----------------------------->|         |
|       |  6. Hook Response            |         |
|       |<-----------------------------|         |
+-------+                              +---------+

The protocol flow proceeds as follows:¶

1. The MTA discovers scanner capabilities by requesting the well-known discovery endpoint.¶

2. The scanner returns a discovery document describing supported stages, actions, and configuration options.¶

3. The scanner submits a registration request specifying desired stages, properties, and callback configuration.¶

4. The MTA validates the request, optionally verifies the callback endpoint, and returns registration confirmation.¶

5. During mail processing, the MTA invokes the scanner's callback URL with message properties and context.¶

6. The scanner returns a response containing an action and optional modifications.¶

2.2. Serialization

Requests and responses are serialized using either JSON [RFC8259] or CBOR [RFC8949]. The serialization format is negotiated during registration and indicated via HTTP Content-Type headers.¶

For JSON serialization, the Content-Type header MUST be "application/json". For CBOR serialization, the Content-Type header MUST be "application/cbor".¶

Binary data handling differs between formats. In JSON serialization, binary content such as message body parts MUST be encoded using Base64. In CBOR serialization, binary content SHOULD be transmitted as raw byte strings.¶

2.3. Processing Stages

MTA Hooks defines processing stages for both inbound and outbound message handling. Scanners subscribe to specific stages during registration and receive invocations only for subscribed stages.¶

2.4. Inbound Message Processing

During inbound processing, the MTA invokes registered hooks as it receives messages from remote SMTP clients. This corresponds to traditional mail filtering scenarios where external services inspect incoming mail for spam, viruses, or policy violations.¶

The inbound flow proceeds through SMTP protocol stages:¶

1. A remote client connects to the MTA.¶

2. The MTA invokes hooks registered for the "connect" stage.¶

3. The client sends EHLO/HELO; the MTA invokes "ehlo" stage hooks.¶

4. The client sends MAIL FROM; the MTA invokes "mail" stage hooks.¶

5. The client sends one or more RCPT TO commands; the MTA invokes "rcpt" stage hooks for each.¶

6. The client sends DATA and message content; the MTA invokes "data" stage hooks.¶

At each stage, scanners may instruct the MTA to accept, reject, or modify the transaction.¶

2.5. Outbound Message Processing

During outbound processing, the MTA invokes registered hooks as it delivers messages to remote SMTP servers. This supports use cases including delivery logging, compliance monitoring, and routing decisions.¶

The outbound flow proceeds as follows:¶

1. The MTA selects a queued message for delivery and identifies the recipients due for delivery at this time.¶

2. The MTA attempts delivery to all selected recipients.¶

3. After all attempts in this delivery job complete, the MTA invokes hooks registered for the "delivery" stage.¶

4. If any recipient requires retry, the MTA invokes "defer" stage hooks.¶

5. If the MTA generates a DSN, it invokes "dsn" stage hooks before sending.¶

A delivery job represents a single processing cycle where the MTA retrieves a message from the queue and attempts delivery to one or more recipients. The specific batching of recipients into delivery jobs is implementation-defined and may depend on factors such as destination domain, connection reuse, or queue configuration. The "delivery" stage hook is invoked once per delivery job after all recipient attempts within that job have completed.¶

Scanners may modify per-recipient delivery status, suppress DSN generation, or alter retry scheduling.¶

2.6. Modifications

Scanners communicate changes through modifications to the hook request object. Modifications are expressed as operations on JSON Pointers [RFC6901] referencing properties within the request structure.¶

Three modification operations are supported:¶

• Set: Replace the value at a specified path.¶

• Add: Insert a value at a specified path, including array element insertion.¶

• Delete: Remove the value at a specified path.¶

The MTA applies modifications in a defined order: set operations first, followed by add operations, and finally delete operations. Any modification that fails (for example, referencing a non-existent path for deletion) SHOULD be logged and included in failure statistics, but MUST NOT cause the entire response to be rejected.¶

If a scanner modifies both the "message" and "rawMessage" properties, the "rawMessage" modification takes precedence and "message" modifications are ignored.¶

3.1. Well-Known Endpoint

Scanners that support discovery MUST expose a discovery document at the path "/.well-known/mta-hooks". The MTA retrieves this document using an HTTP GET request.¶

The discovery endpoint MUST support JSON serialization. Support for CBOR serialization is OPTIONAL.¶

3.2. Discovery Document Format

The discovery document is a JSON or CBOR object containing the following fields:¶

version: String

The protocol version. This specification defines version "1.0".¶

endpoints: DiscoveryEndpoints

URLs for protocol operations.¶

serialization: String[]

Supported serialization formats. Valid values are "json" and "cbor".¶

capabilities: DiscoveryCapabilities

Supported protocol capabilities.¶

limits: DiscoveryLimits|null

Operational limits, or null if no specific limits are advertised.¶

extensions: String[]|null

Supported protocol extensions. Extension identifiers SHOULD use a reverse domain name prefix for vendor-specific extensions.¶

A DiscoveryEndpoints object has the following properties:¶

registration: String

URL path for submitting registration requests.¶

deregistration: String

URL path template for deregistration, with "{registration_id}" placeholder.¶

A DiscoveryCapabilities object has the following properties:¶

inbound: DirectionCapabilities|null

Inbound processing capabilities, or null if inbound processing is not supported.¶

outbound: DirectionCapabilities|null

Outbound processing capabilities, or null if outbound processing is not supported.¶

A DirectionCapabilities object has the following properties:¶

stages: String[]

Supported stages for this processing direction.¶

actions: String[]

Supported actions that scanners may request.¶

fetchProperties: String[]

JSON Pointers for properties the MTA can include in hook requests.¶

updateProperties: String[]

JSON Pointers for properties scanners may modify.¶

A DiscoveryLimits object has the following properties:¶

maxMessageSize: UnsignedInt|null

Maximum message size in bytes the scanner accepts.¶

maxRegistrations: UnsignedInt|null

Maximum concurrent registrations.¶

timeoutMs: UnsignedInt|null

Default timeout in milliseconds for hook invocations.¶

The fetchProperties and updateProperties arrays contain JSON Pointers as defined in [RFC6901]. Each pointer identifies a property within the hook request structure that the MTA supports including or that scanners may modify. For example, "/envelope/from/address" refers to the sender's email address within the envelope object.¶

{
  "version": "1.0",

  "endpoints": {
    "registration": "/v1/hooks/register",
    "deregistration": "/v1/hooks/register/{registration_id}"
  },

  "serialization": ["json", "cbor"],

  "capabilities": {
    "inbound": {
      "stages": ["connect", "ehlo", "mail", "rcpt", "data"],
      "actions": ["accept", "reject", "discard",
                  "quarantine", "disconnect"],
      "fetchProperties": ["/envelope", "/message", "/rawMessage",
                          "/server", "/tls", "/auth", "/senderAuth",
                          "/client", "/stage", "/action",
                          "/timestamp","/response", "/protocol",
                          "/queue"],
      "updateProperties": ["/envelope", "/message", "/rawMessage",
                           "/action", "/response"]
    },
    "outbound": {
      "stages": ["delivery", "defer", "dsn"],
      "actions": ["continue", "cancel"],
      "fetchProperties": ["/envelope", "/message", "/rawMessage",
                          "/server", "/queue", "/stage", "/action",
                          "/timestamp", "/protocol"],
      "updateProperties": ["/envelope/to", "/action", "/message",
                           "/rawMessage"]
    }
  },

  "limits": {
    "maxMessageSize": 52428800,
    "maxRegistrations": 64,
    "timeoutMs": 30000
  },

  "extensions": ["x-vendor-feature"]
}

3.3. Manual Configuration

Discovery is OPTIONAL. Administrators MAY configure scanner endpoints manually, including capability restrictions and authentication credentials. Manual configuration may be necessary in environments where the well-known endpoint is not accessible or where policy requires explicit configuration.¶

4.1. Registration Request

Scanners submit registration requests via HTTP POST to the registration endpoint. The request body contains a JSON or CBOR object with the following fields:¶

name: String

Human-readable name identifying the scanner.¶

version: String|null

Scanner software version string.¶

callback: CallbackConfig

Callback configuration.¶

expiresAt: UTCDate|null

Requested registration expiration timestamp. The MTA MAY assign a different expiration based on policy.¶

serialization: String

Requested serialization format for hook requests. MUST be a value from the MTA's supported serialization list.¶

inbound: StageSubscription|null

Inbound hook configuration. Omit or set to null if not subscribing to inbound stages.¶

outbound: StageSubscription|null

Outbound hook configuration. Omit or set to null if not subscribing to outbound stages.¶

filter: FilterOperator|FilterCondition|null

Filter configuration to limit which messages trigger hooks. Uses filter syntax from Section 5.5 of [RFC8620].¶

metadata: String[String]|null

Arbitrary key-value pairs for scanner identification and operational metadata.¶

A CallbackConfig object has the following properties:¶

url: String

HTTPS URL where the MTA sends hook requests.¶

timeoutMs: UnsignedInt|null

Requested timeout in milliseconds. The MTA MAY ignore or cap this value.¶

A StageSubscription object has the following properties:¶

stages: String[]

Stages to subscribe to. MUST be a subset of the MTA's supported stages for this direction.¶

properties: String[]|null

JSON Pointers specifying message properties to receive. A value of null requests all supported properties.¶

At least one of "inbound" or "outbound" MUST be present and non-null in the registration request.¶

POST /v1/hooks/register HTTP/1.1
Host: mta.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "name": "Acme Spam Filter",
  "version": "2.1.0",

  "callback": {
    "url": "https://scanner.example.com/hooks/scan",
    "timeoutMs": 25000
  },

  "expiresAt": "2025-12-21T15:30:00Z",

  "serialization": "json",

  "inbound": {
    "stages": ["data"],
    "properties": ["/message", "/envelope", "/senderAuth"]
  },

  "outbound": {
    "stages": ["delivery"],
    "properties": null
  },

  "filter": {
    "operator": "OR",
    "conditions": [
      {"from": "*@external.example.com"},
      {"envelopeFrom": "*@partner.example.org"}
    ]
  },

  "metadata": {
    "vendor": "acme-security",
    "environment": "production",
    "instance": "scanner-01"
  }
}

4.2. Callback Verification

Upon receiving a registration request, the MTA SHOULD verify that the callback URL is reachable and operated by the registering party. Verification proceeds as follows:¶

1. The MTA generates a unique verification token.¶

2. The MTA sends an HTTP POST request to the callback URL with Content-Type set to the serialization format requested in the registration request. The request body contains:¶

{
  "action": "verify",
  "token": "vrf_8f3a2b1c9d4e5f6a7b8c9d0e1f2a3b4c"
}

1. The scanner MUST respond with HTTP status 200 and a body containing the same token:¶

{
  "token": "vrf_8f3a2b1c9d4e5f6a7b8c9d0e1f2a3b4c"
}

1. The MTA confirms the response token matches the request token.¶

If verification fails, the MTA MUST reject the registration request:¶

• If the callback URL is unreachable or times out: HTTP 422 with error code CALLBACK_UNREACHABLE¶

• If the callback responds but the token does not match: HTTP 422 with error code CALLBACK_VERIFICATION_FAILED¶

• If the callback URL does not use HTTPS: HTTP 422 with error code TLS_REQUIRED¶

• If the callback URL's TLS certificate is invalid: HTTP 422 with error code TLS_CERTIFICATE_INVALID¶

4.3. Registration Response

Upon successful registration, the MTA returns HTTP status 201 Created with a response body containing:¶

registrationId: String

Unique identifier for this registration. The identifier MUST consist of ASCII alphanumeric characters plus hyphen (-), underscore (_), and colon (:), with a maximum length of 255 characters.¶

status: String

Registration status. Values are "active", "suspended", or "pending_verification".¶

createdAt: UTCDate

Timestamp of registration creation.¶

expiresAt: UTCDate|null

Timestamp when registration expires, or null if no expiration is set.¶

callback: CallbackConfig

Confirmed callback configuration, which may differ from the request if the MTA adjusted values.¶

negotiated: NegotiatedCapabilities

Final negotiated capabilities representing the intersection of scanner request and MTA support.¶

endpoints: RegistrationEndpoints

URLs for managing this registration.¶

A NegotiatedCapabilities object has the following properties:¶

serialization: String

Confirmed serialization format.¶

inbound: NegotiatedSubscription|null

Confirmed inbound configuration, or null if not registered for inbound processing.¶

outbound: NegotiatedSubscription|null

Confirmed outbound configuration, or null if not registered for outbound processing.¶

A NegotiatedSubscription object has the following properties:¶

stages: String[]

Confirmed stages.¶

properties: String[]

Confirmed property list.¶

A RegistrationEndpoints object has the following properties:¶

deregistration: String

URL for deregistration requests.¶

status: String

URL for status queries.¶

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/hooks/register/reg_7a3b9c2e-4d5f-6a7b-8c9d-0e1f2a3b4c5d

{
  "registrationId": "reg_7a3b9c2e-4d5f-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "active",
  "createdAt": "2024-12-21T15:30:00Z",
  "expiresAt": "2025-12-21T15:30:00Z",

  "callback": {
    "url": "https://scanner.example.com/hooks/scan",
    "timeoutMs": 25000
  },

  "negotiated": {
    "serialization": "json",
    "inbound": {
      "stages": ["data"],
      "properties": ["/message", "/envelope", "/senderAuth"]
    },
    "outbound": {
      "stages": ["delivery"],
      "properties": ["/message", "/envelope", "/queue", "/server"]
    }
  },

  "endpoints": {
    "deregistration": "/v1/hooks/register/reg_7a3b9c2e",
    "status": "/v1/hooks/register/reg_7a3b9c2e/status"
  }
}

4.4. Authentication

Authentication for registration requests is REQUIRED but the specific mechanism is out of scope for this specification. Implementations SHOULD support at least one of the following authentication methods:¶

• Bearer tokens via the HTTP Authorization header¶

• Mutual TLS with client certificate verification¶

• HMAC-based pre-shared key authentication¶

See Section 9 for deployment guidance on authentication.¶

4.5. Registration Lifecycle

GET /v1/hooks/register/reg_7a3b9c2e/status HTTP/1.1
Host: mta.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "registrationId": "reg_7a3b9c2e-4d5f-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "active",
  "createdAt": "2024-12-21T15:30:00Z",
  "expiresAt": "2025-12-21T15:30:00Z",
  "lastInvocation": "2024-12-21T16:42:18Z",

  "statistics": {
    "invocations": {
      "total": 15482,
      "last24h": 3241,
      "last7d": 10234,
      "last30d": 43210
    },
    "errors": {
      "total": 32,
      "last24h": 5,
      "last7d": 12,
      "last30d": 28
    },
    "averageResponseMs": 45
  },

  "health": {
    "status": "healthy",
    "lastCheck": "2024-12-21T16:44:00Z",
    "consecutiveFailures": 0
  }
}

4.6. Deregistration

Scanners deregister by sending an HTTP DELETE request to the deregistration endpoint.¶

DELETE /v1/hooks/register/reg_7a3b9c2e HTTP/1.1
Host: mta.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Upon successful deregistration, the MTA returns HTTP status 200 with confirmation:¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "registrationId": "reg_7a3b9c2e-4d5f-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "deregistered",
  "deregisteredAt": "2024-12-21T16:45:00Z"
}

After deregistration, the MTA MUST NOT send further hook invocations to the scanner's callback URL.¶

5.1. Request Structure

Hook requests are transmitted via HTTP POST to the scanner's callback URL. The Content-Type header indicates the serialization format negotiated during registration.¶

The MTA MAY include an X-MTA-Hooks-Registration header containing the registration identifier. This header is OPTIONAL but can assist scanners that handle multiple registrations at a single endpoint.¶

The request body contains a JSON or CBOR object with properties determined by the scanner's registration. The following sections describe available properties organized by category.¶

5.2. Common Properties

The following properties are available for both inbound and outbound processing:¶

stage: String

The current processing stage.¶

action: String

The action the MTA will perform if no scanner modifications occur. For inbound processing, values are "accept", "reject", "discard", "quarantine", or "disconnect". For outbound processing, values are "continue" or "cancel".¶

envelope: Envelope

The message envelope containing sender and recipient information.¶

message: Object|null

A structured representation of the email message based on the Email object defined in Section 4 of [RFC8621].¶

rawMessage: String|null

The complete message in Internet Message Format as defined in [RFC5322]. In JSON serialization, the value is Base64-encoded. In CBOR serialization, the value is a raw byte string.¶

timestamp: UTCDate

Timestamp when the current stage began.¶

protocol: ProtocolInfo|null

Protocol information.¶

queue: QueueInfo|null

Queue information.¶

server: ServerInfo|null

Information about the MTA.¶

5.3. Envelope Properties

An Envelope object has the following properties:¶

from: EnvelopeAddress

Sender information from MAIL FROM command.¶

to: EnvelopeAddress[]|DeliveryRecipient[]

Recipient information from RCPT TO commands. For inbound processing, this is an array of EnvelopeAddress objects. For outbound processing, this is an array of DeliveryRecipient objects.¶

An EnvelopeAddress object represents an address in the message envelope and has the following properties:¶

address: String|null

The email address. For MAIL FROM, this MAY be null to represent the null reverse-path. For RCPT TO, this MUST NOT be null.¶

parameters: String[String]

SMTP parameters associated with the address as key-value pairs. Common parameters include ORCPT, ENVID, and other DSN-related parameters defined in [RFC3461].¶

For outbound processing, recipient objects include additional delivery status fields described in Section 5.9.¶

5.4. Queue Properties

A QueueInfo object has the following properties:¶

id: String

Unique queue identifier for this message within this MTA. The identifier MUST be unique for the lifetime of the message in the queue and SHOULD remain stable across hook invocations for the same queued message.¶

5.5. Message Properties

5.6. Server Properties

A ServerInfo object has the following properties:¶

name: String

Server hostname.¶

ip: String

Server IP address.¶

port: UnsignedInt

Server port number.¶

5.7. Protocol Properties

A ProtocolInfo object has the following properties:¶

version: String

MTA Hooks protocol version.¶

5.8. Inbound Properties

The following properties are available only during inbound processing:¶

response: SmtpResponse|null

The SMTP response the MTA would send if no scanner modifications occur.¶

client: ClientInfo|null

Information about the connecting SMTP client.¶

senderAuth: SenderAuthentication|null

Results of sender authentication checks.¶

auth: SmtpAuthentication|null

SMTP authentication information, if the client authenticated.¶

tls: TlsInfo|null

TLS connection information.¶

5.9. Outbound Properties

The following properties are available only during outbound processing.¶

5.10. Example Inbound Hook Request

POST /hooks/scan HTTP/1.1
Host: scanner.example.com
Content-Type: application/json
X-MTA-Hooks-Registration: reg_7a3b9c2e

{
  "stage": "data",
  "action": "accept",
  "timestamp": "2024-12-21T16:30:00Z",

  "response": {
    "code": 250,
    "enhancedCode": "2.0.0",
    "message": "OK"
  },

  "protocol": {
    "version": "1.0"
  },

  "queue": {
    "id": "queue_abc123"
  },

  "envelope": {
    "from": {
      "address": "sender@example.org",
      "parameters": {}
    },
    "to": [
      {
        "address": "recipient@example.com",
        "parameters": {}
      }
    ]
  },

  "message": {
    "size": 2048,
    "subject": "Meeting Tomorrow",
    "from": [
      {
        "name": "Sender Name",
        "email": "sender@example.org"
      }
    ],
    "to": [
      {
        "email": "recipient@example.com"
      }
    ],
    "sentAt": "2024-12-21T16:29:00Z",
    "messageId": ["<msg123@example.org>"],
    "headers": [
      {"name": "From", "value": "Sender Name <sender@example.org>"},
      {"name": "To", "value": "recipient@example.com"},
      {"name": "Subject", "value": "Meeting Tomorrow"},
      {"name": "Date", "value": "Sat, 21 Dec 2024 16:29:00 +0000"},
      {"name": "Message-ID", "value": "<msg123@example.org>"}
    ],
    "bodyStructure": {
      "type": "text/plain",
      "charset": "utf-8",
      "size": 28
    },
    "bodyValues": {
      "1": {
        "value": "Let's meet tomorrow at 10am.",
        "isEncodingProblem": false,
        "isTruncated": false
      }
    }
  },

  "client": {
    "ip": "192.0.2.100",
    "port": 54321,
    "ptr": "mail.example.org",
    "ehlo": "mail.example.org",
    "activeConnections": 3
  },

  "server": {
    "name": "mx1.example.com",
    "ip": "198.51.100.25",
    "port": 25
  },

  "tls": {
    "version": "TLSv1.3",
    "cipher": "TLS_AES_256_GCM_SHA384",
    "cipherBits": 256
  },

  "senderAuth": {
    "spf-mail": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  }
}

5.11. Example Outbound Hook Request

POST /hooks/delivery HTTP/1.1
Host: scanner.example.com
Content-Type: application/json
X-MTA-Hooks-Registration: reg_7a3b9c2e

{
  "stage": "delivery",
  "action": "continue",
  "timestamp": "2024-12-21T17:00:00Z",

  "protocol": {
    "version": "1.0"
  },

  "queue": {
    "id": "queue_def456",
    "expiresAt": "2024-12-24T17:00:00Z",
    "attempts": 3
  },

  "envelope": {
    "from": {
      "address": "notifications@example.com",
      "parameters": {}
    },
    "to": [
      {
        "address": "user1@recipient.example",
        "parameters": {},
        "status": "delivered",
        "attempt": 1,
        "lastResponse": {
          "code": 250,
          "enhancedCode": "2.0.0",
          "message": "Message accepted"
        }
      },
      {
        "address": "user2@recipient.example",
        "parameters": {},
        "status": "deferred",
        "attempt": 3,
        "lastResponse": {
          "code": 451,
          "enhancedCode": "4.7.1",
          "message": "Try again later"
        },
        "nextAttemptAt": "2024-12-21T18:00:00Z",
        "nextDsnAt": "2024-12-22T17:00:00Z"
      }
    ]
  },

  "message": {
    "subject": "Your order has shipped",
    "from": [{"email": "notifications@example.com"}],
    "to": [
      {"email": "user1@recipient.example"},
      {"email": "user2@recipient.example"}
    ],
    "size": 4096
  },

  "server": {
    "name": "smtp-out.example.com",
    "ip": "198.51.100.50",
    "port": 25
  }
}

6.1. Response Structure

Scanners respond with an HTTP 200 status code. The response body contains a JSON or CBOR object specifying modifications to apply to the hook request. The object has the following fields:¶

set: SetOperation[]|null

An array of set operations to apply, or null if no set operations.¶

add: AddOperation[]|null

An array of add operations to apply, or null if no add operations.¶

delete: DeleteOperation[]|null

An array of delete operations to apply, or null if no delete operations.¶

A SetOperation object has the following properties:¶

path: String

JSON Pointer (per [RFC6901]) to the property to replace.¶

value: any

The new value for the property.¶

An AddOperation object has the following properties:¶

path: String

JSON Pointer to the location where the value should be added.¶

value: any

The value to add.¶

index: UnsignedInt|null

For array additions, the zero-based index at which to insert the value. If null or omitted, the value is appended to the array.¶

A DeleteOperation object has the following properties:¶

path: String

JSON Pointer to the property to remove.¶

6.2. Actions

Scanners change the MTA's action by including a set operation targeting the "/action" path. The following values are valid for inbound and outbound processing respectively.¶

The following action values are valid:¶

6.3. Modifications

Scanners communicate changes by specifying operations on the hook request object. The response contains JSON Pointer paths identifying properties to modify and the operations to perform. These modifications can alter any aspect of the transaction that the MTA permits, including:¶

• The action the MTA should take (accept, reject, quarantine, etc.)¶

• The SMTP response to send to the client or expect from the server¶

• Message headers and body content¶

• Envelope addresses (sender and recipients)¶

• Per-recipient delivery status for outbound processing¶

Three modification operations are supported:¶

set

Replace the value at a specified path with a new value.¶

add

Insert a value at a specified path. For objects, this adds a new property. For arrays, this inserts an element at the specified index or appends if no index is given.¶

delete

Remove the value at a specified path.¶

{
  "set": [
    {
      "path": "/action",
      "value": "reject"
    },
    {
      "path": "/response",
      "value": {
        "code": 550,
        "enhancedCode": "5.7.1",
        "message": "Message rejected due to policy"
      }
    }
  ]
}

{
  "add": [
    {
      "path": "/message/headers",
      "value": {"name": "X-Spam-Score", "value": "5.2"},
      "index": 0
    },
    {
      "path": "/envelope/to",
      "value": {
        "address": "archive@example.com",
        "parameters": {}
      }
    }
  ]
}

{
  "delete": [
    {"path": "/message/headers/3"},
    {"path": "/message/headers/1"}
  ]
}

6.4. Example Hook Responses

HTTP/1.1 200 OK
Content-Type: application/json

{
  "add": [
    {
      "path": "/message/headers",
      "value": {"name": "X-Spam-Status", "value": "No"},
      "index": 0
    },
    {
      "path": "/message/headers",
      "value": {"name": "X-Spam-Score", "value": "1.2"},
      "index": 1
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "set": [
    {
      "path": "/action",
      "value": "reject"
    },
    {
      "path": "/response",
      "value": {
        "code": 550,
        "enhancedCode": "5.7.1",
        "message": "Message rejected: virus detected"
      }
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "set": [
    {
      "path": "/message/subject",
      "value": "[EXTERNAL] Original Subject"
    }
  ],
  "add": [
    {
      "path": "/envelope/to",
      "value": {
        "address": "compliance@example.com",
        "parameters": {}
      }
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "set": [
    {
      "path": "/envelope/to/1/status",
      "value": "failed-silent"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{}

7.1. HTTP Version

Implementations MUST support HTTP/1.1 [RFC9112]. Implementations SHOULD support HTTP/2 [RFC9113] for improved performance through multiplexing. Implementations MAY support HTTP/3 [RFC9114].¶

When multiple HTTP versions are available, implementations SHOULD prefer newer versions for their performance benefits while maintaining fallback to HTTP/1.1.¶

7.2. TLS Requirements

All MTA Hooks communications MUST use TLS. Implementations MUST support TLS 1.2 [RFC5246] and SHOULD support TLS 1.3 [RFC8446].¶

Implementations MUST validate server certificates against trusted certificate authorities. Self-signed certificates SHOULD NOT be accepted in production deployments unless explicitly configured by administrators.¶

Cipher suite selection SHOULD follow current best practices. Implementations SHOULD disable cipher suites known to be weak or compromised.¶

7.3. Request Methods

The following HTTP methods are used:¶

• GET: Discovery document retrieval and status queries¶

• POST: Registration requests and hook invocations¶

• DELETE: Deregistration requests¶

7.4. Content Negotiation

For hook requests and responses, the Content-Type header MUST be set to "application/json" for JSON serialization or "application/cbor" for CBOR serialization.¶

The Accept header MAY be used during discovery to indicate preferred serialization format. If the scanner cannot provide the requested format, it SHOULD return the discovery document in JSON format.¶

7.5. Error Handling

7.6. Connection Management

Implementations SHOULD use connection pooling to reduce latency for repeated requests to the same scanner endpoint. HTTP/2 multiplexing, where available, reduces the need for multiple connections.¶

Implementations SHOULD respect HTTP keep-alive semantics and connection limits advertised by scanners.¶

8.1. MTA Considerations

8.2. Scanner Considerations

8.3. Large Message Handling

Large messages present challenges for both MTAs and scanners. Implementations SHOULD consider:¶

• Message size limits advertised in discovery documents¶

• Truncation policies for oversized messages¶

• Memory management for large message bodies¶

Streaming or chunked delivery is not currently specified. For very large messages, implementations MAY arrange out-of-band content retrieval, though this is outside the scope of this specification.¶

8.4. High Availability

9.1. Authentication and Authorization

Authentication of registration requests is critical to prevent unauthorized scanners from receiving email content. Implementations MUST require authentication for registration operations.¶

Recommended authentication approaches:¶

• Bearer tokens: Simple to implement; tokens should be generated with sufficient entropy and rotated periodically.¶

• Mutual TLS: Provides strong authentication and binds identity to transport security.¶

• HMAC signatures: Allows authentication without transmitting secrets; requires secure key distribution.¶

Authorization policies SHOULD restrict which scanners may register and what capabilities they may request. Policies may be based on scanner identity, requested stages, or other criteria.¶

9.2. Transport Security

All MTA Hooks communications MUST use TLS to protect message content and authentication credentials in transit. Implementations MUST validate certificates to prevent man-in-the-middle attacks.¶

For internal network deployments, administrators may choose to use private certificate authorities. However, disabling certificate validation is NOT RECOMMENDED even for internal communications.¶

9.3. Message Confidentiality

Email messages frequently contain sensitive personal or business information. Scanners necessarily receive access to message content to perform their functions. Deployments SHOULD consider:¶

• Data handling policies for scanner operators¶

• Logging policies that avoid recording message content¶

• Data retention limits at scanner endpoints¶

• Regulatory requirements such as GDPR for personal data processing¶

9.4. Denial of Service

9.5. Injection Attacks

Scanner responses contain modifications applied to message processing. Implementations MUST validate all scanner-provided data:¶

• Header values MUST be validated to prevent header injection¶

• Recipient addresses MUST be validated against policy¶

• Body modifications MUST not introduce malformed content¶

9.6. Privacy Considerations

Email processing inherently involves access to personal communications. Implementations SHOULD minimize data exposure:¶

• Scanners SHOULD request only necessary properties¶

• MTAs SHOULD honor property restrictions from capability negotiation¶

• Logging SHOULD avoid recording message content or metadata¶

• Scanner operators SHOULD implement appropriate data protection measures¶

10.1. Well-Known URI Registration

This document registers the following well-known URI per [RFC8615]:¶

URI suffix: mta-hooks¶

Change controller: IETF¶

Specification document: This document¶

Status: permanent¶

Related information: N/A¶

10.2. MTA Hooks Serialization Format Registry

IANA is requested to create a new registry entitled "MTA Hooks Serialization Formats" with the following initial contents:¶

• Format: json¶

  • Description: JSON serialization per RFC 8259¶

  • Reference: This document¶

• Format: cbor¶

  • Description: CBOR serialization per RFC 8949¶

  • Reference: This document¶

New registrations require Specification Required per [RFC8126].¶

10.3. MTA Hooks Inbound Action Registry

IANA is requested to create a new registry entitled "MTA Hooks Inbound Actions" with the following initial contents:¶

• Action: accept¶

  • Description: Accept message for delivery¶

  • Reference: This document¶

• Action: reject¶

  • Description: Reject message with error response¶

  • Reference: This document¶

• Action: discard¶

  • Description: Accept but do not deliver message¶

  • Reference: This document¶

• Action: quarantine¶

  • Description: Place message in quarantine¶

  • Reference: This document¶

• Action: disconnect¶

  • Description: Terminate SMTP connection¶

  • Reference: This document¶

New registrations require Specification Required per [RFC8126].¶

10.4. MTA Hooks Outbound Action Registry

IANA is requested to create a new registry entitled "MTA Hooks Outbound Actions" with the following initial contents:¶

• Action: continue¶

  • Description: Proceed with normal delivery processing¶

  • Reference: This document¶

• Action: cancel¶

  • Description: Cancel pending deliveries¶

  • Reference: This document¶

New registrations require Specification Required per [RFC8126].¶

10.5. MTA Hooks Inbound Stage Registry

IANA is requested to create a new registry entitled "MTA Hooks Inbound Stages" with the following initial contents:¶

• Stage: connect¶

  • Description: Client connection established¶

  • Reference: This document¶

• Stage: ehlo¶

  • Description: EHLO/HELO command received¶

  • Reference: This document¶

• Stage: mail¶

  • Description: MAIL FROM command received¶

  • Reference: This document¶

• Stage: rcpt¶

  • Description: RCPT TO command received¶

  • Reference: This document¶

• Stage: data¶

  • Description: Message content received¶

  • Reference: This document¶

New registrations require Specification Required per [RFC8126].¶

10.6. MTA Hooks Outbound Stage Registry

IANA is requested to create a new registry entitled "MTA Hooks Outbound Stages" with the following initial contents:¶

• Stage: delivery¶

  • Description: Delivery attempt completed¶

  • Reference: This document¶

• Stage: defer¶

  • Description: Delivery deferred for retry¶

  • Reference: This document¶

• Stage: dsn¶

  • Description: DSN generation pending¶

  • Reference: This document¶

New registrations require Specification Required per [RFC8126].¶

10.7. MTA Hooks Error Code Registry

IANA is requested to create a new registry entitled "MTA Hooks Error Codes" with the initial contents specified in Appendix A.¶

New registrations require Specification Required per [RFC8126].¶

11.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3339]

Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <https://www.rfc-editor.org/rfc/rfc3339>.

[RFC5246]

Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <https://www.rfc-editor.org/rfc/rfc5246>.

[RFC5321]

Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, DOI 10.17487/RFC5321, October 2008, <https://www.rfc-editor.org/rfc/rfc5321>.

[RFC5322]

Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, <https://www.rfc-editor.org/rfc/rfc5322>.

[RFC6901]

Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, <https://www.rfc-editor.org/rfc/rfc6901>.

[RFC8126]

Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/rfc/rfc8126>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC8446]

Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/rfc/rfc8446>.

[RFC8615]

Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <https://www.rfc-editor.org/rfc/rfc8615>.

[RFC8620]

Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, <https://www.rfc-editor.org/rfc/rfc8620>.

[RFC8621]

Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, August 2019, <https://www.rfc-editor.org/rfc/rfc8621>.

[RFC8949]

Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, <https://www.rfc-editor.org/rfc/rfc8949>.

[RFC9112]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, June 2022, <https://www.rfc-editor.org/rfc/rfc9112>.

[RFC9113]

Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, DOI 10.17487/RFC9113, June 2022, <https://www.rfc-editor.org/rfc/rfc9113>.

[RFC9114]

Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114, June 2022, <https://www.rfc-editor.org/rfc/rfc9114>.

11.2. Informative References

[RFC3461]

Moore, K., "Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs)", RFC 3461, DOI 10.17487/RFC3461, January 2003, <https://www.rfc-editor.org/rfc/rfc3461>.

[RFC6376]

Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., "DomainKeys Identified Mail (DKIM) Signatures", STD 76, RFC 6376, DOI 10.17487/RFC6376, September 2011, <https://www.rfc-editor.org/rfc/rfc6376>.

[RFC7208]

Kitterman, S., "Sender Policy Framework (SPF) for Authorizing Use of Domains in Email, Version 1", RFC 7208, DOI 10.17487/RFC7208, April 2014, <https://www.rfc-editor.org/rfc/rfc7208>.

[RFC7489]

Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based Message Authentication, Reporting, and Conformance (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015, <https://www.rfc-editor.org/rfc/rfc7489>.

A.1. Error Response Structure

Error responses use the following structure:¶

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

A.2. HTTP 400 Bad Request

• INVALID_REQUEST: Malformed JSON/CBOR or missing required fields.¶

• INVALID_CALLBACK_URL: Callback URL is malformed or uses disallowed scheme.¶

• CAPABILITY_MISMATCH: Requested capability not supported by MTA.¶

• INVALID_STAGE: One or more requested stages are not valid.¶

• INVALID_ACTION: One or more requested actions are not valid.¶

• INVALID_MODIFICATION: One or more requested modifications are not valid.¶

• NO_STAGES_REQUESTED: Neither inbound nor outbound stages were specified.¶

• FILTER_INVALID: Filter configuration is syntactically invalid.¶

A.3. HTTP 401 Unauthorized

• AUTHENTICATION_REQUIRED: No authentication credentials provided.¶

• INVALID_CREDENTIALS: Provided credentials are invalid or expired.¶

A.4. HTTP 403 Forbidden

• REGISTRATION_DENIED: Valid credentials but not authorized to register.¶

• DOMAIN_NOT_ALLOWED: Scanner not authorized for requested domains.¶

• CALLBACK_NOT_ALLOWED: Callback URL not in allowlist.¶

A.5. HTTP 404 Not Found

• REGISTRATION_NOT_FOUND: No registration exists with the specified ID.¶

A.6. HTTP 409 Conflict

• ALREADY_REGISTERED: Scanner with same callback URL already registered.¶

• REGISTRATION_LIMIT_REACHED: Maximum number of registrations exceeded.¶

A.7. HTTP 422 Unprocessable Entity

• UNSUPPORTED_FILTER: The filter contains conditions that are not supported by this MTA.¶

• CALLBACK_UNREACHABLE: MTA could not reach callback URL for verification.¶

• CALLBACK_VERIFICATION_FAILED: Callback URL responded but verification failed.¶

• TLS_REQUIRED: Callback URL must use HTTPS.¶

• TLS_CERTIFICATE_INVALID: Callback URL TLS certificate is invalid or untrusted.¶

A.8. HTTP 429 Too Many Requests

• RATE_LIMITED: Too many registration attempts; retry after specified time.¶

A.9. HTTP 500 Internal Server Error

• INTERNAL_ERROR: Unexpected server error during processing.¶

A.10. HTTP 503 Service Unavailable

• REGISTRATION_DISABLED: Registration temporarily disabled by administrator.¶

B.1. Inbound Spam Filtering

This example shows a complete flow for spam filtering during inbound message reception.¶

GET /.well-known/mta-hooks HTTP/1.1
Host: scanner.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "version": "1.0",
  "endpoints": {
    "registration": "/v1/hooks/register",
    "deregistration": "/v1/hooks/register/{registration_id}"
  },
  "serialization": ["json"],
  "capabilities": {
    "inbound": {
      "stages": ["data"],
      "actions": ["accept", "reject", "quarantine"],
      "fetchProperties": ["/message", "/envelope", "/senderAuth",
                          "/client"],
      "updateProperties": ["/message/headers", "/action", "/response"]
    }
  },
  "limits": {
    "maxMessageSize": 26214400,
    "timeoutMs": 30000
  }
}

POST /v1/hooks/register HTTP/1.1
Host: scanner.example.com
Content-Type: application/json
Authorization: Bearer sk_live_abc123

{
  "name": "SpamFilter Pro",
  "version": "3.0.1",
  "callback": {
    "url": "https://filter.example.net/hooks/spam",
    "timeoutMs": 20000
  },
  "serialization": "json",
  "inbound": {
    "stages": ["data"],
    "properties": ["/message", "/envelope", "/senderAuth", "/client"]
  },
  "metadata": {
    "customer": "acme-corp"
  }
}

POST /hooks/spam HTTP/1.1
Host: filter.example.net
Content-Type: application/json

{
  "action": "verify",
  "token": "vrf_xyz789"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "vrf_xyz789"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/hooks/register/reg_spam_001

{
  "registrationId": "reg_spam_001",
  "status": "active",
  "createdAt": "2024-12-21T10:00:00Z",
  "expiresAt": "2025-01-21T10:00:00Z",
  "callback": {
    "url": "https://filter.example.net/hooks/spam",
    "timeoutMs": 20000
  },
  "negotiated": {
    "serialization": "json",
    "inbound": {
      "stages": ["data"],
      "properties": ["/message", "/envelope", "/senderAuth", "/client"]
    }
  },
  "endpoints": {
    "deregistration": "/v1/hooks/register/reg_spam_001",
    "status": "/v1/hooks/register/reg_spam_001/status"
  }
}

POST /hooks/spam HTTP/1.1
Host: filter.example.net
Content-Type: application/json
X-MTA-Hooks-Registration: reg_spam_001

{
  "stage": "data",
  "action": "accept",
  "timestamp": "2024-12-21T10:30:00Z",
  "response": {
    "code": 250,
    "enhancedCode": "2.0.0",
    "message": "OK"
  },
  "envelope": {
    "from": {"address": "alice@sender.example", "parameters": {}},
    "to": [{"address": "bob@recipient.example", "parameters": {}}]
  },
  "message": {
    "subject": "Quarterly Report",
    "from": [{"email": "alice@sender.example", "name": "Alice Smith"}],
    "to": [{"email": "bob@recipient.example"}],
    "size": 15360,
    "bodyValues": {
      "1": {
        "value": "Please find attached the Q4 report...",
        "isEncodingProblem": false,
        "isTruncated": false
      }
    }
  },
  "senderAuth": {
    "spf-mail": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  },
  "client": {
    "ip": "192.0.2.50",
    "ehlo": "mail.sender.example"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "add": [
    {
      "path": "/message/headers",
      "value": {"name": "X-Spam-Status", "value": "No, score=0.5"},
      "index": 0
    }
  ]
}

POST /hooks/spam HTTP/1.1
Host: filter.example.net
Content-Type: application/json
X-MTA-Hooks-Registration: reg_spam_001

{
  "stage": "data",
  "action": "accept",
  "timestamp": "2024-12-21T10:35:00Z",
  "response": {
    "code": 250,
    "enhancedCode": "2.0.0",
    "message": "OK"
  },
  "envelope": {
    "from": {"address": "promo@spammer.invalid", "parameters": {}},
    "to": [{"address": "bob@recipient.example", "parameters": {}}]
  },
  "message": {
    "subject": "YOU HAVE WON $1,000,000!!!",
    "from": [{"email": "winner@lottery.invalid"}],
    "to": [{"email": "bob@recipient.example"}],
    "size": 8192
  },
  "senderAuth": {
    "spf-mail": "fail",
    "dkim": "none",
    "dmarc": "fail"
  },
  "client": {
    "ip": "203.0.113.99",
    "ehlo": "totally-legit.invalid"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "set": [
    {
      "path": "/action",
      "value": "reject"
    },
    {
      "path": "/response",
      "value": {
        "code": 550,
        "enhancedCode": "5.7.1",
        "message": "Message rejected due to spam content"
      }
    }
  ]
}

B.2. Outbound Delivery Logging

This example shows outbound hook usage for delivery status logging and compliance.¶

POST /v1/hooks/register HTTP/1.1
Host: mta.example.com
Content-Type: application/json
Authorization: Bearer sk_live_def456

{
  "name": "Delivery Logger",
  "version": "1.0.0",
  "callback": {
    "url": "https://logger.example.net/hooks/delivery",
    "timeoutMs": 5000
  },
  "serialization": "json",
  "outbound": {
    "stages": ["delivery", "dsn"],
    "actions": ["continue"],
    "properties": null
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "registrationId": "reg_logger_001",
  "status": "active",
  "createdAt": "2024-12-21T11:00:00Z",
  "negotiated": {
    "serialization": "json",
    "outbound": {
      "stages": ["delivery", "dsn"],
      "actions": ["continue"],
      "properties": ["/envelope", "/message", "/queue", "/context"]
    }
  },
  "endpoints": {
    "deregistration": "/v1/hooks/register/reg_logger_001",
    "status": "/v1/hooks/register/reg_logger_001/status"
  }
}

POST /hooks/delivery HTTP/1.1
Host: logger.example.net
Content-Type: application/json
X-MTA-Hooks-Registration: reg_logger_001

{
  "stage": "delivery",
  "action": "continue",
  "timestamp": "2024-12-21T12:00:00Z",
  "queue": {
    "id": "q_msg_12345",
    "expiresAt": "2024-12-24T12:00:00Z",
    "attempts": 1
  },
  "envelope": {
    "from": {"address": "notify@example.com", "parameters": {}},
    "to": [
      {
        "address": "user1@active.example",
        "parameters": {},
        "status": "delivered",
        "attempt": 1,
        "lastResponse": {
          "code": 250,
          "enhancedCode": "2.0.0",
          "message": "Delivered"
        }
      },
      {
        "address": "user2@slow.example",
        "parameters": {},
        "status": "deferred",
        "attempt": 1,
        "lastResponse": {
          "code": 451,
          "enhancedCode": "4.7.1",
          "message": "Greylisted, try again"
        },
        "nextAttemptAt": "2024-12-21T12:15:00Z"
      },
      {
        "address": "user3@invalid.example",
        "parameters": {},
        "status": "failed",
        "attempt": 1,
        "lastResponse": {
          "code": 550,
          "enhancedCode": "5.1.1",
          "message": "User unknown"
        }
      }
    ]
  },
  "message": {
    "subject": "System Notification",
    "messageId": "<notify-12345@example.com>",
    "size": 2048
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "action": "continue"
}

B.3. Deregistration

DELETE /v1/hooks/register/reg_spam_001 HTTP/1.1
Host: scanner.example.com
Authorization: Bearer sk_live_abc123

HTTP/1.1 200 OK
Content-Type: application/json

{
  "registrationId": "reg_spam_001",
  "status": "deregistered",
  "deregisteredAt": "2024-12-21T18:00:00Z"
}