README.md in inbox-0.2.0 vs README.md in inbox-0.3.0

- old
+ new

@@ -1,126 +1,214 @@ -Inbox -===== +# Inbox Ruby bindings +## Installation -Description ------------ +Add this line to your application's Gemfile: -* Preview send emails in development and test mode. + gem 'inbox' -* Test them using your standard Capybara matchers or -any other testing framework that you prefer. +And then execute: + bundle -Installation ------------- +You don't need to use this repo unless you're planning to modify the gem. If you just want to use the Inbox SDK with Ruby bindings, you should run: -In your `Gemfile` add: + gem install inbox -```ruby -gem 'inbox' + +##Requirements + +- Ruby 1.8.7 or above. (Ruby 1.8.6 may work if you load ActiveSupport.) + +- rest-client, json + + +## Example + +A small example Rails app is included in the `example` directory. You can run the sample app to see how an authentication flow might be implemented. + +`cd example` + +`RESTCLIENT_LOG=stdout rails s` + +*Note that you will need to replace the Inbox App ID and Secret in `config/environments/development.rb` to use the sample app.* + +## Usage + +### App ID and Secret + +Before you can interact with the Inbox API, you need to register for the Inbox developer program at [http://www.inboxapp.com/](http://www.inboxapp.com/). After you've created a developer account, you can create a new application to generate an App ID / Secret pair. + +### Authentication + +The Inbox API uses server-side (three-legged) OAuth, and the Ruby gem provides a convenience methods that simplify the OAuth process. For more information about authenticating with Inbox, visit the [Developer Documentation](https://www.inboxapp.com/docs/gettingstarted-hosted#authenticating). + +**Step 1: Redirect the user to Inbox:** + ``` +:::ruby +require 'inbox' -And run: +def login + inbox = Inbox::API.new(config.inbox_app_id, config.inbox_app_secret, nil) + # The email address of the user you want to authenticate + user_email = 'ben@inboxapp.com' + # This URL must be registered with your application in the developer portal + callback_url = url_for(:action => 'login_callback') + + redirect_to inbox.url_for_authentication(callback_url, user_email) +end ``` -bundle install + +**Step 2: Handle the Authentication Response:** + ``` +:::ruby +def login_callback + inbox = Inbox::API.new(config.inbox_app_id, config.inbox_app_secret, nil) + inbox_token = inbox.auth_token_for_code(params[:code]) + # Save the inbox_token to the current session, save it to the user model, etc. +end +``` -Setup ------ +### Fetching Namespaces -Mount engine in `config/routes.rb` +``` +:::ruby +inbox = Inbox::API.new(config.inbox_app_id, config.inbox_app_secret, inbox_token) -```ruby -Rails.application.routes.draw do - mount Inbox::Engine => "/inbox" -end +# Get the first namespace +namespace = inbox.namespaces.first + +# Print out the email address and provider (Gmail, Exchange) +puts namespace.email_address +puts namespace.provider ``` -Feel free to mount it under different route -if this one is already taken in your application -```ruby - mount Inbox::Engine => "/mailer" +### Fetching Threads + ``` +:::ruby +# Fetch the first thread +thread = namespace.threads.first +# Fetch a specific thread +thread = namespace.threads.find('ac123acd123ef123') -Usage ------ +# List all threads tagged `inbox` +# (paginating 50 at a time until no more are returned.) +namespace.threads.where(:tag => 'inbox').each do |thread| + puts thread.subject +end -### Manual +# List the 5 most recent unread threads +namespace.threads.where(:tag => 'unread').range(0,4).each do |thread| + puts thread.subject +end -Navigate to `/inbox/<email>/emails` ex.: `/inbox/robert.pankowecki@gmail.com/emails` -to see a list of emails that would have been delivered to the user. +# List all threads with 'ben@inboxapp.com' +namespace.threads.where(:any_email => 'ben@inboxapp.com').each do |thread| + puts thread.subject +end -Click subject of the email to see its content +# Collect all threads with 'ben@inboxapp.com' into an array. +# Note: for large numbers of threads, this is not advised. +threads = namespace.threads.where(:any_email => 'ben@inboxapp.com').all +``` -### Testing framework -In [capybara](https://github.com/jnicklas/capybara/) or [bbq](https://github.com/drugpl/bbq) +### Working with Threads -```ruby -visit("/inbox/robert.pankowecki@gmail.com/emails") -click_link("Subject of the email") -has_content?("This should be in email") -click_link("Some link in the email ex. account activation link") ``` +:::ruby +# List thread participants +thread.participants.each do |participant| + puts participant['email'] +end -The nice thing is that this is just HTML page displaying email content so you can use -your favorite testing framework (`BBQ`, `Capybara`, `Test::Unit`, `Spinach`, `Cucumber`, `RSpec`, whatever) -for checking the content of page. And you can reuse your matchers. +# Mark as read +thread.mark_as_read! +# Archive +thread.archive! -### Sending +# Add or remove arbitrary tags +tagsToAdd = ['inbox', 'cfa1233ef123acd12'] +tagsToRemove = [] +thread.update_tags!(tagsToAd, tagsToRemove) -Navigate to `/inbox/<email>/emails/new` ex.: `/inbox/robert.pankowecki@gmail.com/emails/new` -to see an ugly form for sending emails that you can use to play around and see if everything -works fine. +# List messages +thread.messages.each do |message| + puts message.subject +end +``` -### Clear send emails -```ruby - ActionMailer::Base.deliveries.clear # in :test mode - Inbox::FileDelivery.new(ActionMailer::Base.inbox_settings).clear # in :inbox mode +### Working with Files + ``` +:::ruby +# List files +namespace.files.each do |file| + puts file.filename +end -Async (distributed / queue) ---------------------------- +# Create a new file +file = namespace.files.build(:file => File.new("./public/favicon.ico", 'rb')) +file.save! +``` -In case you want to have acceptance tests of emails that are -sent using external process (`resque`, `sidekiq`, ...) just set +### Working with Messages, Contacts, etc. -```ruby -config.action_mailer.delivery_method = :inbox +Each of the primary collections (contacts, messages, etc.) behave the same way as `threads`. For example, finding messages with a filter is similar to finding threads: + ``` +:::ruby +messages = namespace.messages.where(:to => 'ben@inboxapp.com`).all +``` -in `config/environments/test.rb` and create `tmp/mails` directory. +The `where` method accepts a hash of filters, as documented in the [Inbox Filters Documentation](https://www.inboxapp.com/docs/api#filters). +### Creating and Sending Drafts -If you send emails from your Rails models, controllers, services or use-cases you can stick with: +``` +:::ruby +# Create a new draft +draft = namespace.drafts.build( + :to => [{:name => 'Ben Gotow', :email => 'ben@inboxapp.com'}], + :subject => "Sent by Ruby", + :body => "Hi there!<strong>This is HTML</strong>" +) -```ruby -config.action_mailer.delivery_method = :test +# Modify attributes as necessary +draft.cc = [{:name => 'Michael', :email => 'mg@inboxapp.com'}] + +# Add the file we uploaded as an attachment +draft.attach(file) + +# Save the draft +draft.save! + +# Send the draft. This method returns immediately and queues the message +# with Inbox for delivery through the user's SMTP gateway. +draft.send! ``` -Look & Feel ------------ +## Contributing -![Inbox gem look and feel](http://img832.imageshack.us/img832/1333/screenshotinboxgooglech.png) +We'd love your help making the Inbox ruby gem better. Join the Google Group for project updates and feature discussion. We also hang out in `##inbox` on [irc.freenode.net](http://irc.freenode.net), or you can email [help@inboxapp.com](mailto:help@inboxapp.com). +Please sign the Contributor License Agreement before submitting pull requests. (It's similar to other projects, like NodeJS or Meteor.) -Inspirations ------------- +The Inbox ruby gem uses [Jeweler](https://github.com/technicalpickles/jeweler) for release management. When you're ready to release a new version, do something like this: -* [https://github.com/37signals/mail_view](https://github.com/37signals/mail_view) -* [https://github.com/ryanb/letter_opener](https://github.com/ryanb/letter_opener) -* [https://github.com/suhrawardi/capybara_email/](https://github.com/suhrawardi/capybara_email/) -* [https://github.com/pawelpacana/mail_inbox/](https://github.com/pawelpacana/mail_inbox/) -* [http://api.rubyonrails.org/](http://api.rubyonrails.org/) + rake version:bump:minor + rake release -License -------- +Tests can be run with: -MIT-LICENSE + rspec spec +