This post comes from Bruno Morency, President of Context.IO, the missing email API that makes it easy and fast to integrate your user's email data in your application. This application and walkthrough are designed to give you insight into the basics of what you can do by combining Context.IO and the Box platform. When you're done reading, go check out Context.IO!
We all know managing files in Box is a breeze, but the reality is most of us continue to exchange important files and messages via email. Wouldn’t it be great if there was a way to easily manage and sync all the files locked in email with your Box account? Enter Context.IO, the API that makes developing applications that use email data fast and easy.
We built EmailToBox.com as a showcase of how the Context.IO API can be used to easily integrate email data with Box. The concept of this app is pretty simple:
- Upon signup, the app creates an “EmailToBox” folder in the user’s email account and Box account (for Gmail, it creates an “EmailToBox” label),
- When users drag an email message to their new “EmailToBox” folder, the app will upload its attachments to the “EmailToBox” folder in their Box account.
In this post, we’ll go over the code behind the key functionality of this application:
- Connecting to the user’s mailbox
- Setting up a special tracked folder in the user’s mailbox
- Uploading files attached to messages placed in that special folder to Box
Connecting User Accounts
The first step is to handle registration of new users. To create an account on EmailToBox, new users first login their existing Box accounts so we can get an auth_token for it. The next step is to connect to the mailbox through Context.IO.
To handle that, we’ll use the connect_tokens functionality which handles the user workflow and redirects users to our app once the mailbox is connected to our Context.IO API key. Let’s see how this works:
If you want full control over the user experience to connect mailboxes, you can use direct API calls instead of a connect_token. The relevant calls are http://context.io/docs/latest/accounts#post to create a new account that matches our own users and then http://context.io/docs/latest/accounts/sources#post to add a source to that account for the user’s mailbox.
Creating the Special “EmailToBox” Tracked Folder
Now that we have a user connected to a Box account and an email account, the next step is to create the “EmailToBox” folders in both services. We create the folder in the Box account using the create_folder function. To create the folder in the email account, we’ll use the Folders resource of Context.IO as follows:
Just like that, the new folder has been created. The last step of the user setup is to monitor that folder for new messages placed in it. To do so, we simply use the Context.IO WebHooks with the filter_folder_added option. With this webhook functionality, all we need to do is define an event we want to track in the mailbox and tell Context.IO which URL to call on our app when it happens. Here’s how we set it up:
That’s it! We now have a complete user setup and our app will be notified when a new message is placed in the EmailToBox folder we created for that user.
Processing WebHook Callback
The last remaining piece is to handle the callback that Context.IO will make to our application when emails are placed by users in their EmailToBox folder. That callback is an HTTP POST call and the request body is a JSON object containing metadata about the message for which the webhook has been triggered. The exact format of that JSON object can be found here: http://context.io/docs/2.0/accounts/webhooks#callbacks. Let’s see how we handle these POST requests in our app:
Since the callback URL our app exposes to receive these callbacks needs to be accessible without any sessions or authentication, there must be a way to verify that the request is legitimate. This is what the signature, timestamp and token properties in the request body are for. This signature is the HMAC-SHA256 hash of the string formed by concatenating the timestamp and token properties using your Context.IO consumer secret as the hashing key. The last part in the code above recalculates that hash and makes sure it matches the one given in the request body. You can further increase security by rejecting any request with a timestamp older than a couple of minutes and making sure the same token isn’t used twice within that allowed time period. If you do so, we strongly recommend setting up NTP on your server to make sure your clock isn’t drifting too far. Now that we validated the callback request, the actual processing begins. First, we check if the message has any attachments, then we’ll upload them to the appropriate Box account:
Once we verified the emails have at least one attachment, the first thing we do is download the message body. Then, we loop through the attachments, download them from the mailbox and upload them to Box. Finally, after the upload is complete, we add the message body as a comment on the file we just uploaded.
As you can see, this app was really quite simple and very light on code, but in the end we built something very useful. While the examples above are really taken from the code running http://emailtobox.com, they have been trimmed down to make them simpler to read. We encourage you to explore and use the complete source code available in Context.IO’s GitHub profile: https://github.com/ContextIO/EmailToBox.
What do you think you can build with email? With all of the rich data being exchanged by email on a daily basis, we see email as a rich treasure trove of information just waiting to be leveraged in applications. We have CRM solutions, productivity tools, and of course, document management apps using us in pretty cool ways. We’d love to get some ideas on what you want to build - get in touch with us!
Context.IO API documentation: http://context.io/docs/latest
Get a free Context.IO API key: http://context.io/#signup
API Explorer: https://console.context.io/#explore
Context.IO on GitHub: https://github.com/ContextIO