mirror of
https://github.com/chatmail/core.git
synced 2026-04-26 01:46:34 +03:00
reformat: use shorter lines (max. 80 chats) and try to add linebreaks semantically
This commit is contained in:
B. Petersen
committed by
holger krekel
holger krekel
parent
8a3bf6a5d9
commit
00e929afac
180
spec.md
180
spec.md
@@ -2,7 +2,9 @@
|
||||
|
||||
Version 0.19.0
|
||||
|
||||
This document describes how emails can be used to implement typical messenger functions while staying compatible to existing MUAs.
|
||||
This document describes how emails can be used
|
||||
to implement typical messenger functions
|
||||
while staying compatible to existing MUAs.
|
||||
|
||||
- [Encryption](#encryption)
|
||||
- [Outgoing messages](#outgoing-messages)
|
||||
@@ -20,10 +22,14 @@ This document describes how emails can be used to implement typical messenger fu
|
||||
|
||||
# Encryption
|
||||
|
||||
Messages SHOULD be encrypted by the [Autocrypt](https://autocrypt.org/level1.html) standard; `prefer-encrypt=mutual` MAY be set by default.
|
||||
Messages SHOULD be encrypted by the
|
||||
[Autocrypt](https://autocrypt.org/level1.html) standard;
|
||||
`prefer-encrypt=mutual` MAY be set by default.
|
||||
|
||||
Meta data (at least the subject and all chat-headers) SHOULD be encrypted by the [Memoryhole](https://github.com/autocrypt/memoryhole) standard.
|
||||
If Memoryhole is not used, the subject of encrypted messages SHOULD be replaced by the string
|
||||
Meta data (at least the subject and all chat-headers) SHOULD be encrypted
|
||||
by the [Memoryhole](https://github.com/autocrypt/memoryhole) standard.
|
||||
If Memoryhole is not used,
|
||||
the subject of encrypted messages SHOULD be replaced by the string
|
||||
`Chat: Encrypted message` where the part after the colon MAY be localized.
|
||||
|
||||
|
||||
@@ -31,7 +37,8 @@ If Memoryhole is not used, the subject of encrypted messages SHOULD be replaced
|
||||
|
||||
Messengers MUST add a `Chat-Version: 1.0` header to outgoing messages.
|
||||
For filtering and smart appearance of the messages in normal MUAs,
|
||||
the `Subject` header SHOULD start with the characters `Chat:` and SHOULD be an excerpt of the message.
|
||||
the `Subject` header SHOULD start with the characters `Chat:`
|
||||
and SHOULD be an excerpt of the message.
|
||||
Replies to messages MAY follow the typical `Re:`-format.
|
||||
|
||||
The body MAY contain text which MUST have the content type `text/plain`
|
||||
@@ -41,8 +48,8 @@ The text MAY be divided into a user-text-part and a footer-part using the
|
||||
line `-- ` (minus, minus, space, lineend).
|
||||
|
||||
The user-text-part MUST contain only user generated content.
|
||||
User generated content are eg. texts a user has actually typed or pasted or
|
||||
forwarded from another user.
|
||||
User generated content are eg. texts a user has actually typed
|
||||
or pasted or forwarded from another user.
|
||||
Full quotes, footers or sth. like that MUST NOT go to the user-text-part.
|
||||
|
||||
From: sender@domain
|
||||
@@ -56,14 +63,19 @@ Full quotes, footers or sth. like that MUST NOT go to the user-text-part.
|
||||
|
||||
# Incoming messages
|
||||
|
||||
The `Chat-Version` header MAY be used to detect if a messages comes from a compatible messenger.
|
||||
The `Chat-Version` header MAY be used
|
||||
to detect if a messages comes from a compatible messenger.
|
||||
|
||||
The `Subject` header MUST NOT be used to detect compatible messengers, groups or whatever.
|
||||
The `Subject` header MUST NOT be used
|
||||
to detect compatible messengers, groups or whatever.
|
||||
|
||||
Messenger SHOULD show the `Subject` if the message comes from a normal MUA together with the email-body.
|
||||
The email-body SHOULD be converted to plain text, full-quotes and similar regions SHOULD be cut.
|
||||
Messenger SHOULD show the `Subject`
|
||||
if the message comes from a normal MUA together with the email-body.
|
||||
The email-body SHOULD be converted
|
||||
to plain text, full-quotes and similar regions SHOULD be cut.
|
||||
|
||||
Attachments SHOULD be shown where possible. If an attachment cannot be shown, a non-distracting warning SHOULD be printed.
|
||||
Attachments SHOULD be shown where possible.
|
||||
If an attachment cannot be shown, a non-distracting warning SHOULD be printed.
|
||||
|
||||
|
||||
# Forwarded messages
|
||||
@@ -90,21 +102,25 @@ which SHOULD be anonymized or just a placeholder.
|
||||
Hello world!
|
||||
|
||||
Incoming forwarded messages are detected by the header.
|
||||
The messenger SHOULD mark these messages in a way that it becomes obvious
|
||||
that the message is not created by the sender.
|
||||
Note that most messengers do not show the original sender with forwarded messages
|
||||
The messenger SHOULD mark these messages in a way that
|
||||
it becomes obvious that the message is not created by the sender.
|
||||
Note that most messengers do not show the original sender of forwarded messages
|
||||
but MUAs typically expose the sender in the UI.
|
||||
|
||||
|
||||
# Groups
|
||||
|
||||
Groups are chats with usually more than one recipient, each defined by an email-address.
|
||||
Groups are chats with usually more than one recipient,
|
||||
each defined by an email-address.
|
||||
The sender plus the recipients are the group members.
|
||||
|
||||
To allow different groups with the same members, groups are identified by a group-id.
|
||||
The group-id MUST be created only from the characters `0`-`9`, `A`-`Z`, `a`-`z` `_` and `-`.
|
||||
To allow different groups with the same members,
|
||||
groups are identified by a group-id.
|
||||
The group-id MUST be created only from the characters
|
||||
`0`-`9`, `A`-`Z`, `a`-`z` `_` and `-`.
|
||||
|
||||
Groups MUST have a group-name. The group-name is any non-zero-length UTF-8 string.
|
||||
Groups MUST have a group-name.
|
||||
The group-name is any non-zero-length UTF-8 string.
|
||||
|
||||
Groups MAY have a group-image.
|
||||
|
||||
@@ -113,13 +129,17 @@ Groups MAY have a group-image.
|
||||
|
||||
All group members MUST be added to the `From`/`To` headers.
|
||||
The group-id MUST be written to the `Chat-Group-ID` header.
|
||||
The group-name MUST be written to `Chat-Group-Name` header (the forced presence of this header makes it easier to join a group chat on a second device any time).
|
||||
The group-name MUST be written to `Chat-Group-Name` header
|
||||
(the forced presence of this header makes it easier
|
||||
to join a group chat on a second device any time).
|
||||
|
||||
The `Subject` header of outgoing group messages SHOULD start with the characters `Chat:` followed by the group-name and a colon followed by an excerpt of the message.
|
||||
The `Subject` header of outgoing group messages
|
||||
SHOULD start with the characters `Chat:`
|
||||
followed by the group-name and a colon followed by an excerpt of the message.
|
||||
|
||||
To identify the group-id on replies from normal MUAs, the group-id MUST also be added to
|
||||
the message-id of outgoing messages. The message-id MUST have the
|
||||
format `Gr.<group-id>.<unique data>`.
|
||||
To identify the group-id on replies from normal MUAs,
|
||||
the group-id MUST also be added to the message-id of outgoing messages.
|
||||
The message-id MUST have the format `Gr.<group-id>.<unique data>`.
|
||||
|
||||
From: member1@domain
|
||||
To: member2@domain, member3@domain
|
||||
@@ -131,30 +151,46 @@ format `Gr.<group-id>.<unique data>`.
|
||||
|
||||
Hello group - this group contains three members
|
||||
|
||||
Messengers adding the member list in the form `Name <email-address>` MUST take care only to spread the names authorized by the contacts themselves.
|
||||
Otherwise, names as _Daddy_ or _Honey_ may be spread (this issue is also true for normal MUAs, however, for more contact- and chat-centralized apps
|
||||
Messengers adding the member list in the form `Name <email-address>`
|
||||
MUST take care only to spread the names authorized by the contacts themselves.
|
||||
Otherwise, names as _Daddy_ or _Honey_ may be spread
|
||||
(this issue is also true for normal MUAs, however,
|
||||
for more contact- and chat-centralized apps
|
||||
such situations happen more frequently).
|
||||
|
||||
|
||||
## Incoming group messages
|
||||
|
||||
The messenger MUST search incoming messages for the group-id in the following headers: `Chat-Group-ID`,
|
||||
The messenger MUST search incoming messages for the group-id
|
||||
in the following headers: `Chat-Group-ID`,
|
||||
`Message-ID`, `In-Reply-To` and `References` (in this order).
|
||||
|
||||
If the messenger finds a valid and existent group-id, the message SHOULD be assigned to the given group.
|
||||
If the messenger finds a valid but not existent group-id, the messenger MAY create a new group.
|
||||
If no group-id is found, the message MAY be assigned to a normal single-user chat with the email-address given in `From`.
|
||||
If the messenger finds a valid and existent group-id,
|
||||
the message SHOULD be assigned to the given group.
|
||||
If the messenger finds a valid but not existent group-id,
|
||||
the messenger MAY create a new group.
|
||||
If no group-id is found,
|
||||
the message MAY be assigned
|
||||
to a normal single-user chat with the email-address given in `From`.
|
||||
|
||||
|
||||
## Add and remove members
|
||||
|
||||
Messenger clients MUST construct the member list from the `From`/`To` headers only on the first group message or if they see a `Chat-Group-Member-Added` or `Chat-Group-Member-Removed` action header.
|
||||
Both headers MUST have the email-address of the added or removed member as the value.
|
||||
Messenger clients MUST NOT construct the member list on other group messages (this is to avoid accidentally altered To-lists in normal MUAs; the user
|
||||
does not expect adding a user to a _message_ will also add him to the _group_ "forever").
|
||||
Messenger clients MUST construct the member list
|
||||
from the `From`/`To` headers only on the first group message
|
||||
or if they see a `Chat-Group-Member-Added`
|
||||
or `Chat-Group-Member-Removed` action header.
|
||||
Both headers MUST have the email-address
|
||||
of the added or removed member as the value.
|
||||
Messenger clients MUST NOT construct the member list
|
||||
on other group messages
|
||||
(this is to avoid accidentally altered To-lists in normal MUAs;
|
||||
the user does not expect adding a user to a _message_
|
||||
will also add him to the _group_ "forever").
|
||||
|
||||
The messenger SHOULD send an explicit mail for each added or removed member.
|
||||
The body of the message SHOULD contain a localized description about what happened
|
||||
The body of the message SHOULD contain
|
||||
a localized description about what happened
|
||||
and the message SHOULD appear as a message or action from the sender.
|
||||
|
||||
From: member1@domain
|
||||
@@ -190,7 +226,8 @@ with the value set to the old group name to all group members.
|
||||
The new group name goes to the header `Chat-Group-Name`.
|
||||
|
||||
The messenger SHOULD send an explicit mail for each name change.
|
||||
The body of the message SHOULD contain a localized description about what happened
|
||||
The body of the message SHOULD contain
|
||||
a localized description about what happened
|
||||
and the message SHOULD appear as a message or action from the sender.
|
||||
|
||||
From: member1@domain
|
||||
@@ -208,13 +245,17 @@ and the message SHOULD appear as a message or action from the sender.
|
||||
## Set group image
|
||||
|
||||
A group MAY have a group-image.
|
||||
To change or set the group-image, the messenger MUST attach an image file to a message and MUST add the header `Chat-Group-Image` with the
|
||||
value set to the image name.
|
||||
To change or set the group-image,
|
||||
the messenger MUST attach an image file to a message
|
||||
and MUST add the header `Chat-Group-Image`
|
||||
with the value set to the image name.
|
||||
|
||||
To remove the group-image, the messenger MUST add the header `Chat-Group-Image: 0`.
|
||||
To remove the group-image,
|
||||
the messenger MUST add the header `Chat-Group-Image: 0`.
|
||||
|
||||
The messenger SHOULD send an explicit mail for each group image change.
|
||||
The body of the message SHOULD contain a localized description about what happened
|
||||
The body of the message SHOULD contain
|
||||
a localized description about what happened
|
||||
and the message SHOULD appear as a message or action from the sender.
|
||||
|
||||
|
||||
@@ -239,20 +280,29 @@ and the message SHOULD appear as a message or action from the sender.
|
||||
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBw ...
|
||||
--==break==--
|
||||
|
||||
The image format SHOULD be image/jpeg or image/png. To save data, it is RECOMMENDED to add a `Chat-Group-Image` only on image changes.
|
||||
The image format SHOULD be image/jpeg or image/png.
|
||||
To save data, it is RECOMMENDED
|
||||
to add a `Chat-Group-Image` only on image changes.
|
||||
|
||||
|
||||
# Set profile image
|
||||
|
||||
A user MAY have a profile-image that MAY be spread to his contacts.
|
||||
To change or set the profile-image, the messenger MUST attach an image file to a message and MUST add the header `Chat-Profile-Image` with the
|
||||
value set to the image name.
|
||||
To change or set the profile-image,
|
||||
the messenger MUST attach an image file to a message
|
||||
and MUST add the header `Chat-Profile-Image`
|
||||
with the value set to the image name.
|
||||
|
||||
To remove the profile-image, the messenger MUST add the header `Chat-Profile-Image: 0`.
|
||||
To remove the profile-image,
|
||||
the messenger MUST add the header `Chat-Profile-Image: 0`.
|
||||
|
||||
To spread the image, the messenger MAY send the profile image together with the next mail to a given contact
|
||||
(to do this only once, the messenger has to keep a `profile_image_update_state` somewhere).
|
||||
Alternatively, the messenger MAY send an explicit mail for each profile-image change to all contacts using a compatible messenger.
|
||||
To spread the image,
|
||||
the messenger MAY send the profile image
|
||||
together with the next mail to a given contact
|
||||
(to do this only once,
|
||||
the messenger has to keep a `profile_image_update_state` somewhere).
|
||||
Alternatively, the messenger MAY send an explicit mail
|
||||
for each profile-image change to all contacts using a compatible messenger.
|
||||
The messenger SHOULD NOT send an explicit mail to normal MUAs.
|
||||
|
||||
From: sender@domain
|
||||
@@ -273,18 +323,25 @@ The messenger SHOULD NOT send an explicit mail to normal MUAs.
|
||||
AKCgkJi3j4l5kjoldfUAKCgkJi3j4lldfHjgWICwgIEBQYFBA ...
|
||||
--==break==--
|
||||
|
||||
The image format SHOULD be image/jpeg or image/png. Note that `Chat-Profile-Image` may appear together with all other headers, eg. there may be a
|
||||
`Chat-Profile-Image` and a `Chat-Group-Image` header in the same message. To save data, it is RECOMMENDED to add a `Chat-Profile-Image` header only on image changes.
|
||||
The image format SHOULD be image/jpeg or image/png.
|
||||
Note that `Chat-Profile-Image` may appear together with all other headers,
|
||||
eg. there may be a `Chat-Profile-Image` and a `Chat-Group-Image` header
|
||||
in the same message.
|
||||
To save data, it is RECOMMENDED to add a `Chat-Profile-Image` header
|
||||
only on image changes.
|
||||
|
||||
|
||||
# Miscellaneous
|
||||
|
||||
Messengers SHOULD use the header `Chat-Predecessor` instead of `In-Reply-To` as
|
||||
the latter one results in infinite threads on typical MUAs.
|
||||
Messengers SHOULD use the header `Chat-Predecessor`
|
||||
instead of `In-Reply-To` as the latter one results
|
||||
in infinite threads on typical MUAs.
|
||||
|
||||
Messengers SHOULD add a `Chat-Voice-message: 1` header if an attached audio file is a voice message.
|
||||
Messengers SHOULD add a `Chat-Voice-message: 1` header
|
||||
if an attached audio file is a voice message.
|
||||
|
||||
Messengers MAY add a `Chat-Duration` header to specify the duration of attached audio or video files.
|
||||
Messengers MAY add a `Chat-Duration` header
|
||||
to specify the duration of attached audio or video files.
|
||||
The value MUST be the duration in milliseconds.
|
||||
This allows the receiver to show the time without knowing the file format.
|
||||
|
||||
@@ -292,16 +349,23 @@ This allows the receiver to show the time without knowing the file format.
|
||||
Chat-Voice-Message: 1
|
||||
Chat-Duration: 10000
|
||||
|
||||
Messengers MAY send and receive Message Disposition Notifications (MDNs, [RFC 8098](https://tools.ietf.org/html/rfc8098), [RFC 3503](https://tools.ietf.org/html/rfc3503))
|
||||
using the `Chat-Disposition-Notification-To` header instead of the `Disposition-Notification-To` (which unfortunately forces many other MUAs to send weird mails not following any
|
||||
standard).
|
||||
Messengers MAY send and receive Message Disposition Notifications
|
||||
(MDNs, [RFC 8098](https://tools.ietf.org/html/rfc8098),
|
||||
[RFC 3503](https://tools.ietf.org/html/rfc3503))
|
||||
using the `Chat-Disposition-Notification-To` header
|
||||
instead of the `Disposition-Notification-To`
|
||||
(which unfortunately forces many other MUAs
|
||||
to send weird mails not following any standard).
|
||||
|
||||
|
||||
## Sync messages
|
||||
|
||||
If some action is required by a message header, the action should only be performed if the _effective date_ is newer than the date the last action was performed.
|
||||
If some action is required by a message header,
|
||||
the action should only be performed if the _effective date_ is newer
|
||||
than the date the last action was performed.
|
||||
|
||||
We define the effective date of a message as the sending time of the message as indicated by its Date header,
|
||||
We define the effective date of a message
|
||||
as the sending time of the message as indicated by its Date header,
|
||||
or the time of first receipt if that date is in the future or unavailable.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user