Introduction

The email gateway provides a simple architecture for Assembla tools to receive emails from users. Users can send emails to a tool to create a new object (eg. an email to space@tickets.assembla.com will create a new ticket) or they can reply to a real time alert to edit an object (eg. replying to a ticket alert will add your reply as a comment into the ticket).

The email gateway provides the following services to every tool:

• Redirects emails to the proper tool
• Checks permissions
• Detects if the emails is from a reply and get the id of the related object
• Cleans the content of the replied alert (if it's a reply)

Example

An example usage is the Email To Tickets Gateway which provides features to:

• Reply to a ticket email alerts and post the reply as a comment.
• Create or edit tickets by email.
• See the user guide at this page.

Configure

Make sure you configure Inbound emails by following these instructions.

Map Emails To Tools

The inbound email processor parses the To header of inbound emails to get the destination domain. It then uses this domain to map the email to a single Assembla tool. In config/settings.yml you will find settings to define the domain of your tool gateway. The key should be the id of the tool and the value should represent the domain where you expect users to send emails to this tool. Note that each tool requires a unique domain (or subdomain). For example, at Assembla.com, we have the following settings:

alert_hosts:
  tool_<%= FlowsTool::ID %>: alerts.assembla.com
  tool_<%= TicketTool::ID %>: tickets.assembla.com
  tool_<%= CustomerSupportTool::ID %>: support.assembla.com

However, for testing a new tool in your local environment, you will need to configure your local environment somewhat differently, for example:

alert_hosts:
  tool_<%= FlowsTool::ID %>: nil
  tool_<%= TicketTool::ID %>: nil
  tool_<%= CustomerSupportTool::ID %>: nil
  tool_<%= MyTool::ID %>: gmail.com

If you need to request a new production domain, please contact an administrator.

Parse Emails

Your tool will have to override the following method to parse the content of the email:
parse_email(email,user,object_id) where object_id is the id of the related object in case it's a reply (if not, it will be set to nil)

Check Permissions

Your tool can receive messages from owners, members or everyone. To define which group will have access to the email gateway, you need to override the accept_email_from method. The possible values are:

Space::MESSAGES_FROM_MEMBERS (default. Includes Members and Owners)
Space::MESSAGES_FROM_OWNERS (Only Owners)
Space::MESSAGES_FROM_ALL, (Includes Public in general, Members and Owners)

The user is identified by his email address.

Detect If The Email Is From A Reply

In case the user replies to a real time alert, the email gateway will provide the id of the related object when calling the parse_email(email,user,object_id) method from your tool. By default the id will be the event.obj_id. However, you can change this for your tool if you need a more friendly number by overriding the email_alert_id method.

Note: The object_id is retrieved from an email header called References. Users can also provide this id in the To email address with the following format:

space_name.wiki_name+object_id@tool_host

For example, "breakout+2@tickets.assembla.com" will attach a comment to ticket with number 2 in breakout space.

Clean The Content Of The Replied Alert

In case the user replies to a real time alert, the email body might contain information from the previous alert. The EmailUtils class provides a method called extract_body(mail,obj_id=nil) that will remove the content of the old reply if obj_id is passed.

Note that this method will return the clean body and the format (which might be HTML or plain). Read the comment in the class for more information about it.

Some Important Comments

1. Make sure to check the EmailUtils class. It has some methods that might be useful for your parsing:
   1. extract_body
   2. clean_html
   3. save_attachment
2. If your parse_email method takes a lot of processing, I strongly encourage you to locate the parser inside lib/breakout/email_processors for asynchronous processing (refer to examples for flow_parser and ticket_parser).