We wish to allow Synapse users to contact each other via email. The feature request is here: PLFM-2527. This document suggests a design.
Design Features
Allow users to send emails to each other, and to Teams, using the synapse.org domain. E.g. if two users have usernames "Alice" and "Bob", allow Alice to send an email to "bob@synapse.org". Bob will receive the message at the email account he has registered with Synapse as his 'notification' address.
If Bob's User Profile notification settings have disabled email, then he will not receive the message.
The user name in the email addresses will be analyzed using Synapse's user name uniqueness rule, i.e. after stripping all non alphanumeric characters the unique Synapse user name (or team name) alias will be matched. (If no match is found, the message will be rejected.)
If Alice and Bob are on a Team, "Alice and Bobs Team", then Alice can send an email to "aliceandbobsteam@synapse.org". The message will be sent to each team member as if it were sent to them directly.
TODO: Shall we limit Team messaging in any way? E.g. can only Team admin's send messages to Teams? Shall we only allow messaging to small Teams? (We could even combine the two and allow all small Team members to email each other, but for large Teams only allow admin's to do so.)
MIKE: A suggestion - changing behavior based on Team size seems arbitrary, and likely to cause confusion in the use base. My proposal is that Team Managers can always send a message to all Team Members. Team Managers can change a Team configuration option "allow Team members to send messages to the team". Now, we've converted out debate into what the default should be. I feel less strongly about this, but would lean towards allowing the messaging, as I think it will be useful and not abused in the majority of the cases. But for cases such as the Challenge "All Users" teams, we could flip the switch the other way.
Each message will have a "one-click unsubscribe" footer, facilitating update of the recipient's notification settings to suppress email delivery.
Leveraging the Synapse Messaging System
Synapse has an existing system for sending messages, described here: Messaging services. This service requires the client to upload the body of an email to an S3 file, then create a message object referencing the file and containing other metadata (from, to, subject). We will leverage this by adding a component which receives emails and converts them to web requests. The service we have investigated for this purpose is http://www.cloudmailin.com/. CloudMailIn has an option to format requests as JSON, http://docs.cloudmailin.com/http_post_formats/json/
We will add the following service to the Messaging Services:
| Method | URI | Request Body | Parameters | Response Body | Permission |
|---|---|---|---|---|---|
| POST | /cloudMailInMessage | Message | notificationUnsubscribeEndpoint | none | Basic Authentication |
We add a JSON schema to lib-auto-generated, org.sagebionetworks.repo.model.message.cloudmailin.Message, describing the CloudMailIn JSON format. A POST containing this message is authorized using 'Basic Authentication'. Also it takes a parameter, notificationUnsubscribeEndpoint, which is the Synapse Portal endpoint for one-click unsubscription. The message content is uploaded to an S3 with a MIME type application/json.
The message metadata (to, from, subject) is saved in Synapse as a MessageToUser object. We add a new field, notificationUnsubscribeEndpoint, to capture this metadata, used during message delivery (see below).
Message Delivery
The Synapse message system delivers messages via calls to Amazon Simple Email Service (SES) by asynchronous workers. The message metadata and S3 file are retrieved and, depending on whether the MIME type is text/plain or text/html, a plain or html message is constructed using the SES 'Formatted Email' API (http://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-formatted.html). This system will be extended in two ways:
(1) For messages having MIME type application/json the CloudMailIn text, html, and attachments are assembled into a multipart message and sent via the SES 'raw' interface (http://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-raw.html);
(2) For all messages, whether plain, html, or a combination, a one-click unsubscribe footer will be added.