AWeber API Gem

Official AWeber API gem.

Installation

gem install aweber

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 directory for just example code.

Requires a normal AWeber account (not a Labs account)

1. Register an AWeber Labs Account

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

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.

3. Write Some Code

The OAuth Handler

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

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:

oauth.request_token.authorize_url

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

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

Verification Code

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

oauth.authorize_with_verifier('verification_code')

Grab an AWeber::Base

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.

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:

...
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:

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)

I want to distribute my app as a public app

If you intend to distribute your app to many AWeber customers via source code (See here for more info), you will want to use the app id to authenticate your app as follows.

Build the authorize_app url:

require 'aweber'
app_id = '1XXXXXXX8' #paste you app id from labs.aweber.com here
auth_url = 'https://auth.aweber.com/1.0/oauth/authorize_app/' + app_id
puts "please go to " + auth_url

Verification Code

After you do the above step, it will output a “Verification Code”. Copy this into authorize_with_authorization_code

aweber = AWeber::Base.authorize_with_authorization_code('My|Authcode|Pasted|Here')

You can now use the aweber object to access data from the account that authorized your app!

Usage

Resource Traversal

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

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

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.

find_by_*

Collections also support ActiveRecord style find_by_* methods:

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

Resources

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

aweber.account.lists[1234]

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.

Updating Resources

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

Updateable Subscribers

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

Moving Subscriber From List to List

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

Example

subscriber = account.lists[654321].subscribers[123456]
subscriber.name = "New Name"
subscriber.save

Adding Subscribers

new_subscriber = {}
new_subscriber["email"] = "[email protected]"
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)

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.

Copyright

Copyright © 2010-2013 AWeber Communications, Inc. See LICENSE for more detail.