Build awesome things with email! We take the pain out of syncing email data with your app so you can focus on what makes your product great.

CIOAPIClient is an easy to use iOS and OS X library for communicating with the Context.IO 2.0 API. It is built upon NSURLSession and provides convenient asynchronous block based methods for interacting with the API.

Getting Started

• Sign up for a developer account at Context.IO
• Submit a request for a 3-legged OAuth Token. This library only supports 3-legged tokens to ensure end-users of your application can only access their own account
• Download CIOAPIClient and check out the included iOS example app. It is also available as a CocoaPod to make it even easier to add to your project
• View the full Context.IO API documentation to better familiarize yourself with the API

Building the Example App

After cloning the git repository, make sure to install cocoapods used by the example app:

• cd <repository path>/Example
• pod install
• open "Context.IO iOS Example App.xcworkspace"

To run the example application, you will need to insert your Context.IO consumer key and secret in CIOAppDelegate.m.

Exploring the API in a Playground

There is a pre-configured Xcode Playground (currently targeting Xcode 6.4 + Swift 1.2) in the CIOPlayground directory. Playgrounds with library dependencies are slightly finicky with Xcode 6.4, follow these steps to get it working:

• cd CIOPlayground
• pod install
• Open CIOPlayground.xcworkspace
• Select the CIOAPIClient Scheme in the Xcode scheme selection dropdown (it should have a dynamic framework yellow toolbox icon)
• Build the scheme (⌘B)
• Select CIOPlayground.playground from the CIOPlayground project in the Project navigator left sidebar
• Add your consumer key and consumer secret to the line

let s: CIOAPISession = CIOAPISession(consumerKey: "", consumerSecret: "")

• At this point the playground will execute and an authentication WebView will appear in the bottom left corner of your screen
• Authorize an email account using the Context.IO auth flow in the WebView
  • The first time the code executes after authentication it may fail. Edit the playground to try again.
• Add any code you wish to try to the authenticator.withAuthentication() { session in block in the playground

Example Usage

Use CIOAPISession to construct and execute signed NSURLRequests against the Context.IO API.

Beginning an API Session

Initialize CIOAPISession with your API key consumer key and consumer secret:

CIOAPISession *session = [[CIOAPISession alloc] initWithConsumerKey:@"your-consumer-key"
                                                     consumerSecret:@"your-consumer-secret"];

Authentication

CIOAPISession uses Connect Tokens to authorize individual user's email accounts. Please see the example application for an overview of the authentication process. Feel free to re-use or subclass CIOAuthViewController in your own project - it takes care of the details of authentication and should work out of the box for most purposes.

Retrieve Messages

[[session getMessagesWithParams:nil]
 executeWithSuccess:^(NSArray *responseArray) {
     self.messagesArray = responseArray;
 } failure:^(NSError *error) {
     NSLog(@"error getting messages: %@", error);
 }];

Add a Message to an Existing Folder/Label

[[session updateFoldersForMessageWithID:message[@"message_id"]
                                 params:@{@"add": @"Test Label"}]
 executeWithSuccess:^(NSDictionary *response) {
     NSLog(@"Response: %@", response);
 } failure:^(NSError *error) {
     NSLog(@"error moving message: %@", error);
 }];

List Folders/Labels For An Account

// 0 is an alias for the first source of an account
[[session getFoldersForSourceWithLabel:@"0" params:nil]
 executeWithSuccess:^void(NSArray *folders) {
     NSLog(@"Folders: %@", folders);
 } failure:^void(NSError *error) {
     NSLog(@"Error getting folders: %@", error);
 }];

Download A Message Attachment

NSDictionary *file = [message[@"files"] firstObject];
CIODownloadRequest *downloadRequest = [session downloadContentsOfFileWithID:file[@"file_id"]];
// Save file with attachment's filename in NSDocumentDirectory
NSURL *documentsURL = [[[NSFileManager defaultManager] URLsForDirectory:NSDocumentDirectory
                                                              inDomains:NSUserDomainMask] lastObject];
NSURL *fileURL = [documentsURL URLByAppendingPathComponent:file[@"file_name"]];
[session downloadRequest:downloadRequest
               toFileURL:fileURL
                 success:^{
                     NSLog(@"File downloaded: %@", [fileURL path]);
                 }
                 failure:^(NSError *error) {
                     NSLog(@"Download error: %@", error);
                 }
                progress:^(int64_t bytesRead, int64_t totalBytesRead, int64_t totalBytesExpected){
                    NSLog(@"Download progress: %0.2f%%",
                          ((double)totalBytesExpected / (double)totalBytesRead) * 100);
                }];

Requirements

CIOAPIClient requires either iOS 7.0 and above or Mac OS 10.9 or above.

Acknowledgements

Thanks to Kevin Lord who wrote the original version of this library, Sam Soffes for sskeychain, and TweetDeck for TDOAuth which is used for the OAuth signature generation in CIOAPIClient.

License

CIOAPIClient is licensed under the MIT License. See the LICENSE file for details.