Download OpenAPI specification:Download
We are constantly working to improve this documentation. If you have feedback and questions, please contact the AWeber API team at email@example.com.
The AWeber API is a REST API that uses the OAuth 2.0 authentication model.
Please see the below resources for further information:
|Security scheme type:||OAuth2|
|authorizationCode OAuth Flow|
Authorization URL: https://auth.aweber.com/oauth2/authorize
Token URL: https://auth.aweber.com/oauth2/token
Refresh URL: https://auth.aweber.com/oauth2/token
This means that resources are represented as JSON dictionaries and you use a different HTTP verb to do your standard CRUD operations on them:
Within this document, campaigns is a generic term that refers to both Broadcast and Follow Up messages. Currently the AWeber API does not support Campaigns, which is an email automation platform available to customers within the AWeber web platform.
Before you can make requests to the API, you need to support our authentication protocol. We currently require all API requests to use the OAuth 2.0 authentication protocol.
We recommend that you start out by visiting the OAuth 2.0 Overview. This will walk you through the authentication process.
API resources are arranged in the AWeber API based on their relationships to each other. We illustrate these relationships on the image below with the URLs of the resources. When we refer to the relationships of the resources, we say an Account has Lists, a List has Subscribers, etc. We can also say Subscribers belong to a List, or Lists belong to an Account, and so on.
A single resource is referred to as an Entry and is shown as a yellow circle on the image. Entries are contained in Collections which are shown as a blue box on the image. These resources are contained under version '1.0' of the API.
Collections are represented as an ordered sequence of entries. They are paginated using the
ws.start query parameters where
ws.size is the maximum number of entries to return and
the zero-based index to start the page at. The response represents a page of entries and includes at
least the following body properties:
|entries||List of Objects||The entries on the requested page|
|start||Non-negative Integer||The starting offset of the page|
|total_size||Non-negative Integer||The total size of the collection*|
|next_collection_link||URL||Link to the next page unless this is the final page|
|prev_collection_link||URL||Link to the previous page unless this is the first page|
Though you can specify the exact page that you want using
ws.start, you should use the
prev_collection_link properties in the response to traverse the collection.
prev_collection_link is absent, then the current page is the first page. Likewise, if the
next_collection_link is absent, then the current page is the last page in the collection.
The AWeber API uses the OAuth 2.0 specification for authentication. OAuth 2.0 is the successor to OAuth 1, which AWeber’s API formerly used. If you have an existing OAuth 1 application, documentation regarding how to connect with OAuth 1 is available. Please plan to move to OAuth 2.0 as soon as you are able.
Connecting your integration to an AWeber customer account requires the use of OAuth 2.0. This step is required before you start making requests to AWeber’s API in order to do things like add subscribers, check your broadcast stats, or sending messages. We use OAuth 2.0 in order to ensure that an integration has permission to access a given AWeber account.
You'll need the following to get started:
If you need a customer account you can sign up for a free trial to get started. These examples will be using Python 3 and requests_oauthlib as the HTTP library. You will find there are lots of good libraries available for every programming language. The set up and usage varies between libraries. Be sure to read the documentation for the library you select. For a full sample in Python as well as PHP please see our code samples on GitHub.
Do you just need the endpoints and not a whole walkthrough? Our authorization endpoints are listed below:
OAuth is a way for a developer to securely access information without knowing someone’s password or other login details. The end result of OAuth is an access token, which prove the developer has permission to access the data held in the API and should always be kept safe and secure.
The general flow of OAuth 2.0 is a back and forth handshake between the developer, the AWeber customer, and AWeber’s API. In this guide you’ll learn to do the following:
The first thing you’ll need to do is create a hyperlink to start the authorization process. This code provides AWeber’s API with information such as which integration is making the request and what access the integration requires. Please review the example below:
The components of this URL are as follows:
response_typetells AWeber what you want us to send back. For this step you should always use
codesince you want an authorization code.
client_idis the Client ID listed in your developer account. It uniquely identifies your integration to AWeber.
redirect_uriis your callback. This is where the user-agent (in most cases the customer’s browser) will be sent after the customer clicks
authorize. This should be a uri that your application can read because that’s where we’ll provide our response. When you provide your callback, make sure it’s the same one you specified when creating your integration.
stateis a token you provide to AWeber for CSRF protection. You can also use this token as a session token to preserve user data between the auth steps, providing a better experience for your users. We pass this data back to you later and you can check that it matches the value you sent. A random string or a hash of a session cookie is acceptable here, it just needs to be something you know but a potential attacker doesn’t and it should change for each new user.
scopeis a list of space separated permissions your integration requires. To change permissions later, all customers will need to repeat the authorization process. Please ensure you have the ones you need.
|account.read||get accounts, get account, get integrations, get integration|
|list.read||get list, get lists, find lists, get tags for list, get custom fields, get custom field, get webforms for list, get split tests for list, get split test components, get split test component, get webforms for account, get split tests for account|
|list.write||add custom field, update custom field, delete custom field|
|subscriber.read||get subscribers, get subscriber, get subscriber activity, get subscribers for message|
|subscriber.write||add subscriber, move subscriber, update subscriber, delete subscriber|
|subscriber.read-extended||find subscribers for account, find subscribers for list required to return subscriber fields that are considered PII and normally omitted from responses (currently: email, ip_address, miscellaneous notes, and name)|
|email.read||get messages, get message, get broadcasts, get broadcast, get message opens, get message open, get message tracked events, get message tracked event, get total broadcasts, get campaigns, get campaign, find campaigns, get links, get link, get clicks, get click, get broadcast statistics, get broadcast statistic|
|email.write||create broadcast, update broadcast, delete broadcast, cancel broadcast, schedule broadcast|
Below is an example using requests_oauthlib.
from requests_oauthlib import OAuth2Session AUTHORIZE_URL = 'https://auth.aweber.com/oauth2/authorize' # Replace with your real values client_id = '****' redirect_uri = 'https://localhost' scope = ['account.read', 'list.read', 'subscriber.read', 'email.read'] oauth = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope) authorization_url, state = oauth.authorization_url(AUTHORIZE_URL) print(authorization_url)
The output will be the authorize URL for your integration user.
Using the authorization URL you generated in Step 1, create a button or hyperlink that says “Click to connect to AWeber” or something similar.
The link you provide will lead customers to AWeber’s authorization screen. This screen outlines your integration, the access being requested, and an area for customers to provide their username and password. Customers will review the screen, enter their login credentials, and click authorize.
Clicking authorize (after entering valid credentials) redirects the user to the callback URI you specified in Step 1. In the query string of the redirect will be a query parameter containing your authorization code. If you provided a state token in step 1, that is sent back as a second query parameter.
For example, if the
redirect_uri you provided was
https://app.example.com/auth we would redirect the AWeber customer’s browser to
You should collect the query parameters from the URI. Please verify the
state token sent to you is the same as the one you gave us. If everything is valid, save
code parameter for the next step. Your chosen library may handle verification of the state token for you.
Now that you have your authorization code you’re ready to get your access token! This involves making a POST request to our access token URL,
https://auth.aweber.com/oauth2/token using your
client ID and
client secret from your developer account. We recommend using HTTP Basic
authentication with the
client ID as the username and the
client secret as the password. Most libraries support this approach. If yours doesn’t,
please send them as query parameters called
client_secret. Here’s what a POST request looks like using basic authentication:
POST /oauth2/token Content-Type: application/x-www-form-urlencoded Authorization: Basic ***************** https://auth.aweber.com/oauth2/token?grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_CALLBACK
The parameters required are as follows:
grant_typeis a parameter that tells us if you’re getting a brand new access token or refreshing one. For a new token always pick
codeis the authorization code you obtained in step 2.
redirect_uriis your callback again. Make sure it’s the same as the one you used before! We use this to help verify it’s still the same app making the request.
Our response will contain your
expires_in value, and a
refresh_token. Congratulations, you now have the access token required to make
requests to AWeber’s API! You can try it out right away, but make sure to save the
refresh_token information for later.
NOTE: Tokens should not be shared publicly. Please save them somewhere safe.
To use the
access_token you must include it with your request using (in order of preference) a bearer authentication header, a form encoded parameter in the body,
or a query parameter. Any of those three will work, but please choose one.
This access token remains good for the amount of seconds specified by the
expires_in field. After that time passes you will need to refresh your token, which is covered in the final step of this walkthrough.
Here is a requests_oauthlib example, using the same
OAuth2Session that was set up previously:
client_secret = '*****' authorization_response = input('Log in and paste the returned URL here: ') token = oauth.fetch_token( 'https://auth.aweber.com/oauth2/token', authorization_response=authorization_response, client_secret=client_secret ) print(token)
If it has been a while since you obtained your access token, all requests to AWeber’s API will return an unauthorized error. To correct the error,
you need to refresh your access token. This step works much like obtaining an access token. You will make a POST request to AWeber’s token endpoint.
This time specify a
refresh_token and you include your refresh token in the request (instead of the authorization code). Please review the example below:
POST /oauth2/token Content-Type: application/x-www-form-urlencoded Authorization: Basic ******************* https://auth.aweber.com/oauth2/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN
The response is similar to the access token. You will receive a new
expires_in parameter, and a
refresh_token. This is required each time your token expires.
Most libraries manage refreshing tokens for you by reading the
expires_in parameter from a file or database location. Please refer to your library’s documentation about automatic refreshing. The implementation may vary slightly. When using Python’s requests_oauthlib library the call looks like this, where
oauth is an OAuth2Session:
client_id = '*****' client_secret = '*****' token = oauth.refresh_token('https://auth.aweber.com/oauth2/token', client_id=client_id, client_secret=client_secret)
Sometimes an integration is used by many AWeber customers. You can have as many users as you like with this authentication process. Just start at the top and make a new request token for each user of your integration. Access tokens are tied to AWeber customer accounts so each account will have a new set of tokens. You can store them safely in a database and use the account ID to differentiate them.
Here are some solutions to common problems:
If you still can’t figure it out we’re always happy to help you work through any errors. Send us an email at firstname.lastname@example.org and be sure to note any errors or information about the problem you’re having.
The following examples show how to obtain an access token for an AWeber account using Python. For a PHP version please see our PHP code sample on GitHub.
Below is a python example using the
requests_oauthlib OAuth library to
obtain an accounts access tokens.
You will need:
Client Secret, and
Redirect URIfrom your application, available on the My Apps Page.
passwordfor an AWeber account you want to connect.
from requests_oauthlib import OAuth2Session client_id = '*****' client_secret = '*****' redirect_uri = 'YOUR_REDIRECT_URI' # Sample scopes. Put the ones you need here. scope = ['account.read', 'list.read', 'subscriber.read'] authorization_base_url = 'https://auth.aweber.com/oauth2/authorize' token_url = 'https://auth.aweber.com/oauth2/token' # Create a new OAuth2Session with your information. aweber = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope) # requests_oauthlib generates a state token for us, # but you can optionally specify your own. authorization_url, state = aweber.authorization_url(authorization_base_url) # Open link in browser to authorize. print("Go here to authorize: ", authorization_url) # Get the auth code from the callback. redirect_response = input("Enter the full redirect URL: ") # Use the auth code to get access tokens. token = aweber.fetch_token(token_url, client_secret=client_secret, authorization_response=redirect_response) print("Access Token: ", token['access_token']) print("Refresh Token: ", token['refresh_token']) print("Token Type: ", token['token_type']) print("Expires In: ", token['expires_in']) print("Expires At: ", token['expires_at']) resp = aweber