<commit_before>h1. AWeber API Gem "!https://secure.travis-ci.org/aweber/AWeber-API-Ruby-Library.png!":http://travis-ci.org/aweber/AWeber-API-Ruby-Library

Official AWeber API gem.

h2. Installation

@gem install aweber@

h2. Getting Started

This guide assumes you have nothing previously setup to work with the AWeber API. It will walk through registering an account, creating an app and everything up to the point where you'll actually start working with data.

If you don't want to bother with all the account setup stuff, you can look in the "examples":https://github.com/aweber/AWeber-API-Ruby-Library/tree/master/examples directory for just example code.

*Requires a normal AWeber account (not a Labs account)*

h3. 1. Register an AWeber Labs Account

Head to "http://labs.aweber.com":http://labs.aweber.com and sign up for a free AWeber Labs account. This is how you register apps and get OAuth keys.

h3. 2. Create an App

Once logged in, _Create a New App_. Once created, it will show you the Consumer Key and Secret for that app.

h3. 3. Write Some Code

h4. The OAuth Handler

bc. oauth = AWeber::OAuth.new('consumer_key', 'consumer_secret')

h4. Authorize an Account

Open, what the following outputs, in a browser and use your AWeber account credentials. This will give your app permission to work with your account's data:

bc. oauth.request_token.authorize_url

A callback url may also be passed by setting the :oauth_callback parameter:

bc. oauth.request_token(:oauth_callback => 'http://www.example.com').authorize_url

h4. Verification Code

After you do the above step, it will output a "Verification Code". Copy this and verify your @oauth@ object:

bc. oauth.authorize_with_verifier('verification_code')

h4. Grab an AWeber::Base

bc. aweber = AWeber::Base.new(oauth)

This object is how you access data from your account. @aweber.account@ is your account object which is the stem for all other resources.

h4. What if I don't want to verify every time?

After verifying once, the @oauth@ object contains an @oauth.access_token.token@ and and @oauth.access_token.secret@ which may be used to authorize your application without having to verify via url:

bc. ...
oauth.authorize_with_verifier('verification_code')
puts 'Access token: ' + oauth.access_token.token
puts 'Access token secret: ' + oauth.access_token.secret

The token and secret can then be saved, and authorization can be performed as follows:

bc. require 'aweber'
oauth = AWeber::OAuth.new('consumer_key', 'consumer_secret')
#Rather than authorizing with the verification code, we use the token and secret
oauth.authorize_with_access(YOUR_ACCESS_TOKEN, YOUR_ACCESS_TOKEN_SECRET)
aweber = AWeber::Base.new(oauth)


h2. Usage

h3. Resource Traversal

Getting resource data is much like traversing associations in ActiveRecord. Everything starts with the @account@ object and goes from there:

bc.. aweber.account.lists           #=> #<AWeber::Collection>
aweber.account.lists[123]      #=> #<AWeber::Resource::List>     #123 represents the list id
aweber.account.lists[123].name #=> "WhateverList"

h3. Collections

@aweber.account.lists@ in the example above would be a Collection. Collections act like a normal Hash. Resources of a collection are accessed normally, using @[]@ with the key being the ID of the resource.

h4. find_by_*

Collections also support ActiveRecord style @find_by_*@ methods:

bc. aweber.account.lists.find_by_name("testlist")

h3. Resources

Resources are elements of a Collection. A single list resource would be retrieved with:

bc. aweber.account.lists[1234]

h3. Why can't I access the subscriber data?

If you are unable to access the data associated with your subscribers, it is likely that you have not enabled subscriber access permissions for your application. To do so, follow the directions at: https://labs.aweber.com/docs/permissions. These changes won't take effect until you renew your access tokens.

h2. Updating Resources

Currently, subscribers are the only resource you can update via the API. Everything else is read only for the time being.

h3. Updateable Subscribers

* name
* misc_notes
* email
* status
* last_followup_message_number_sent
* custom_fields (Hash of key/value pairs)
* ad_tracking

h3. Moving Subscriber From List to List

bc. new_list = aweber.account.lists[1234]
subscriber.list = new_list

h3. Example

bc. subscriber = account.lists[654321].subscribers[123456]
subscriber.name = "<NAME>"
subscriber.save

h2. Adding Subscribers

bc. new_subscriber = {}
new_subscriber["email"] = "<EMAIL>"
new_subscriber["name"] = "<NAME>"
aweber.account.lists.find_by_name("mylistname").subscribers.create(new_subscriber)
#Or alternatively: aweber.account.lists[list_id].subscribers.create(new_subscriber)

h2. Note on Patches/Pull Requests
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

h2. Copyright

Copyright (c) 2010-2012 AWeber Communications, Inc. See LICENSE for more detail.
<commit_msg>Travis CI image now uses last master build.<commit_after>h1. AWeber API Gem "!https://secure.travis-ci.org/aweber/AWeber-API-Ruby-Library.png?branch=master!":http://travis-ci.org/aweber/AWeber-API-Ruby-Library

Official AWeber API gem.

h2. Installation

@gem install aweber@

h2. Getting Started

This guide assumes you have nothing previously setup to work with the AWeber API. It will walk through registering an account, creating an app and everything up to the point where you'll actually start working with data.

If you don't want to bother with all the account setup stuff, you can look in the "examples":https://github.com/aweber/AWeber-API-Ruby-Library/tree/master/examples directory for just example code.

*Requires a normal AWeber account (not a Labs account)*

h3. 1. Register an AWeber Labs Account

Head to "http://labs.aweber.com":http://labs.aweber.com and sign up for a free AWeber Labs account. This is how you register apps and get OAuth keys.

h3. 2. Create an App

Once logged in, _Create a New App_. Once created, it will show you the Consumer Key and Secret for that app.

h3. 3. Write Some Code

h4. The OAuth Handler

bc. oauth = AWeber::OAuth.new('consumer_key', 'consumer_secret')

h4. Authorize an Account

Open, what the following outputs, in a browser and use your AWeber account credentials. This will give your app permission to work with your account's data:

bc. oauth.request_token.authorize_url

A callback url may also be passed by setting the :oauth_callback parameter:

bc. oauth.request_token(:oauth_callback => 'http://www.example.com').authorize_url

h4. Verification Code

After you do the above step, it will output a "Verification Code". Copy this and verify your @oauth@ object:

bc. oauth.authorize_with_verifier('verification_code')

h4. Grab an AWeber::Base

bc. aweber = AWeber::Base.new(oauth)

This object is how you access data from your account. @aweber.account@ is your account object which is the stem for all other resources.

h4. What if I don't want to verify every time?

After verifying once, the @oauth@ object contains an @oauth.access_token.token@ and and @oauth.access_token.secret@ which may be used to authorize your application without having to verify via url:

bc. ...
oauth.authorize_with_verifier('verification_code')
puts 'Access token: ' + oauth.access_token.token
puts 'Access token secret: ' + oauth.access_token.secret

The token and secret can then be saved, and authorization can be performed as follows:

bc. require 'aweber'
oauth = AWeber::OAuth.new('consumer_key', 'consumer_secret')
#Rather than authorizing with the verification code, we use the token and secret
oauth.authorize_with_access(YOUR_ACCESS_TOKEN, YOUR_ACCESS_TOKEN_SECRET)
aweber = AWeber::Base.new(oauth)


h2. Usage

h3. Resource Traversal

Getting resource data is much like traversing associations in ActiveRecord. Everything starts with the @account@ object and goes from there:

bc.. aweber.account.lists           #=> #<AWeber::Collection>
aweber.account.lists[123]      #=> #<AWeber::Resource::List>     #123 represents the list id
aweber.account.lists[123].name #=> "WhateverList"

h3. Collections

@aweber.account.lists@ in the example above would be a Collection. Collections act like a normal Hash. Resources of a collection are accessed normally, using @[]@ with the key being the ID of the resource.

h4. find_by_*

Collections also support ActiveRecord style @find_by_*@ methods:

bc. aweber.account.lists.find_by_name("testlist")

h3. Resources

Resources are elements of a Collection. A single list resource would be retrieved with:

bc. aweber.account.lists[1234]

h3. Why can't I access the subscriber data?

If you are unable to access the data associated with your subscribers, it is likely that you have not enabled subscriber access permissions for your application. To do so, follow the directions at: https://labs.aweber.com/docs/permissions. These changes won't take effect until you renew your access tokens.

h2. Updating Resources

Currently, subscribers are the only resource you can update via the API. Everything else is read only for the time being.

h3. Updateable Subscribers

* name
* misc_notes
* email
* status
* last_followup_message_number_sent
* custom_fields (Hash of key/value pairs)
* ad_tracking

h3. Moving Subscriber From List to List

bc. new_list = aweber.account.lists[1234]
subscriber.list = new_list

h3. Example

bc. subscriber = account.lists[654321].subscribers[123456]
subscriber.name = "<NAME>"
subscriber.save

h2. Adding Subscribers

bc. new_subscriber = {}
new_subscriber["email"] = "<EMAIL>"
new_subscriber["name"] = "My New Subscriber"
aweber.account.lists.find_by_name("mylistname").subscribers.create(new_subscriber)
#Or alternatively: aweber.account.lists[list_id].subscribers.create(new_subscriber)

h2. Note on Patches/Pull Requests
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

h2. Copyright

Copyright (c) 2010-2012 AWeber Communications, Inc. See LICENSE for more detail.

{'fraction_non_alphanumeric': 0.0771030139451192, 'fraction_numerical': 0.011515969410706253, 'mean_word_length': 4.6113074204946995, 'pattern_counts': {'":': 6, '<': 12, '<?xml version=': 0, '>': 20, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3339717', 'n_tokens_mistral': 3441, 'n_tokens_neox': 3256, 'n_words': 1395}