Create a Private App

Setup Your Dev Environment

This step is where you will set up the foundation for your new app.

Download the Wrapper

To create an environment to start coding, the simplest way would be to download the zip file from GitHub, unzip the file and create a php file within the directory.

Download the API PHP Library
  • Fully handles OAuth integration
  • Requires PHP 5.x with Curl support
  • Includes a full PHP Library tutorial

Looking for a quick example?

We have a Quick Start script that has everything you need in one place. We can also walk you thru everything step by step by continuing below.


Lets get started!

So after you have downloaded and unzipped the PHP Library, let's create an empty php file to start our application.

Of course, you could clone the project using Git and then change the php.ini file include_path to that directory, but that method requires a bit more effort.

Create a test file, and let's start coding

username@localhost:~/my-test-app$ touch test_app.php
username@localhost:~/my-test-app$ vi test_app.php

First, create a virtualenv

The easiest way to go about this is to create a virtualenv for your test app and use pip to install the aweber_api wrapper. Here are the commands to follow:

username@localhost:~$ virtualenv my-test-app
New python executable in my-test-app/bin/python
Please make sure you remove any previous custom paths from your 
/Users/username/.pydistutils.cfg file.
Installing setuptools............done.
Installing pip...............done.

Next, start development mode

username@localhost:~$ cd my-test-app/
username@localhost:~/my-test-app$ source bin/activate

Install the aweber_api using pip

(my-test-app)username@localhost:~/my-test-app$ pip install aweber_api
Downloading/unpacking aweber-api
  Downloading aweber_api-1.1.2.tar.gz
  Running setup.py egg_info for package aweber-api
    no previously-included directories found matching 'doc/.build'

    Installed /Users/username/my-test-app/build/aweber-api/nose-1.1.3.dev-py2.6.egg
Downloading/unpacking httplib2>=0.7.0 (from aweber-api)
  Downloading httplib2-0.7.5.zip (113Kb): 113Kb downloaded
  Running setup.py egg_info for package httplib2
Downloading/unpacking oauth2>=1.2 (from aweber-api)
  Downloading oauth2-1.5.211.tar.gz
  Running setup.py egg_info for package oauth2
Installing collected packages: aweber-api, httplib2, oauth2
  Running setup.py install for aweber-api
  Running setup.py install for httplib2
  Running setup.py install for oauth2
Successfully installed aweber-api httplib2 oauth2
Cleaning up...

Now you can see the dependencies that were installed in your virtualenv

(my-test-app)username@localhost:~/my-test-app$ pip freeze
aweber-api==1.1.2
httplib2==0.7.5
oauth2==1.5.211
wsgiref==0.1.2

Create a test file, and let's start coding

(my-test-app)username@localhost:~/my-test-app$ touch test_app.py
(my-test-app)username@localhost:~/my-test-app$ vi test_app.py
You can use whichever editor you like, vim (MacVim) is just my own preference.

Connecting To AWeber

So as a developer, your goal is to ultimately gain access to an AWeber Account and pull in data, right? Well, we're going to show you how to do that.

There is a security protocol you have to use to connect to the AWeber API and request Account data. This process is one that is pretty standard and used in a bunch of API's, it's called OAuth.

OAuth in a nutshell:

Step 1:Create an AWeberAPI instance using your consumer key and consumer secret.
Step 2:Ping AWeber Auth to get your request token key and request token secret.
Step 3:Visit the Authorization URL using your request token key.
Step 4:Ping AWeber Auth again to get access keys.
Step 5:Access the API using your access keys.

Let's break it down...

Hang on! We're explaining stuff here...

We have a code sample at the bottom of this page that will put all of these steps together to get access to the API. If you're already familiar with OAuth you can use the code sample to get access to the API.

Step 1: Create an AWeberAPI instance using your consumer key and consumer secret.

The first step is to create an AWeberAPI instance with your consumer key and consumer secret. This object uniquely identifies your application. It will now be used to communicate with any AWeber endpoint.

Where are the consumer key and consumer secret?

When you create an app we give you these keys on the My Apps page within the app entry that you want to start working with.

Do not distribute these keys to others!


Step 2: Ping AWeber Auth to get your request token key and request token secret.

Next we can get the request token key and request token secret (called request keys) from the API by using our application object. When asking for the request keys, you can specify the callback URL that the response will go back to. The callback URL is the URL where the AWeber Customer will get redirected to when they successfully authorize access to your app. This callback URL would be the URL of your app that will handle step 4 if your app is a webpage.

In this case, our app is not a webpage, so we enter 'oob' for the callback URL. When the customers authorize access to your app, they will be given a verification code that must be entered into your app before access to the API will be granted.

You will receive an 'AWeberOAuthDataMissing' exception if you do not enter your consumer key or secret correctly.


Step 3: Visit the Authorization URL using your request token key.

The authorization URL is always https://auth.aweber.com/1.0/oauth/authorize?oauth_token=XXX where XXX is the request token key given to your app in step 2 above.

If your app is a webpage, then redirect your user to this URL. After they have successfully authorized your app they will then be redirected back to your callback URL with both the request token key and verifier code in the querystring. Your app can intercept this data and go right to step 4 to continue.

In our case we need to tell the app user to visit the authorization URL and prompt them for the verifier code that AWeber Auth will give to them.

Here is what the authorization page and the verifier code prompt look like:



Step 4: Ping AWeber Auth again to get access keys

The last step to get access to the API is to get your access token key and access token secret. These credentials (called access keys) give your app access to the API. Once you have the access keys, you wont need the request keys any more. In OAuth you exchange your request keys along with your verifier code for an access key. After you get your access keys, your request keys are no longer needed.

A word about access keys ...

Keep these keys secure! These keys along with your consumer key and consumer secret give you access to the AWeber customer who authorized your app. These keys will remain valid until the customer revokes them or you change your consumer key and secret.


Step 5: Access the API using your access keys

Awesome, you can now access the API! Below is a code sample that puts all of these steps together

Let's use a command line reader so that we can enter the code from the authentication page without interruption. To make sure that the request is being sent out correctly, we can use the debug mode to view the request and make sure that the verifier doesn't include any extra carriage returns or characters which might cause errors.


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?php
require('aweber_api/aweber_api.php');

# replace XXX with your real keys and secrets
$consumerKey = 'XXX';
$consumerSecret = 'XXX';

# create new instance of AWeberAPI
$application = new AWeberAPI($consumerKey, $consumerSecret);

# get a request token using oob as the callback URL
list($requestToken, $tokenSecret) = $application->getRequestToken('oob');

# prompt user to go to authorization URL
echo "Go to this url in your browser: {$application->getAuthorizeUrl()}\n";

# get the verifier code
echo 'Type code here: ';
$code = trim(fgets(STDIN));

# turn on debug mode for more information
$application->adapter->debug = true;

# exchange request token + verifier code for an access token
$application->user->requestToken = $requestToken;
$application->user->tokenSecret = $tokenSecret;
$application->user->verifier = $code;
list($accessToken, $accessSecret) = $application->getAccessToken();

# show your access token
print "\n$accessToken\n$accessSecret\n";

?>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from aweber_api import AWeberAPI

# replace XXX with your keys
consumer_key = 'XXX'
consumer_secret = 'XXX'

# create new instance of AWeberAPI
application = AWeberAPI(consumer_key, consumer_secret)

# get a request token
request_token, token_secret = application.get_request_token('oob')

# prompt user to go to the auth url
print 'Go to this url in your browser: %s' % application.authorize_url

# prompt for verifier code
code = raw_input('Type code here: ')

# exchange request token + verifier code for access token
application.user.request_token = request_token
application.user.token_secret = token_secret
application.user.verifier = code
access_token, access_secret = application.get_access_token()

# show the results
print access_token, access_secret

This is what you should be seeing in your terminal:

username@localhost:~$ php /Applications/MAMP/htdocs/aweber-AWeber-API-PHP-Library/test_app.php
Go to this url in your browser: https://auth.aweber.com/1.0/oauth/authorize?oauth_token=AXXXXXXXXXXXXXXXXXXXXXXq
Type code here: 64suwo
AXXXXXXXXXXXXXXXXXXXXXXJ
** POST: https://auth.aweber.com/1.0/oauth/access_token
Array
(
    [oauth_consumer_key] => AXXXXXXXXXXXXXXXXXXXXXXJ
    [oauth_nonce] => de381a0b9bef67322cbdb7335cbbe6d3
    [oauth_signature] => RcxsfLaQ2zUNvS/CWq+9wup+ap4=
    [oauth_signature_method] => HMAC-SHA1
    [oauth_timestamp] => 1347285440
    [oauth_token] => AXXXXXXXXXXXXXXXXXXXXXXq
    [oauth_verifier] => 64suwo
    [oauth_version] => 1.0
)
 --> Status: 200
 --> Body: oauth_token_secret=AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXN&oauth_token=AXXXXXXXXXXXXXXXXXXXXXXM
AXXXXXXXXXXXXXXXXXXXXXXM AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXN


(my-test-app)username@localhost:~/my-test-app$ python test_app.py
Go to this url in your browser: https://auth.aweber.com/1.0/oauth/authorize?oauth_token=AXXXXXXXXXXXXXXXXXXXXXXR
Type code here: zz4t2w
AXXXXXXXXXXXXXXXXXXXXXXJ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI

Creating A Working App

Congrats, you made it past the hardest step. Now we can do something fun. We can use the built in methods from the wrapper to query the API for information about the AWeber Account we just connected with.

First, we have to change the permissions for our app so that we can request subscriber data from our application.

Asking permission to access subscriber data:

Go to the My Apps page and click on the edit icon (hint: looks like a screwdriver and wrench) to see the settings of the application we have been working with.

Then choose the 'Permission Settings'

Check the 'Request Subscriber Data' checkbox then click 'Save Permission Settings'.

Now let's change some of our sample code so that it's more modular and reusable.

We'll put the code we just made into its own method for safe-keeping and define a class so that we can call methods on our application instance. Notice that the access keys are global for the class, they give us the unlimited access to that one AWeber Account. We will use them in the next steps to query the account.

Here's how it looks when it's broken into separate methods:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<?php
require('aweber_api/aweber_api.php');

class MyApp{

    function __construct() {
        # replace XXX with your real keys and secrets
        $this->consumerKey = 'XXX';
        $this->consumerSecret = 'XXX';

        $this->application = new AWeberAPI($this->consumerKey, $this->consumerSecret);
    }

    function connectToAWeberAccount() {
        list($requestToken, $tokenSecret) = $this->application->getRequestToken('oob');

        echo "Go to this url in your browser: {$this->application->getAuthorizeUrl()}\n";
        echo 'Type code here: ';
        $code = trim(fgets(STDIN));
        $this->application->adapter->debug = true;


        $this->application->user->requestToken = $requestToken;
        $this->application->user->tokenSecret = $tokenSecret;
        $this->application->user->verifier = $code;

        list($accessToken, $accessSecret) = $this->application->getAccessToken();

        print "\n\n$accessToken \n $accessSecret\n";
    }
}

$app = new MyApp();
$app->connectToAWeberAccount();
?>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from aweber_api import AWeberAPI


class MyApp(object):

    def __init__(self):
        # replace XXX with your keys
        consumer_key = 'XXX'
        consumer_secret = 'XXX'
        self.access_token = 'XXX'
        self.access_secret = 'XXX'

        self.application = AWeberAPI(consumer_key, consumer_secret)

    def connect_to_AWeber_account(self):
        request_token, token_secret = self.application.get_request_token('oob')
        print 'Go to this url in your browser: %s' % self.application.authorize_url
        code = raw_input('Type code here: ')

        self.application.user.request_token = request_token
        self.application.user.token_secret = token_secret
        self.application.user.verifier = code

        access_token, access_secret = self.application.get_access_token()
        print access_token, access_secret

        return access_token, access_secret
The connect_to_AWeber_account method can be used to connect to another AWeber account and returns the access keys for the account you sign-in to on the authorize_url site.

Find a subscriber by email

Here we are going to make a method that will find a subscriber on the account. We'll print out a bunch of stuff so you can see what it looks like. In the module, you can create a class and define the permanent variables, paste in your access keys and call the find_subscriber method we are about to write.

At first, we will print out the account and its ID attribute. Now using the account, we can call the wrapper's findSubscribers() method and pass it any one of attributes that a subscriber has. Lastly, we'll print all the subscribers we found and return a subscriber object.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<?php
require('aweber_api/aweber_api.php');

class MyApp{

    function __construct() {
        # replace XXX with your real keys and secrets
        $this->consumerKey = 'XXX';
        $this->consumerSecret = 'XXX';
        $this->accessToken = 'XXX';
        $this->accessSecret = 'XXX';

        $this->application = new AWeberAPI($this->consumerKey, $this->consumerSecret);
    }

    function findSubscriber($email) {
        $account = $this->application->getAccount($this->accessToken, $this->accessSecret);
        print_r($account);
        print $account->id;

        $foundSubscribers = $account->findSubscribers(array('email' => $email));
        print_r($foundSubscribers);

        return $foundSubscribers[0];
    }
}

$app = new MyApp();

$app->findSubscriber($email='whtever@example.com');
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from aweber_api import AWeberAPI


class MyApp(object):

    def __init__(self):
        # replace XXX with your keys
        consumer_key = 'XXX'
        consumer_secret = 'XXX'
        self.access_token = 'XXX'
        self.access_secret = 'XXX'

        self.application = AWeberAPI(consumer_key, consumer_secret)

    def find_subscriber(self, **kwargs):
        account = self.application.get_account(self.access_token, self.access_secret)
        print account, account.id

        found_subscribers = account.findSubscribers(**kwargs)
        print found_subscribers

        for subscriber in found_subscribers:
            print subscriber
            print subscriber.name, subscriber.email

            return subscriber

app = MyApp()
app.find_subscriber(email='whtever@example.com')
If you run the code, here is the response:
localhost:aweber-AWeber-API-PHP-Library yourname$ php test_app.php 
AWeberEntry Object
(
    [_privateData:protected] => Array
        (
            [0] => resource_type_link
            [1] => http_etag
        )

    [_localDiff:protected] => Array
        (
        )

    [_collections:protected] => Array
        (
        )

    [adapter] => OAuthApplication Object
        (
            [debug] => 
            [userAgent] => AWeber OAuth Consumer Application 1.0 - https://labs.aweber.com/
            [format] => 
            [requiresTokenSecret] => 1
            [signatureMethod] => HMAC-SHA1
            [version] => 1.0
            [user] => OAuthUser Object
                (
                    [authorizedToken] => 
                    [requestToken] => 
                    [verifier] => 
                    [tokenSecret] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXE
                    [accessToken] => AXXXXXXXXXXXXXXXXXXXXXX3
                )

            [consumerKey] => AXXXXXXXXXXXXXXXXXXXXXXJ
            [consumerSecret] => qXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI
            [app] => AWeberServiceProvider Object
                (
                    [baseUri] => https://api.aweber.com/1.0
                    [accessTokenUrl] => https://auth.aweber.com/1.0/oauth/access_token
                    [authorizeUrl] => https://auth.aweber.com/1.0/oauth/authorize
                    [requestTokenUrl] => https://auth.aweber.com/1.0/oauth/request_token
                )

        )

    [data] => Array
        (
            [http_etag] => "d183cd520f6a1b6d5ebfcb95de9e1cf5eff51342-ca5feee2b7fbb6febfca8af5541541ea960aaedb"
            [lists_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists
            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4
            [resource_type_link] => https://api.aweber.com/1.0/#account
            [id] => 6XXXX4
            [integrations_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/integrations
        )

    [_dynamicData] => Array
        (
        )

    [url] => /accounts/6XXXX4
)
6XXXX4AWeberCollection Object
(
    [pageSize:protected] => 100
    [_entries:protected] => Array
        (
        )

    [_privateData:protected] => Array
        (
            [0] => entries
            [1] => start
            [2] => next_collection_link
        )

    [_iterationKey:protected] => 0
    [adapter] => OAuthApplication Object
        (
            [debug] => 
            [userAgent] => AWeber OAuth Consumer Application 1.0 - https://labs.aweber.com/
            [format] => 
            [requiresTokenSecret] => 1
            [signatureMethod] => HMAC-SHA1
            [version] => 1.0
            [user] => OAuthUser Object
                (
                    [authorizedToken] => 
                    [requestToken] => 
                    [verifier] => 
                    [tokenSecret] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXE
                    [accessToken] => AXXXXXXXXXXXXXXXXXXXXXX3
                )

            [consumerKey] => AXXXXXXXXXXXXXXXXXXXXXXJ
            [consumerSecret] => qXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI
            [app] => AWeberServiceProvider Object
                (
                    [baseUri] => https://api.aweber.com/1.0
                    [accessTokenUrl] => https://auth.aweber.com/1.0/oauth/access_token
                    [authorizeUrl] => https://auth.aweber.com/1.0/oauth/authorize
                    [requestTokenUrl] => https://auth.aweber.com/1.0/oauth/request_token
                )

        )

    [data] => Array
        (
            [start] => 0
            [total_size_link] => https://api.aweber.com/1.0/accounts/6XXXX4?email=whtever%40example.com&ws.op=findSubscribers&ws.show=total_size
            [entries] => Array
                (
                    [0] => Array
                        (
                            [subscription_url] => http://forms.aweber.com/form/74/653794374.htm
                            [postal_code] => 19006
                            [id] => 52030790
                            [custom_fields] => Array
                                (
                                    [Custom Field] => 
                                )

                            [last_followup_sent_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/campaigns/f11767068
                            [city] => Huntingdon Valley
                            [http_etag] => "1b8cb26e17318122a73dfd131f9c83e0e5e3c834-7853abd4a76565c6846df3605a1b75c68cfab931"
                            [ad_tracking] => subscribers_2
                            [dma_code] => 504
                            [last_followup_message_number_sent] => 1
                            [last_followup_sent_at] => 
                            [misc_notes] => 
                            [latitude] => 40.1287
                            [is_verified] => 
                            [email] => whtever@example.com
                            [status] => unsubscribed
                            [area_code] => 215
                            [unsubscribed_at] => 2012-04-03 10:02:16-04:00
                            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/subscribers/52030790
                            [unsubscribe_method] => undeliverable
                            [ip_address] => 207.106.239.81
                            [name] => heres a name
                            [subscription_method] => signup form
                            [resource_type_link] => https://api.aweber.com/1.0/#subscriber
                            [region] => PA
                            [longitude] => -75.0597
                            [verified_at] => 
                            [subscribed_at] => 2012-04-03 09:52:32-04:00
                            [country] => United States
                        )

                )

            [total_size] => 1
        )

    [_dynamicData] => Array
        (
        )

    [url] => /accounts/6XXXX4?email=whtever%40example.com&ws.op=findSubscribers
)


(my-test-app)username@localhost:~/my-test-app$ python test_app.py
<aweber_api.entry.AWeberEntry object at 0x11007f490> 6XXXX4
<aweber_api.collection.AWeberCollection object at 0x11007f350>
heresaname whtever@example.com

So what are these objects? Well, the first thing we print out is the account. It is an API entry object. An entry is a single entity, or a single account in this case.

The other part we print is the account ID. Each entry is uniquely identified by an id, which is an attribute of every entry and can be found by printing <insert entry type here>.id.

If I wanted to find the Account ID, I would print: account.id

The next thing we print out are the subscribers we found. We get a collection object. A collection is a group of entries, so that tells us that it was appending all the subscribers it found with your arguments into a big collection and returning it. Next, to view all the entries in our collection or each individual subscriber, so we for loop through it and print out the first subscriber's name and email by using the attributes of a subscriber entry and return it. In this particular case, I have one lonely subscriber with that email address.

Why does the findSubscriber return a collection even if it only finds one entry? The answer is, we don't know in advance the number of possibilities that could be returned, so we concat them into a collection object and return it, just to be safe.

Find a list by name

At this point we have just touched on the heirarchy of some of the API. We know that a single account is an entry and there is a collection of lists underneath that. In that collection there are individual list entries, each one having a collection of subscribers belonging to it. If this is starting to get confusing you can check out a graph we made just for you. It will show you what's on the top of the food-chain and how you can access the information you want by traversing through the heirarchy of the API.

Alright, our next adventure will be to find a list by name.

It will be exactly like finding a subscriber but we need to scroll through the lists collection to look for it instead of doing a find on the account like we did for findSubscribers().

First, we will print the lists, or in this case a collection of all the lists within the account. Then we can find on the collection. In the last part we can just print out the first list entry we find, with the name and ID and return it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?php

require('aweber_api/aweber_api.php');

class MyApp{

    function __construct() {
        # replace XXX with your real keys and secrets
        $this->consumerKey = 'XXX';
        $this->consumerSecret = 'XXX';
        $this->accessToken = 'XXX';
        $this->accessSecret = 'XXX';

        $this->application = new AWeberAPI($this->consumerKey, $this->consumerSecret);
    }

    function findList($listName) {
        $account = $this->application->getAccount($this->accessToken, $this->accessSecret);
        print_r($account->lists);

        $foundLists = $account->lists->find(array('name' => $listName));
        //must pass an associative array to the find method

        print_r($foundLists);

        return $foundLists[0];
    }
}

$app = new MyApp();
$app->findList($name='default');
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
from aweber_api import AWeberAPI


class MyApp(object):

    def __init__(self):
        # replace XXX with your keys
        consumer_key = 'XXX'
        consumer_secret = 'XXX'
        self.access_token = 'XXX'
        self.access_secret = 'XXX'

        self.application = AWeberAPI(consumer_key, consumer_secret)

    def find_list(self, **kwargs):
        account = self.application.get_account(self.access_token, self.access_secret)
        print account.lists

        found_lists = account.lists.find(**kwargs)
        print found_lists

        for _list in found_lists:
            print _list
            print _list.name, _list.id

            return _list


app = MyApp()
_list = app.find_list(name='default')
If you run the code, here is the response:
localhost:aweber-AWeber-API-PHP-Library yourname$ php test_app.php
AWeberCollection Object
(
    [pageSize:protected] => 100
    [_entries:protected] => Array
        (
        )

    [_privateData:protected] => Array
        (
            [0] => entries
            [1] => start
            [2] => next_collection_link
        )

    [_iterationKey:protected] => 0
    [adapter] => OAuthApplication Object
        (
            [debug] => 
            [userAgent] => AWeber OAuth Consumer Application 1.0 - https://labs.aweber.com/
            [format] => 
            [requiresTokenSecret] => 1
            [signatureMethod] => HMAC-SHA1
            [version] => 1.0
            [user] => OAuthUser Object
                (
                    [authorizedToken] => 
                    [requestToken] => 
                    [verifier] => 
                    [tokenSecret] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXE
                    [accessToken] => AXXXXXXXXXXXXXXXXXXXXXX3
                )

            [consumerKey] => AXXXXXXXXXXXXXXXXXXXXXXJ
            [consumerSecret] => qXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI
            [app] => AWeberServiceProvider Object
                (
                    [baseUri] => https://api.aweber.com/1.0
                    [accessTokenUrl] => https://auth.aweber.com/1.0/oauth/access_token
                    [authorizeUrl] => https://auth.aweber.com/1.0/oauth/authorize
                    [requestTokenUrl] => https://auth.aweber.com/1.0/oauth/request_token
                )

        )

    [data] => Array
        (
            [total_size] => 4
            [start] => 0
            [entries] => Array
                (
                    [0] => Array
                        (
                            [total_unconfirmed_subscribers] => 0
                            [name] => default
                            [total_subscribers_subscribed_yesterday] => 0
                            [http_etag] => "ea8f15575e8ce58a0683041adcee0275188d1fbc-ca5feee2b7fbb6febfca8af5541541ea960aaedb"
                            [web_form_split_tests_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/web_form_split_tests
                            [subscribers_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/subscribers
                            [total_subscribers_subscribed_today] => 0
                            [id] => XXXXXXX
                            [total_subscribed_subscribers] => 0
                            [total_unsubscribed_subscribers] => 0
                            [campaigns_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/campaigns
                            [custom_fields_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/custom_fields
                            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960
                            [total_subscribers] => 0
                            [resource_type_link] => https://api.aweber.com/1.0/#list
                            [web_forms_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/web_forms
                        )

                    [1] => Array
                        (
                            [total_unconfirmed_subscribers] => 0
                            [name] => fakelistyooooo
                            [total_subscribers_subscribed_yesterday] => 0
                            [http_etag] => "fb04fc02ff0638ebc377737c07d38c21edcceeb5-ca5feee2b7fbb6febfca8af5541541ea960aaedb"
                            [web_form_split_tests_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2427220/web_form_split_tests
                            [subscribers_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2427220/subscribers
                            [total_subscribers_subscribed_today] => 0
                            [id] => XXXXXXX
                            [total_subscribed_subscribers] => 0
                            [total_unsubscribed_subscribers] => 0
                            [campaigns_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2427220/campaigns
                            [custom_fields_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2427220/custom_fields
                            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2427220
                            [total_subscribers] => 0
                            [resource_type_link] => https://api.aweber.com/1.0/#list
                            [web_forms_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2427220/web_forms
                        )

                    [2] => Array
                        (
                            [total_unconfirmed_subscribers] => 0
                            [name] => morefakelistsss
                            [total_subscribers_subscribed_yesterday] => 0
                            [http_etag] => "67930cc524dc45fd36466f4c35b529e197316efb-ca5feee2b7fbb6febfca8af5541541ea960aaedb"
                            [web_form_split_tests_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2431816/web_form_split_tests
                            [subscribers_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2431816/subscribers
                            [total_subscribers_subscribed_today] => 0
                            [id] => XXXXXXX
                            [total_subscribed_subscribers] => 0
                            [total_unsubscribed_subscribers] => 0
                            [campaigns_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2431816/campaigns
                            [custom_fields_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2431816/custom_fields
                            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2431816
                            [total_subscribers] => 0
                            [resource_type_link] => https://api.aweber.com/1.0/#list
                            [web_forms_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2431816/web_forms
                        )

                    [3] => Array
                        (
                            [total_unconfirmed_subscribers] => 0
                            [name] => selectionoflist
                            [total_subscribers_subscribed_yesterday] => 0
                            [http_etag] => "8a1e464f72f258a0264252c7400be4168f4d44da-ca5feee2b7fbb6febfca8af5541541ea960aaedb"
                            [web_form_split_tests_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/web_form_split_tests
                            [subscribers_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/subscribers
                            [total_subscribers_subscribed_today] => 0
                            [id] => XXXXXXX
                            [total_subscribed_subscribers] => 2
                            [total_unsubscribed_subscribers] => 2
                            [campaigns_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/campaigns
                            [custom_fields_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/custom_fields
                            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732
                            [total_subscribers] => 4
                            [resource_type_link] => https://api.aweber.com/1.0/#list
                            [web_forms_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2281732/web_forms
                        )

                )

            [resource_type_link] => https://api.aweber.com/1.0/#list-page-resource
        )

    [_dynamicData] => Array
        (
        )

    [url] => /accounts/6XXXX4/lists
)
AWeberCollection Object
(
    [pageSize:protected] => 100
    [_entries:protected] => Array
        (
        )

    [_privateData:protected] => Array
        (
            [0] => entries
            [1] => start
            [2] => next_collection_link
        )

    [_iterationKey:protected] => 0
    [adapter] => OAuthApplication Object
        (
            [debug] => 
            [userAgent] => AWeber OAuth Consumer Application 1.0 - https://labs.aweber.com/
            [format] => 
            [requiresTokenSecret] => 1
            [signatureMethod] => HMAC-SHA1
            [version] => 1.0
            [user] => OAuthUser Object
                (
                    [authorizedToken] => 
                    [requestToken] => 
                    [verifier] => 
                    [tokenSecret] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXE
                    [accessToken] => AXXXXXXXXXXXXXXXXXXXXXX3
                )

            [consumerKey] => AXXXXXXXXXXXXXXXXXXXXXXJ
            [consumerSecret] => qXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI
            [app] => AWeberServiceProvider Object
                (
                    [baseUri] => https://api.aweber.com/1.0
                    [accessTokenUrl] => https://auth.aweber.com/1.0/oauth/access_token
                    [authorizeUrl] => https://auth.aweber.com/1.0/oauth/authorize
                    [requestTokenUrl] => https://auth.aweber.com/1.0/oauth/request_token
                )

        )

    [data] => Array
        (
            [start] => 0
            [total_size_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists?name=default2283960&ws.op=find&ws.show=total_size
            [entries] => Array
                (
                    [0] => Array
                        (
                            [total_unconfirmed_subscribers] => 0
                            [name] => default2283960
                            [total_subscribers_subscribed_yesterday] => 0
                            [http_etag] => "ea8f15575e8ce58a0683041adcee0275188d1fbc-ca5feee2b7fbb6febfca8af5541541ea960aaedb"
                            [web_form_split_tests_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/web_form_split_tests
                            [subscribers_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/subscribers
                            [total_subscribers_subscribed_today] => 0
                            [id] => XXXXXXX
                            [total_subscribed_subscribers] => 0
                            [total_unsubscribed_subscribers] => 0
                            [campaigns_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/campaigns
                            [custom_fields_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/custom_fields
                            [self_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960
                            [total_subscribers] => 0
                            [resource_type_link] => https://api.aweber.com/1.0/#list
                            [web_forms_collection_link] => https://api.aweber.com/1.0/accounts/6XXXX4/lists/2283960/web_forms
                        )

                )

            [total_size] => 1
        )

    [_dynamicData] => Array
        (
        )

    [url] => /accounts/6XXXX4/lists
    )


(my-test-app)username@localhost:~/my-test-app$ python test_app.py
<aweber_api.collection.AWeberCollection object at 0x1101c4950>
<aweber_api.collection.AWeberCollection object at 0x1101c48d0>
<aweber_api.entry.AWeberEntry object at 0x1101c4b50>
default 2XXXXX0

Add a subscriber

Yay! You can find subscribers, but what about adding them?

In this next method we are going show you exactly how to add a subscriber. We already have the account we want to add a subscriber to, but we will also need to know the list (because subscribers belong to a list and lists belong to an account). We can't skip over the hierarchy of the API.

When we find the list that we want to add the subscriber to, we need to make the URL that the request will go out to. To create a subscriber, you actually make a request to a URL which is why we need to tell the API which URL to look for the resource. To make the URL, you need to know the account ID and the list ID.

This method will require two things, the first is the subscriber, the second is the list ID. With these variables we can create the URL that the resource is stored at and then call a method from our handy wrapper that will do the POST request for us to create the new subscriber. Around the code that creates the subscriber, we want to use a try/except. This will ensure that the subscriber is successfully created and that we had no trouble along the way.

Make sure you have a valid email address. For example, if you tried to add a subscriber with the email 'jondoe@example.com' you would catch an error that said:

WebServiceError: email: Email address blocked.
Please refer to http://www.aweber.com/faq/questions/518/.

To run this, we need to first use the find_list() method we just created and use the _list that is returned. Then we can create a subscriber and pass that into our method. We can make a simple array to handle the subscriber and pass that into our method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<?php
require('aweber_api/aweber_api.php');

class MyApp{

    function __construct() {
        # replace XXX with your real keys and secrets
        $this->consumerKey = 'XXX';
        $this->consumerSecret = 'XXX';
        $this->accessToken = 'XXX';
        $this->accessSecret = 'XXX';

        $this->application = new AWeberAPI($this->consumerKey, $this->consumerSecret);
    }

    function addSubscriber($subscriber, $list) {
        # get your aweber account
        $account = $this->application->getAccount($this->accessToken, $this->accessSecret);

        # get your list
        $listUrl = "/accounts/$account->id/lists/$list->id";
        $list = $account->loadFromUrl($listUrl);

        try {
            # create your subscriber
            $list->subscribers->create($subscriber);
        }

        catch(Exception $exc) {
            print $exc;
        }
    }
}

$app = new MyApp();

$list = $app->findList($name='default');

$subscriber = array(
    'email' => 'johndoe@example.com',
    'name'  => 'John Doe'
);

$app->addSubscriber($subscriber, $list);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
from aweber_api import AWeberAPI


class MyApp(object):

    def __init__(self):
        # replace XXX with your keys
        consumer_key = 'XXX'
        consumer_secret = 'XXX'
        self.access_token = 'XXX'
        self.access_secret = 'XXX'

        self.application = AWeberAPI(consumer_key, consumer_secret)

    def add_subscriber(self, subscriber, _list):
        account = app.application.get_account(self.access_token, self.access_secret)

        list_url = '/accounts/%s/lists/%s' % (account.id, _list.id)
        _list = account.load_from_url(list_url)

        try:
            _list.subscribers.create(**subscriber)

        except Exception, exc:
            print exc


app = MyApp()

_list = app.find_list(name='default')

subscriber = {
    'email': 'johndoe@example.com',
    'name': 'John Doe',
}

app.add_subscriber(subscriber, _list)