Browse files

Create gh-pages branch via GitHub

  • Loading branch information...
1 parent 37ddcdd commit 77782e09a79c986476796a9598f05a9c7a6f346c @jdennes jdennes committed May 3, 2014
Showing with 13 additions and 15 deletions.
  1. +12 −14 index.html
  2. +1 −1 params.json
View
26 index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
- <title>createsend-ruby by campaignmonitor</title>
+ <title>createsend by campaignmonitor</title>
<link rel="stylesheet" href="stylesheets/styles.css">
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
@@ -15,7 +15,7 @@
<body>
<div class="wrapper">
<header>
- <h1>createsend-ruby</h1>
+ <h1>createsend</h1>
<p>A Ruby library for the Campaign Monitor API</p>
<p class="view"><a href="https://github.com/campaignmonitor/createsend-ruby">View the Project on GitHub <small>campaignmonitor/createsend-ruby</small></a></p>
@@ -31,23 +31,21 @@
<h1>
<a name="createsend" class="anchor" href="#createsend"><span class="octicon octicon-link"></span></a>createsend</h1>
-<p><a href="http://travis-ci.org/campaignmonitor/createsend-ruby"><img src="https://secure.travis-ci.org/campaignmonitor/createsend-ruby.png" alt="Build Status"></a> <a href="https://coveralls.io/r/campaignmonitor/createsend-ruby"><img src="https://coveralls.io/repos/campaignmonitor/createsend-ruby/badge.png?branch=master" alt="Coverage Status"></a> <a href="https://gemnasium.com/campaignmonitor/createsend-ruby"><img src="https://gemnasium.com/campaignmonitor/createsend-ruby.png" alt="Dependency Status"></a> <a href="http://badge.fury.io/rb/createsend"><img src="https://badge.fury.io/rb/createsend.png" alt="Gem Version"></a></p>
-
-<p>A Ruby library which implements the complete functionality of the <a href="http://www.campaignmonitor.com/api/">Campaign Monitor API</a>.</p>
+<p>A Ruby library which implements the complete functionality of the <a href="http://www.campaignmonitor.com/api/">Campaign Monitor API</a>. Requires Ruby &gt;= 1.9.3.</p>
<h2>
-<a name="installation" class="anchor" href="#installation"><span class="octicon octicon-link"></span></a>Installation</h2>
-
-<p>To install:</p>
-
-<pre><code>gem install createsend
-</code></pre>
+<a name="quick-start" class="anchor" href="#quick-start"><span class="octicon octicon-link"></span></a>Quick start</h2>
-<p>Or, add a dependency to your <code>Gemfile</code> then <code>bundle install</code>.</p>
+<p>Add the gem to your <code>Gemfile</code>:</p>
<div class="highlight highlight-ruby"><pre><span class="n">gem</span> <span class="s1">'createsend'</span>
</pre></div>
+<p>Or, install the gem:</p>
+
+<pre><code>gem install createsend
+</code></pre>
+
<h2>
<a name="authenticating" class="anchor" href="#authenticating"><span class="octicon octicon-link"></span></a>Authenticating</h2>
@@ -222,7 +220,7 @@
<p>The best way of finding out the expected input and output of a particular method in a particular class is to use the unit tests as a reference.</p>
-<p>For example, if you wanted to find out how to call the CreateSend::Subscriber.add method, you would look at the file test/subscriber_test.rb</p>
+<p>For example, if you wanted to find out how to call the <code>CreateSend::Subscriber.add</code> method, you would look at the file <a href="https://github.com/campaignmonitor/createsend-ruby/blob/master/test/subscriber_test.rb">test/subscriber_test.rb</a></p>
<div class="highlight highlight-ruby"><pre><span class="n">should</span> <span class="s2">"add a subscriber with custom fields"</span> <span class="k">do</span>
<span class="n">stub_post</span><span class="p">(</span><span class="vi">@auth</span><span class="p">,</span> <span class="s2">"subscribers/</span><span class="si">#{</span><span class="vi">@list_id</span><span class="si">}</span><span class="s2">.json"</span><span class="p">,</span> <span class="s2">"add_subscriber.json"</span><span class="p">)</span>
@@ -235,7 +233,7 @@
<h2>
<a name="documentation" class="anchor" href="#documentation"><span class="octicon octicon-link"></span></a>Documentation</h2>
-<p>Full documentation is hosted by <a href="http://rubydoc.info/gems/createsend/frames">RubyDoc.info</a>.</p>
+<p>Ruby documentation is available at <a href="http://rubydoc.info/gems/createsend/frames">RubyDoc.info</a>.</p>
<h2>
<a name="contributing" class="anchor" href="#contributing"><span class="octicon octicon-link"></span></a>Contributing</h2>
View
2 params.json
@@ -1 +1 @@
-{"name":"createsend-ruby","tagline":"A Ruby library for the Campaign Monitor API","body":"# createsend\r\n[![Build Status](https://secure.travis-ci.org/campaignmonitor/createsend-ruby.png)][travis] [![Coverage Status](https://coveralls.io/repos/campaignmonitor/createsend-ruby/badge.png?branch=master)][coveralls] [![Dependency Status](https://gemnasium.com/campaignmonitor/createsend-ruby.png)][gemnasium] [![Gem Version](https://badge.fury.io/rb/createsend.png)][gembadge]\r\n\r\nA Ruby library which implements the complete functionality of the [Campaign Monitor API](http://www.campaignmonitor.com/api/).\r\n\r\n[travis]: http://travis-ci.org/campaignmonitor/createsend-ruby\r\n[coveralls]: https://coveralls.io/r/campaignmonitor/createsend-ruby\r\n[gemnasium]: https://gemnasium.com/campaignmonitor/createsend-ruby\r\n[gembadge]: http://badge.fury.io/rb/createsend\r\n\r\n## Installation\r\n\r\nTo install:\r\n\r\n```\r\ngem install createsend\r\n```\r\n\r\nOr, add a dependency to your `Gemfile` then `bundle install`.\r\n\r\n```ruby\r\ngem 'createsend'\r\n```\r\n\r\n## Authenticating\r\n\r\nThe Campaign Monitor API supports authentication using either OAuth or an API key.\r\n\r\n### Using OAuth\r\n\r\nIf you're developing a Rails or Rack based application, we recommend using [omniauth-createsend](https://github.com/jdennes/omniauth-createsend) to authenticate with the Campaign Monitor API. You might find this [example application](https://github.com/jdennes/createsendoauthtest) helpful.\r\n\r\nIf you don't use [omniauth-createsend](https://github.com/jdennes/omniauth-createsend), you'll need to get access tokens for your users by following the instructions included in the Campaign Monitor API [documentation](http://www.campaignmonitor.com/api/getting-started/#authenticating_with_oauth). This gem provides functionality to help you do this, as described below. There's also another [example application](https://gist.github.com/jdennes/4945412) you may wish to reference, which doesn't depend on any OAuth libraries.\r\n\r\n#### Redirecting to the authorization URL\r\n\r\nThe first thing your application should do is redirect your user to the Campaign Monitor authorization URL where they will have the opportunity to approve your application to access their Campaign Monitor account. You can get this authorization URL by using `CreateSend::CreateSend.authorize_url`, like so:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauthorize_url = CreateSend::CreateSend.authorize_url(\r\n 'Client ID for your application',\r\n 'Redirect URI for your application',\r\n 'The permission level your application requires',\r\n 'Optional state data to be included'\r\n)\r\n# Redirect your users to authorize_url.\r\n```\r\n\r\n#### Exchanging an OAuth code for an access token\r\n\r\nIf your user approves your application, they will then be redirected to the `redirect_uri` you specified, which will include a `code` parameter, and optionally a `state` parameter in the query string. Your application should implement a handler which can exchange the code passed to it for an access token, using `CreateSend::CreateSend.exchange_token` like so:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\naccess_token, expires_in, refresh_token = CreateSend::CreateSend.exchange_token(\r\n 'Client ID for your application',\r\n 'Client Secret for your application',\r\n 'Redirect URI for your application',\r\n 'A unique code for your user' # Get the code parameter from the query string\r\n)\r\n# Save access_token, expires_in, and refresh_token.\r\n```\r\n\r\nAt this point you have an access token and refresh token for your user which you should store somewhere convenient so that your application can look up these values when your user wants to make future Campaign Monitor API calls.\r\n\r\n#### Making API calls using an access token\r\n\r\nOnce you have an access token and refresh token for your user, you can use the `createsend` gem to authenticate and make further API calls like so:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\ncs = CreateSend::CreateSend.new auth\r\nclients = cs.clients\r\n```\r\n\r\n#### Refreshing access tokens\r\n\r\nAll OAuth access tokens have an expiry time, and can be renewed with a refresh token. If your access token expires when attempting to make an API call, the `CreateSend::ExpiredOAuthToken` exception will be raised, so your code should handle this. You can handle this using either `CreateSend::CreateSend.refresh_access_token` (when calling class methods) or `CreateSend::CreateSend#refresh_token` (when calling instance methods).\r\n\r\nHere's an example of using `CreateSend::CreateSend#refresh_token` to refresh your current access token when calling `CreateSend::CreateSend#clients`:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\ncs = CreateSend::CreateSend.new auth\r\n\r\nbegin\r\n tries ||= 2\r\n clients = cs.clients\r\n rescue CreateSend::ExpiredOAuthToken => eot\r\n access_token, expires_in, refresh_token = cs.refresh_token\r\n # Here you should save your updated access token, 'expire in' value,\r\n # and refresh token. `cs` will automatically have the new access token\r\n # set, so there is no need to set it again.\r\n retry unless (tries -= 1).zero?\r\n p \"Error: #{eot}\"\r\n rescue Exception => e\r\n p \"Error: #{e}\"\r\nend\r\n```\r\n\r\nIn addition to raising `CreateSend::ExpiredOAuthToken` when an access token has expired, this library also raises `CreateSend::InvalidOAuthToken` if an invalid access token is used, and raises `CreateSend::RevokedOAuthToken` if a user has revoked the access token being used. This makes it easier for you to handle these cases in your code.\r\n\r\n### Using an API key\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\ncs = CreateSend::CreateSend.new :api_key => 'your api key'\r\nclients = cs.clients\r\n```\r\n\r\n## Basic usage\r\nThis example of listing all your clients and their campaigns demonstrates basic usage of the library and the data returned from the API:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\ncs = CreateSend::CreateSend.new auth\r\n\r\nclients = cs.clients\r\nclients.each do |cl|\r\n p \"Client: #{cl.Name}\"\r\n client = CreateSend::Client.new auth, cl.ClientID\r\n p \"- Campaigns:\"\r\n client.campaigns.each do |cm|\r\n p \" - #{cm.Subject}\"\r\n end\r\nend\r\n```\r\n\r\nRunning this example will result in something like:\r\n\r\n```\r\nClient: First Client\r\n- Campaigns:\r\n - Newsletter Number One\r\n - Newsletter Number Two\r\nClient: Second Client\r\n- Campaigns:\r\n - News for January 2013\r\n```\r\n\r\n## Handling errors\r\nIf the Campaign Monitor API returns an error, an exception will be raised. For example, if you attempt to create a campaign and enter empty values for subject and other required fields:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\n\r\nbegin\r\n id = CreateSend::Campaign.create auth, \"4a397ccaaa55eb4e6aa1221e1e2d7122\",\r\n \"\", \"\", \"\", \"\", \"\", \"\", \"\", [], []\r\n p \"New campaign ID: #{id}\"\r\n rescue CreateSend::BadRequest => br\r\n p \"Bad request error: #{br}\"\r\n p \"Error Code: #{br.data.Code}\"\r\n p \"Error Message: #{br.data.Message}\"\r\n rescue Exception => e\r\n p \"Error: #{e}\"\r\nend\r\n```\r\n\r\nRunning this example will result in:\r\n\r\n```\r\nBad request error: The CreateSend API responded with the following error - 304: Campaign Subject Required\r\nError Code: 304\r\nError Message: Campaign Subject Required\r\n```\r\n\r\n## Expected input and output\r\nThe best way of finding out the expected input and output of a particular method in a particular class is to use the unit tests as a reference.\r\n\r\nFor example, if you wanted to find out how to call the CreateSend::Subscriber.add method, you would look at the file test/subscriber_test.rb\r\n\r\n```ruby\r\nshould \"add a subscriber with custom fields\" do\r\n stub_post(@auth, \"subscribers/#{@list_id}.json\", \"add_subscriber.json\")\r\n custom_fields = [ { :Key => 'website', :Value => 'http://example.com/' } ]\r\n email_address = CreateSend::Subscriber.add @auth, @list_id, \"subscriber@example.com\", \"Subscriber\", custom_fields, true\r\n email_address.should == \"subscriber@example.com\"\r\nend\r\n```\r\n\r\n## Documentation\r\n\r\nFull documentation is hosted by [RubyDoc.info](http://rubydoc.info/gems/createsend/frames).\r\n\r\n## Contributing\r\n\r\nPlease check the [guidelines for contributing](https://github.com/campaignmonitor/createsend-ruby/blob/master/CONTRIBUTING.md) to this repository.\r\n\r\n## Releasing\r\n\r\nPlease check the [instructions for releasing](https://github.com/campaignmonitor/createsend-ruby/blob/master/RELEASE.md) the `createsend` gem.\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}
+{"name":"createsend","tagline":"A Ruby library for the Campaign Monitor API","body":"# createsend\r\n\r\nA Ruby library which implements the complete functionality of the [Campaign Monitor API](http://www.campaignmonitor.com/api/). Requires Ruby >= 1.9.3.\r\n\r\n## Quick start\r\n\r\nAdd the gem to your `Gemfile`:\r\n\r\n```ruby\r\ngem 'createsend'\r\n```\r\n\r\nOr, install the gem:\r\n\r\n```\r\ngem install createsend\r\n```\r\n\r\n## Authenticating\r\n\r\nThe Campaign Monitor API supports authentication using either OAuth or an API key.\r\n\r\n### Using OAuth\r\n\r\nIf you're developing a Rails or Rack based application, we recommend using [omniauth-createsend](https://github.com/jdennes/omniauth-createsend) to authenticate with the Campaign Monitor API. You might find this [example application](https://github.com/jdennes/createsendoauthtest) helpful.\r\n\r\nIf you don't use [omniauth-createsend](https://github.com/jdennes/omniauth-createsend), you'll need to get access tokens for your users by following the instructions included in the Campaign Monitor API [documentation](http://www.campaignmonitor.com/api/getting-started/#authenticating_with_oauth). This gem provides functionality to help you do this, as described below. There's also another [example application](https://gist.github.com/jdennes/4945412) you may wish to reference, which doesn't depend on any OAuth libraries.\r\n\r\n#### Redirecting to the authorization URL\r\n\r\nThe first thing your application should do is redirect your user to the Campaign Monitor authorization URL where they will have the opportunity to approve your application to access their Campaign Monitor account. You can get this authorization URL by using `CreateSend::CreateSend.authorize_url`, like so:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauthorize_url = CreateSend::CreateSend.authorize_url(\r\n 'Client ID for your application',\r\n 'Redirect URI for your application',\r\n 'The permission level your application requires',\r\n 'Optional state data to be included'\r\n)\r\n# Redirect your users to authorize_url.\r\n```\r\n\r\n#### Exchanging an OAuth code for an access token\r\n\r\nIf your user approves your application, they will then be redirected to the `redirect_uri` you specified, which will include a `code` parameter, and optionally a `state` parameter in the query string. Your application should implement a handler which can exchange the code passed to it for an access token, using `CreateSend::CreateSend.exchange_token` like so:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\naccess_token, expires_in, refresh_token = CreateSend::CreateSend.exchange_token(\r\n 'Client ID for your application',\r\n 'Client Secret for your application',\r\n 'Redirect URI for your application',\r\n 'A unique code for your user' # Get the code parameter from the query string\r\n)\r\n# Save access_token, expires_in, and refresh_token.\r\n```\r\n\r\nAt this point you have an access token and refresh token for your user which you should store somewhere convenient so that your application can look up these values when your user wants to make future Campaign Monitor API calls.\r\n\r\n#### Making API calls using an access token\r\n\r\nOnce you have an access token and refresh token for your user, you can use the `createsend` gem to authenticate and make further API calls like so:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\ncs = CreateSend::CreateSend.new auth\r\nclients = cs.clients\r\n```\r\n\r\n#### Refreshing access tokens\r\n\r\nAll OAuth access tokens have an expiry time, and can be renewed with a refresh token. If your access token expires when attempting to make an API call, the `CreateSend::ExpiredOAuthToken` exception will be raised, so your code should handle this. You can handle this using either `CreateSend::CreateSend.refresh_access_token` (when calling class methods) or `CreateSend::CreateSend#refresh_token` (when calling instance methods).\r\n\r\nHere's an example of using `CreateSend::CreateSend#refresh_token` to refresh your current access token when calling `CreateSend::CreateSend#clients`:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\ncs = CreateSend::CreateSend.new auth\r\n\r\nbegin\r\n tries ||= 2\r\n clients = cs.clients\r\n rescue CreateSend::ExpiredOAuthToken => eot\r\n access_token, expires_in, refresh_token = cs.refresh_token\r\n # Here you should save your updated access token, 'expire in' value,\r\n # and refresh token. `cs` will automatically have the new access token\r\n # set, so there is no need to set it again.\r\n retry unless (tries -= 1).zero?\r\n p \"Error: #{eot}\"\r\n rescue Exception => e\r\n p \"Error: #{e}\"\r\nend\r\n```\r\n\r\nIn addition to raising `CreateSend::ExpiredOAuthToken` when an access token has expired, this library also raises `CreateSend::InvalidOAuthToken` if an invalid access token is used, and raises `CreateSend::RevokedOAuthToken` if a user has revoked the access token being used. This makes it easier for you to handle these cases in your code.\r\n\r\n### Using an API key\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\ncs = CreateSend::CreateSend.new :api_key => 'your api key'\r\nclients = cs.clients\r\n```\r\n\r\n## Basic usage\r\nThis example of listing all your clients and their campaigns demonstrates basic usage of the library and the data returned from the API:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\ncs = CreateSend::CreateSend.new auth\r\n\r\nclients = cs.clients\r\nclients.each do |cl|\r\n p \"Client: #{cl.Name}\"\r\n client = CreateSend::Client.new auth, cl.ClientID\r\n p \"- Campaigns:\"\r\n client.campaigns.each do |cm|\r\n p \" - #{cm.Subject}\"\r\n end\r\nend\r\n```\r\n\r\nRunning this example will result in something like:\r\n\r\n```\r\nClient: First Client\r\n- Campaigns:\r\n - Newsletter Number One\r\n - Newsletter Number Two\r\nClient: Second Client\r\n- Campaigns:\r\n - News for January 2013\r\n```\r\n\r\n## Handling errors\r\nIf the Campaign Monitor API returns an error, an exception will be raised. For example, if you attempt to create a campaign and enter empty values for subject and other required fields:\r\n\r\n```ruby\r\nrequire 'createsend'\r\n\r\nauth = {\r\n :access_token => 'your access token',\r\n :refresh_token => 'your refresh token'\r\n}\r\n\r\nbegin\r\n id = CreateSend::Campaign.create auth, \"4a397ccaaa55eb4e6aa1221e1e2d7122\",\r\n \"\", \"\", \"\", \"\", \"\", \"\", \"\", [], []\r\n p \"New campaign ID: #{id}\"\r\n rescue CreateSend::BadRequest => br\r\n p \"Bad request error: #{br}\"\r\n p \"Error Code: #{br.data.Code}\"\r\n p \"Error Message: #{br.data.Message}\"\r\n rescue Exception => e\r\n p \"Error: #{e}\"\r\nend\r\n```\r\n\r\nRunning this example will result in:\r\n\r\n```\r\nBad request error: The CreateSend API responded with the following error - 304: Campaign Subject Required\r\nError Code: 304\r\nError Message: Campaign Subject Required\r\n```\r\n\r\n## Expected input and output\r\n\r\nThe best way of finding out the expected input and output of a particular method in a particular class is to use the unit tests as a reference.\r\n\r\nFor example, if you wanted to find out how to call the `CreateSend::Subscriber.add` method, you would look at the file [test/subscriber_test.rb](https://github.com/campaignmonitor/createsend-ruby/blob/master/test/subscriber_test.rb)\r\n\r\n```ruby\r\nshould \"add a subscriber with custom fields\" do\r\n stub_post(@auth, \"subscribers/#{@list_id}.json\", \"add_subscriber.json\")\r\n custom_fields = [ { :Key => 'website', :Value => 'http://example.com/' } ]\r\n email_address = CreateSend::Subscriber.add @auth, @list_id, \"subscriber@example.com\", \"Subscriber\", custom_fields, true\r\n email_address.should == \"subscriber@example.com\"\r\nend\r\n```\r\n\r\n## Documentation\r\n\r\nRuby documentation is available at [RubyDoc.info](http://rubydoc.info/gems/createsend/frames).\r\n\r\n## Contributing\r\n\r\nPlease check the [guidelines for contributing](https://github.com/campaignmonitor/createsend-ruby/blob/master/CONTRIBUTING.md) to this repository.\r\n\r\n## Releasing\r\n\r\nPlease check the [instructions for releasing](https://github.com/campaignmonitor/createsend-ruby/blob/master/RELEASE.md) the `createsend` gem.\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}

0 comments on commit 77782e0

Please sign in to comment.