Email Integration

Email Integration Developer Documentation

Feature Overview

This allows TaarifaWaterpoints users to interact with the API solely by email. It is built on Context.IO, which sends a webhook callback every time the app's email account gets a new message. The code extracts meaningful data out of the email message, structures it in a format that TaarifaAPI understands, and takes appropriate actions via the API to do whatever the user wants to do.

This should be a viable option to send/receive data via email in areas where there's limited connectivity. Most devices have email clients and can save drafts.

Setup dev environment

In order to set up TaarifaWaterpoints so it can translate emails into actions:

• an email account needs to be registered
• get a Context.IO API key
• link the email account to your Context.IO API key
• a Context.IO webhook needs to be set up
  • note: if developing on a localhost, ngrok must be used to receive the webhook

Register an email account

For development purposes, I registered [email protected]. Feel free to use this account! The password is SUPER SECRET (taarifareport). Really though, any email account will work as long as the email server supports the IMAP protocol, since that's how Context.IO is able to connect to the server and make all the email magic happen. Ideally, this account should probably be '[email protected]'

Get a Context.IO API key

Visit http://context.io and click the orange button to sign up for a free API key. It's free to use with a small number of email accounts, so no payment information is required. If you have any issues with that, let Tony ([email protected]) know and he'll (I'll ;) ) get you free usage. Be sure to verify the account by clicking the link in the email that you get after initially signing up. That activates your account and is required before you can use the API.

Link the email account to Context.IO

After you activate the account, then you're able to link up an email account in the admin console. First time you log into Context.IO, you should be prompted to add your first email account. If you do not see that, you can click on the "add account" button to start the flow to add an account. If the account provider is Gmail or Outlook.com, you will be prompted to authenticate via Oauth. If not, then you will be prompted to enter the email credentials.

After the account is added, Context.IO starts syncing the account, but the webhook feature is ready to use immediately.

Set up a Context.IO webhook

You need to do this in order for Context.IO to make a POST to TaarifaWaterpoints to notify the app that a new email has arrived. You're able to create a webhook using the interactive admin console and don't need to write any code. First thing you need is the ID of the email account. You can get this by logging into Context.IO and the first button (top left) in the admin site is called "accounts." This is a list of all the connected email accounts. In the info window that pops up on the right side, you should see an "id" field under Account Properties. Copy that then click the "explore" button on the top menu.

This is the interactive console. You can make API requests and see responses without writing any code. Navigate to the "webhooks" item in the left menu. It's under "accounts." After you click on that, you see some HTTP verbs at the top. You make a POST to this endpoint to create a new webhook. There's 2 required parameters - callback_url and failure_notif_url. The callback_url parameter is where Context.IO will make a POST request.

PAUSE

If you are developing on your localhost, you need to expose the /email view to the internet so Context.IO can do a POST. The best way to do this is with ngrok. (https://ngrok.com/) Go to that url and install ngrok. Usage is REALLY easy. Type this in a CLI.

ngrok 5000

That will start the tunnel for you. In the terminal, you'll see the public url that you should put in the callback_url parameter. Be sure that you append /email to the end of it, since that's the view that handles the emails.

UNPAUSE

For instance, this is what the callback_url parameter should look something like if you are using ngrok to tunnel to localhost:

callback_url: http://1ae28ef0.ngrok.com/email

The failure_notif_url parameter is less important now because the app doesn't handle webhooks that were failed to be delivered. This would be a good "TODO" to be sure that all webhooks are delivered.

There are a few optional params that should also be set.

• sync_period: 0
  • this will tell Context.IO to deliver the webhooks immediately upon receipt. From a practical standpoint, this usually is within 10 seconds, but could be a few minutes.
• include_body: 1
  • We want the webhook callback to include the body of the email!
• body_type: text/plain
  • we want the plain text body, not the HTML body.

If there are any questions about Context.IO don't hesitate to ask me, [email protected]. My day job is developer evangelist for them, and am waaay happy to help out. I mean, with anything too - stuff not related to Context.IO... with life. I give good life advice.

Checking the feature out

Ok, so you should have the flask dev server running, an email account set up, a Context.IO webhook on that account pointing to your local dev environment through ngrok. Phew!

So, if you tail -f taarifawaterpoints.log you should see the response from submitting the request to the TaarifaAPI.

You can also see the webhook come in on the terminal window that's running the flask dev server.

If the correct params are sent in the email, then you should be able to go to http://localhost:5000/api/requests and see the result of the request being submitted!

User documentation and TODO list

That's being maintained on Hackpad: https://taarifa.hackpad.com/Reporting-Via-Email-Fud605fAsek