JSON Message Transport Protocol (JMTP)

Status: Internet-Draft (unofficial)

Last Updated: July 2025

Abstract

JMTP defines a JSON-based message transport protocol operating over HTTPS, suitable for secure, structured communication between organizations, systems, or individuals. JMTP is designed to replace or supplement traditional protocols such as SMTP for email or EDI for business messages.

1. Introduction

The protocol supports decoupled notification and retrieval phases. Senders post message notifications to recipients' endpoints, and recipients pull the full message if it passes validation or policy review.

2. Terminology

• Agent: Application module that handles message types.
• Notification: A summary message announcing availability of a full message.
• Envelope: The full JSON message including headers, body, and attachments.

3. Message Flow

1. Sender POSTs notification to recipient’s JMTP endpoint.
2. Recipient queues and validates message/agent assignment.
3. Recipient agent sends a GET or POST to retrieve the full message.
4. Agent processes message per business rules.

4. Message Structure

{
  "message_type": "email",
  "message_id": "1234567890",
  "from": "alice@example.com",
  "to": ["bob@example.com"],
  "subject": "Test Message",
  "body": {
    "text": "This is a test.",
    "html": "
This is a test.
"
  },
  "attachments": [
    {
      "filename": "doc.pdf",
      "content_type": "application/pdf",
      "content_base64": "..."
    }
  ]
}

5. Security

• All transport must be over HTTPS.
• JWT or mutual TLS authentication is recommended.
• Signatures can be used to verify integrity and sender identity.

6. Federation & Discovery

JMTP clients and servers should expose a discovery file at /.well-known/jmtp:

{
  "inbox": "https://example.org/api/jmtp/notify",
  "retrieval": "https://example.org/api/jmtp/retrieve"
}

7. Error Handling

• 400 - Malformed notification
• 401 - Unauthorized
• 404 - Unknown message ID
• 429 - Too many requests
• 501 - Unknown message type
• 503 - Recipient unavailable

8. SMTP Replacement Use Case

JMTP supports structured email messaging with headers and bodies defined in JSON. An SMTP-to-JMTP gateway can convert MIME email into JMTP messages. Message discovery uses DNS and /.well-known endpoints to locate recipient inboxes.

9. Future Work

• Schema registry for message types
• Decentralized trust model and routing
• Native client libraries and browser support