Mail: Write email

[kulmann]

Initial Checklist

• I understand this is a user story and questions should be posted in the Community Discussions
• I searched issues and couldn’t find anything (or linked relevant results below)

User Story

• As a user, I want to write an email so that I can communicate with my colleagues, customers, friends, etc.

User Value

Writing emails

Acceptance Criteria

• Writing email is available on a new route /mail/create
  • upon entering the compose view, we add draftId=new parameter to the url
  • when coming from the /mail/inbox route, add any existing parameter out of accountId, mailboxId, mailId to the url (if they exist)
• on mobile: compose view is filling the entire viewport
• on larger viewports: as a start, the compose view is also filling the entire viewport (we might think about a modal later on)
• view consists of:
  • header: close button, title "New message", send button (for now always disabled)
  • From (pre-select first identity of the default account), dropdown, lists all available identities
  • To (text input for now)
  • CC (text input for now)
  • BCC (text input for now)
  • Subject (text input)
  • Body (text area, use raw text editor for this issue as first iteration, sophisticated editor later)
  • Footer (not needed for now as we don't have any functionality like adding attachments, yet)

[pbleser-oc]

We had a conversation about where the "Send" button ought to be placed, either at the bottom (same as GMail) or in the top right corner (same as Apple Mail):

• it seems more natural in terms of email writing flow (pick To/CC, write a subject, write the email, send it), to have the Send button at the bottom as in the current mockups, to avoid having to move the finger to the top
• but that also bears a greater risk of accidentally hitting that Send button while writing the email, whereas having it at the top reduces that risk, precisely because one has to move their finger to the top, out of the way of the email body

After discussion, we tend to favour the top corner option.
This was submitted as a comment to the design agency.

[pbleser-oc]

Best practices in JMAP seem to recommend the following approach when creating and updating drafts:

1. create a new email using Email/set (or POST /groupware/accounts/{accountId}/emails using the Groupware API), with mailboxIds containing the ID of the Mailbox with the "role":"draft" property (e.g. {"mailboxIds":{"a":true}}), which sends back an Email id (as well as a blobId and threadId)
2. when explicitly or implicitly (autosave after 5min) updating the draft, create a new email using Email/set, adding "destroy":{"..."}to delete the previous draft (that's the PUT /groupware/accounts/{accountId}/emails/{emailId} endpoint in the Groupware)

The Email id of the draft is thus going to change over time (actually every time it is autosaved), and the UI needs to be able to update the corresponding property in the current URL (as a "replace" operation, to prevent the previous ID to still be in the browser history.)

When an Email is sent using EmailSubmission/set (not in the Groupware API yet at the time of writing), it can include a "transactional" operation to either

• delete the draft email (onSuccessDestroyEmail)
• update the draft email (onSuccessUpdateEmail)
  after it has been sent successfully.

The latter seems more likely, in order to then modify the draft to

• move it from the Drafts to the Sent folder
• remove the $draft flag

If the draft is destroyed: once the email has actually been sent, the draft email ID in the browser history refers to a non-existent email, to which the UI request to load that email (GET /groupware/accounts/{accountId}/emails/{emailId}) will return a 404.

But if the draft is moved to the Sent mailbox, then the ID refers to an existing email, albeit an Email that is not a draft (does not have the $draft keyword), the UI request to load it will succeed.

The UI should thus probably always check that the draft... is indeed a draft, when loading it.

[pbleser-oc]

When creating/replacing an Email (draft), the body can either

• have the full complexity of multipart MIME, using the bodyStructure and bodyValues properties (see JMAP Emails Examples)
• use the simplified structure with the textBody, htmlBody, attachments and bodyValues properties

Here an example of the latter (the "simple" format), which can be sent to the following endpoint:

POST /groupware/accounts/{accountId}/emails

Body:

{
  "mailboxIds": { "a": true },
  "keywords": { "$draft": true },
  "to": [{"name": "Camina Drummer", "email":"cdrummer@opa.org"}],
  "subject": "Oye Beltalowda",
  "textBody": [
    {"partId": "t123", "type": "text/plain"}
  ],
  "htmlBody": [
    {"partId": "h456", "type": "text/html"}
  ],
  "bodyValues": {
    "t123": {
      "value": "Oye, Beltalowda, this is your bosmang speaking."
    },
    "h456": {
      "value": "<html><body><p>Oye, Beltalowda.</p><p>This is your bosmang speaking.</p></body></html>",
    },
  },
  "attachments": [
    {
      "blobId": "<id of a blob that was already uploaded>",
      "name": "map.jpg",
      "type": "image/jpeg",
      "disposition": "attachment"
    }
  ]
}

200 OK response body:

{
    "id": "leaaaagl",
    "blobId": "cav10yznxf7fgmvtnadyje9fpwjqzpeuq0yge0othawc1g97usjmwaiazmaq",
    "threadId": "cz",
    "size": 288
}