Gmail is one of the largest Mailbox Providers in the world, so you probably want to make sure your Context.IO powered application can properly connect to Gmail. There are several things you need to know before implementing your Gmail integration.
Oauth, not password
In Context.IO, you can add email accounts via password or oauth. Authenticating users via password only works great for IMAP providers that do not support oauth, like Yahoo, Aol, or generic IMAP providers. For providers that support OAuth, like Gmail (and Outlook), it is always preferred by the provider that developers use oauth to authenticate and add users.
Gmail is known to throttle connection attempts made via plain password, and will sometimes even block them if it deems the application making the request as “unsafe.”
We often see developers who try to add a user account by plain password get the following error message:
Please log in via your web browser: https://support.google.com/mail/accounts/answer/78754.
If you visit the page included in the error message, you can see that Gmail is deeming the application making a connection attempt as “unsafe” and is asking the user to login via web browser instead.
This error does not happen on connection attempts made via oauth. For this reason, we recommend developers always use oauth for authenticating / adding Gmail accounts.
Context.IO faciliates oauth
Context.IO has a "connect tokens" feature that facilitates the oauth process for developers. A developer simply needs to POST to
lite/connect_tokens with the email address they wish to add as a param to initiate the oauth process. If you use our connect tokens feature, Context.IO will even handle the refreshing of connect tokens for you!
Alternatively, if you do not wish to use this feature, you can handle your own oauth process and simply pass us your provider key and provider refresh token.
Customizing your provider keys
If you use Context.IO connect tokens, we highly recommend you get your own Google API key. If you do not add a custom Google API key, the application will default to use Context.IO’s Google API key. If your application uses Context.IO’s Google API key, the end-user will see “Context.IO” in their list of applications, not your application, and this can cause confusion.
We recommend you get your own Google API key and add it to Context.IO. This makes it clear for users to see which application is accessing their account and reduces confusion.
To use custom Google API keys and add them to Context.IO:
- Go to the Google Developer Console: https://console.developers.google.com
- You should now see the Google Developer Console dashboard. Click on the dropdown next to the search bar, then click on "Create a project…"
- With the new project created, now click on "Credentials" under the API Manager sidebar on the screen.
- BEFORE YOU DO ANYTHING you need to set-up your OAuth consent screen. Click on the "OAuth consent screen" link to do this.
- Customize your product name, this is what will be show to users when authenticating. You can also add custom branding and other information. Click save.
- Now click on "Credentials", then click on the "Create credentials" drop-down. Select "Oauth client id".
- Select your application type, and name your application. Click save.
- Now, login to console.context.io
- Click on Settings, then "OAuth access to IMAP"
- Select "Standard Gmail" and fill in your Consumer Key and Consumer Secret.
Skipping Context.IO connect screens
If you are using Context.IO connect tokens, you might have noticed some Context.IO screens where we gather some information and also ask the user to ensure they are logged in to their account before redirecting the user to the provider-specific consent screen.
If you would like to skip the "make sure you’re logged in screen", you can append "
skip_oauth_splash=1" to the
browser_redirect_url you get from the POST
Keep in mind these screens cannot be skipped for non-oauth accounts. You will also not be able to skip these screens if you do not pass in an email address as part of the
connect_token request (otherwise we don’t know where to redirect a user).