API Delivery-Service (Incoming Messages)
For more detailed information about delivery services, see the appendix. Relevant to DM3MTP (protocol) is the API to deliver messages (encrypted envelopes) only.
The delivery service is a JSON-RPC service, following the JSON-RPC 2.0 specification (see also [RPC1]).
API Delivery-Service (Incoming Messages)
Submit Message
Methode
Request
Response
Error codes
Get Properties of the Delivery Service
Methode
Response
Get the User's Profile Extension
Methode
Request
Response
To accept incoming messages, the delivery service MUST support the following JSON-RPC methods:
Submit Message
The submit message method is called to deliver the complete message envelope containing the delivery information and the encrypted message.
Methode
Request
The request delivers the encrypted envelope containing the message itself and the delivery information as EncryptionEnvelope.
Response
The response is as defined in the JSON-RPC specification. In case of an error, an error message is returned.
Example
Error codes
For default JSON-RPC error codes see appendix.
Additional, application specific error codes can be reported:
Error code | Error text | Description |
---|---|---|
-32000 | Invalid input | Missing or invalid parameters. |
-32001 | Resource not found | Requested resource not found. |
-32002 | Resource unavailable | Requested resource not available. |
-32003 | Unauthorized | The caller was not authorized to call this method. |
-32004 | Method not supported | Method is not implemented. |
-32005 | Limit exceeded | Request exceeds defined limit. |
-32006 | JSON-RPC version not supported | Version of JSON-RPC protocol is not supported. |
If the message is rejected from the delivery service, the following error codes will be returned:
Error code | Error text | Description |
---|---|---|
-32010 | Spam | The sender's address didn't fit the required spam protection settings. |
-32011 | Too big | The size of the message exceeds the approved maximum size. |
Get Properties of the Delivery Service
A delivery service provides a set of properties that a sending client MUST evaluate and observe. These properties can be informative or define what the sender of a message must follow in order for the delivery service to accept the message at all.
(compatibility information: it replaces the formerly defined mutableProfileExtension provided in the network.dm3.profile
)
Methode
Response
Message TTL: Defines, how long the delivery service guarantees to cache a message. After the guaranteed time, the message MAY be removed, even if it was not picked up by the receiver. The minimum MUST be 30 days. If the value is not set, or set to 0 or null, messages will be cached unlimited (default).
Size Limit: Each delivery service can define a maximum size of incoming messages. As the content of the message incl. attachments is encrypted for the receiver, the delivery service can't restrict attachments or other embedded data by its content. The only way is to restrict the total size of the message. A sender MUST check this property before sending the message, otherwise, the message may be rejected.
In case of an error, an error object is returned as described in error codes.
Get the User's Profile Extension
Profile extensions are mutable properties of a receiver (identified by his/her ENS Name, ...) that are not stored in the network.dm3.profile
and can be changed without the need for a transaction. As these properties may vary between different delivery services, each delivery service to which the user is connected must provide this information.
Methode
Request
The request passes the name of the receiver.
Response
The profileExtension contains configuration information of the receiver:
Encryption Scheme: (OPTIONAL) The default encryption scheme is x25519-chacha20-poly1305. If another encryption scheme needs to be used (e.g., because this is needed for an ecosystem that is integrated into dm3), this can be requested. The default algorithm MUST be accepted, too. Otherwise, it might be impossible for a sender to deliver a message when it doesn't support the requested algorithm. This is a list of supported schemes, sorted by importance. All listed algorithms MUST be supported by the receiver. The sender is free to choose but should use receiver's preferences if supported.
Supported Message Types: The receiver MUST provide a list of all message types that the client he/she uses is supporting (see message data structure). The message type NEW MUST be supported always and is set as default in case no information is delivered. The sender MUST NOT send unsupported messages, as the receiver will not accept those messages.
Other information (like spam protection settings) can be added to this struct (defined in protocol extensions).
Example Profile Exception:
In case of an error, an error object is returned as described in error codes.
Last updated