Synapse Email Service

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.

We will allow Team administrators to control who has permission to send messages to the Team.

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:

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.