AWeber API (1.0)

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 protected].

The AWeber API is a REST API that uses the OAuth 2.0 authentication model. We also offer webhooks.

Please see the below resources for further information:

Getting Started

Creating a Developer Account

To start developing, you will first need to create a free developer account. After you create a developer account, log in and create an app.

What does AWeber provide?

AWeber provides a REST API and Webhooks. For more information about webhooks please navigate to the Webhooks section within this documentation.

What is the AWeber API?

The AWeber API is a JSON based REST API.

This means that resources are represented as JSON dictionaries and you use a different HTTP verb to do your standard CRUD operations on them:

  • POST: Create new resources.
  • GET: Retrieve a resource.
  • PATCH: Update existing resources.
  • DELETE: Delete existing resources.

Note

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.

Authentication

Before you can make requests to the API, you need to support our authentication protocol. We currently require all new applications using the API to make use of 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.

How Resources are Arranged in the AWeber API

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.

[Resource Map]

 

How Collections are Represented

Collections are represented as an ordered sequence of entries. They are paginated using the ws.size and ws.start query parameters where ws.size is the maximum number of entries to return and ws.start is the zero-based index to start the page at. The response represents a page of entries and includes at least the following body properties:

Name Type Description
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.size and ws.start, you should use the next_collection_link and prev_collection_link properties in the response to traverse the collection. If the 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.

Authentication Overview

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:

  • An AWeber developer account
  • An app created in that account
  • An AWeber customer account
  • An HTTP library capable of making OAuth 2.0 requests.

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, C#.NET, Ruby, and Node.js please see our code samples on GitHub.

OAuth 2.0

The following endpoints and scopes are used to authenticate.

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
Scopes:
  • account.read -
    Access account information and associated integrations.
    Required for the following endpoints: get accounts, get account, get integrations, get integration
  • landing-page.read -
    Retrieve landing pages
    Required for the following endpoints: get landing pages, get landing page
  • list.read -
    Retrieve lists, custom fields, tags, and sign up forms
    Required for the following endpoints: 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 -
    Create, edit, and delete custom fields
    Required for the following endpoints: add custom field, update custom field, delete custom field
  • subscriber.read -
    Retrieve subscribers and their activity
    Required for the following endpoints: get subscribers, get subscriber, get subscriber activity, get subscribers for message, find subscribers for account, find subscribers for list
  • subscriber.write -
    Create, edit, delete, retrieve, search for, and move subscribers
    Required for the following endpoints: add subscriber, move subscriber, update subscriber, delete subscriber
  • subscriber.read-extended -
    Previously required to retrieve subscriber PII such as name, email, IP address, etc. This functionality was moved to the "subscriber.read" scope
  • email.read -
    Retrieve email activity related to broadcasts and follow-ups
    Required for the following endpoints: 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 and send email broadcasts
    Required for the following endpoints: create broadcast, update broadcast, delete broadcast, cancel broadcast, schedule broadcast

What is OAuth 2.0?

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 proves that the developer has permission to access the data held in the API and should always be kept safe and secure. If you are creating an application that cannot store secrets in an secure way (e.g. a mobile application or a WordPress plugin) use Proof Key for Code Exchange (PKCE) which does not require the client secret to be used or stored. See Public or confidential? below for more detail.

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:

  1. Build an authorization URL
  2. Get an authorization code
  3. Trade your authorization code for an access token
  4. Refresh your access token after it expires using the refresh token

If your client is a public client, then you do not have a client secret and you are required to use the code verifier and code challenge instead of the client secret. The steps required are the same except that the client_secret is not used. See Public or confidential? below for more detail.

Step 1: Build an authorization URL

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:

https://auth.aweber.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK&scope=YOUR_REQUESTED_SCOPES&state=STATE_TOKEN

The components of this URL are as follows:

  • The base URL is provided by AWeber and connects you to our servers.

  • response_type tells AWeber what you want us to send back. For this step you should always use code since you want an authorization code.

  • client_id is the Client ID listed in your developer account. It uniquely identifies your integration to AWeber.

  • redirect_uri is 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.

    If your application will be installed on multiple domains, you can send the authorization code out-of-band (OOB) instead. This will display the code in a page where users can copy and paste it into your application. To do this, configure your application's redirect URI to the special value urn:ietf:wg:oauth:2.0:oob and use this value for your redirect_uri.

To learn more about how to implement OOB, please visit our knowledge base article.

  • state is 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.
  • scope is 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.

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.

Step 2: Get an Authorization Code

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:

https://app.example.com/auth?code=YOUR_NEW_AUTH_CODE&state=STATE_YOU_PROVIDED

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 the code parameter for the next step. Your chosen library may handle verification of the state token for you.

If you specified urn:ietf:wg:oauth:2.0:oob as your redirect_uri, the code will be displayed in a page for users to copy and paste into your application instead.

Step 3: Trade your Authorization Code for an Access Token

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 your library does not support setting the Authorization header, please send them as query parameters called client_id and client_secret.

Here’s what a POST request looks like using basic authentication:

POST /oauth2/token HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic *****************

grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_CALLBACK

The parameters required are as follows:

  • grant_type is a parameter that tells us if you’re getting a brand new access token or refreshing one. For a new token always pick authorization_code.
  • code is the authorization code you obtained in step 2.
  • redirect_uri is 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 access_token, an 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 expires_in and 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 a bearer authentication header. If you cannot set the Authorization header, then you may include the access token in a form-encoded body parameter named access_token or a query parameter of the same name. 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 of fetching a token 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)

Step 4: Refresh the Access 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 grant_type of refresh_token and you include your refresh token in the request (instead of the authorization code). The same rules apply to including your client credentials (client_id and client_secret). The following example shows how to refresh a token using requests_oauthlib again.

POST /oauth2/token HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic *******************

grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN

The response is the same as when you redeem the authorization code for an access token. You will receive a new access_token, an 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)

Public or confidential?

The preceding examples assumed that your applications configuration is kept secret since the client secret is used to create and refresh tokens. The client secret is required to be kept secret at all times. Anyone that has access to your client identifier and secret can access the data of every AWeber customer using your application. This works well for applications that you host in a closed environment but it does not work for mobile applications or integrations without secure configuration (e.g., Wordpress plug-ins).

The OAuth 2.0 framework defines two client types in RFC-6749:

Confidential

Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.

Public

Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.

Public clients cannot use the standard OAuth 2.0 Authorization Code flow since they are incapable of maintaining secrets. For this reason, the AWeber API supports supports Proof Key for Code Exchange (PKCE) as specified in RFC-7636 for public clients.

There are a few differences in the authorization flow for PKCE. The most important is that you never include your client secret. Instead of using a client secret that is shared between the client and the authorization server, PKCE has the client create a string of ASCII characters known as the code verifier. A hashed digest of the verifier is sent with the authorization request (step 1) and the verifier is added to the token request (step 3). The server saves the hashed digest (also known as the code challenge) with the authorization code that it generates and compares the verifier to the challenge when redeeming the authorization code.

Let's walk through the differences from the standard flow step-by-step to see how PKCE works without a client secret.

Step 1: Build an authorization URL

The authorization URL for public clients requires two additional parameters to act as a transient secret. The code challenge is the hashed version of the code verifier. The code challenge method identifies the hash algorithm that was used to generate the challenge. This is required to be S256 since the AWeber API only supports SHA256 hashed challenges.

Before sending the authorization request, the client is required to generate a code verifier that is a random string of at least 43 characters and at most 128 characters. See RFC-7636 for a precise description of the code verifier. Then the client generates the code challenge from the verifier by hashing the verifier using SHA-256 and Base64 encoding the resulting value using the url-safe base64 variant. The challenge and challenge method are sent as the code_challenge and code_challenge_method query parameters in the authorization URL.

The following python snippet will generate an acceptable random verifier and code challenge:

import base64
import hashlib
import os
import uuid

# Generate a ASCII verifier string -- we are using base64.urlsafe_b64encode
# here to ensure that the characters in the string are valid.  The verifier
# is NOT REQUIRED to be a base 64 encoded string.  The use of base64 here is
# for convenience ONLY.
verifier_bytes = os.urandom(32)
code_verifier = base64.urlsafe_b64encode(verifier_bytes).rstrip(b'=')
challenge_bytes = hashlib.sha256(code_verifier).digest()
code_challenge = base64.urlsafe_b64encode(challenge_bytes).rstrip(b'=')
state = str(uuid.uuid4())

# Use the following parameters in the authorize URL.
url_parameters = {
    'response_type': 'code',
    'client_id': MY_CLIENT_ID,
    'redirect_uri': MY_REDIRECT_URI,
    'scope': REQUESTED_SCOPES,
    'state': state,
    'code_challenge': code_challenge,
    'code_challenge_method': 'S256',
}

Remember that the client is REQUIRED to save the code_verifier for use in step 3.

Step 2: Get an Authorization Code

This step is unchanged from the standard authorization code flow.

Step 3: Trade your Authorization Code for an Access Token

Instead of using the client secret, the client passes the code verifier that was generated in step 1. It also pass the client_id in the body instead of the Authorization header. This avoids possible issues with libraries that do not support having an empty password.

The POST request should look like the following:

POST /oauth2/token HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_CALLBACK&client_id=YOUR_CLIENT_ID&code_verifier=CODE_VERIFIER_FROM_STEP_1

Step 4: Refresh the Access Token

With OAuth 2.0, your access tokens will expire after ~2 hours. Several methods for refreshing are possible. If you do not refresh your token, you will receive an access token expired error.

For Public clients, you omit the client_secret from the authorization parameters. The client should include the client_id in the body instead of using an Authorization header without a password.

Have more than one user?

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.

Having trouble?

Here are some solutions to common problems:

  • Check the documentation for your chosen library. Are the calls being made correctly and is everything being passed around as it should be?
  • Is your access token still valid? Try refreshing the token and see if that fixes any 401 Unauthorized errors.
  • Did you copy your client ID and secret correctly? Make sure the ID and secret you’re using are the ones we provided in your developer account.
  • Make sure you’re using your AWeber customer account and not your AWeber developer account on the authorization login page.

If you still can’t figure it out we’re always happy to help you work through any errors. Send us an email at [email protected] and be sure to note any errors or information about the problem you’re having.

OAuth 2.0 Examples

The following examples show how to obtain an access token for an AWeber account using Python. For PHP, C#.NET, Ruby, and Node.js versions please see our PHP, C#.NET, Ruby, and Node.js code samples on GitHub.

Get An Access Token

Below is a python example using the requests_oauthlib OAuth library to obtain an accounts access tokens.

You will need:

  • The Client ID, Client Secret, and Redirect URI from your integration, available on the My Apps Page.
  • The list of scopes to allow for the customer's account.
  • The username and password for an AWeber account that you want to connect.
from requests_oauthlib import OAuth2Session

AUTHORIZATION_BASE_URL = 'https://auth.aweber.com/oauth2/authorize'
TOKEN_URL = 'https://auth.aweber.com/oauth2/token'

client_id = '*****'
client_secret = '*****'
redirect_uri = 'YOUR_REDIRECT_URI'

# Sample scopes. Put the ones that you need here.
scope = ['account.read', 'list.read', 'subscriber.read']

# 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.get('https://api.aweber.com/1.0/accounts')
resp.raise_for_status()
print(resp.json())

Now you should have your access token and account id from the output. The last call in the example is to retrieve the /accounts resource in order to retrieve the account id. The account id and access token are needed for every api call.

Distributing the application's source code?

If you are making the source code of your integration public, you may not have a means to distribute the client secret securely. If you cannot guarantee the confidentiality of your client secret, then you are required to use Proof Key for Code Exchange as described in Public or confidential.

Below is an example on how to authenticate using PKCE with the requests_oauthlib library. You will need:

  • The Client ID, and Redirect URI from your integration, available on the My Apps Page.
  • The list of scopes to allow for the customer's account.
  • The username and password for an AWeber account that you want to connect.
import base64
import hashlib
import os
import urllib as parse

from requests_oauthlib import OAuth2Session

AUTHORIZATION_BASE_URL = 'https://auth.aweber.com/oauth2/authorize'
TOKEN_URL = 'https://auth.aweber.com/oauth2/token'

client_id = input('Your client ID:    ')
redirect_uri = input('Your redirect URI: ')

# Sample scopes. Put the ones that you need here.
scope = ['account.read', 'list.read', 'subscriber.read']

# Create a new OAuth2Session with your information.
aweber = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope)

# Generate a valid code verifier and derived code challenge.
verifier_bytes = os.urandom(32)
code_verifier = base64.urlsafe_b64encode(verifier_bytes).rstrip(b'=')
challenge_bytes = hashlib.sha256(code_verifier).digest()
code_challenge = base64.urlsafe_b64encode(challenge_bytes).rstrip(b'=')

# requests_oauthlib generates a state token for us, 
# but you can optionally specify your own.
authorization_url, state = aweber.authorization_url(
    AUTHORIZATION_BASE_URL, code_challenge=code_challenge,
    code_challenge_method='S256')

# 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, authorization_response=redirect_response, client_secret=None,
    body=parse.urlencode({'code_verifier': code_verifier}))

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.get('https://api.aweber.com/1.0/accounts')
resp.raise_for_status()
print(resp.json())

OAuth 2.0 Traces

This section contains low-level HTTP traces of the OAuth 2.0 authorization code flow. The client IDs, client secrets, authorization codes, and other details are fictitious and should not be used anywhere else.

Confidential protocol flow

The following HTTP trace shows the entire flow for a Confidential client using the following parameters:

Parameter Value
Client ID N1nwOnhAUyEjJcA0l4eI7dCfYKNVizSDE4Le0J4FRqc
Client secret rSu9NU70xOZFN2ojnWq3tLI49kb8vs84_KZQe1bcJy4
Scopes account.read list.read subscriber.read
Redirect URI https://127.0.0.1/oauth2-callback
State 62cdb1ee8a5c40f6ba0d5de1dfa83113
Authorization code VhXKzYi5paFfs1aYqgikSw

The web application initiates the authorization flow.

GET /oauth2/authorize?response_type=code&client_id=N1nwOnhAUyEjJcA0l4eI7dCfYKNVizSDE4Le0J4FRqc&redirect_uri=https%3A%2F%2F127.0.0.1%2Foauth2-callback&scope=account.read+list.read+subscriber.read&state=62cdb1ee8a5c40f6ba0d5de1dfa83113 HTTP/1.1
Host: auth.aweber.com

HTTP/1.1 200 OK
Content-Type: text/html

<html>.... authorization form ....</html>

The user authenticates and authorizes the application.

The authorization form action initiates a POST to the AWeber authorization server which redirects the user to the application-specified redirect URL.

POST /oauth2/authorize HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded

parameters-omitted

HTTP/1.1 302 Found
Location: https://127.0.0.1/oauth2-callback?state=62cdb1ee8a5c40f6ba0d5de1dfa83113&code=VhXKzYi5paFfs1aYqgikSw

The external application exchanges the authorization code for an access token.

POST /oauth2/token HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic TjFud09uaEFVeUVqSmNBMGw0ZUk3ZENmWUtOVml6U0RFNExlMEo0RlJxYzpyU3U5TlU3MHhPWkZOMm9qbldxM3RMSTQ5a2I4dnM4NF9LWlFlMWJjSnk0

grant_type=authorization_code&code=VhXKzYi5paFfs1aYqgikSw&redirect_uri=https%3A%2F%2F127.0.0.1%2Foauth2-callback

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "uPloUGQL689I9qYk1nkwjb2yZirWnoja",
  "refresh_token": "XF2OZN3dmSSphGimcoNbq839UGT0lGo2",
  "expires_in": 7200,
  "state": "62cdb1ee8a5c40f6ba0d5de1dfa83113"
}

Public protocol flow

The following HTTP trace shows the entire flow for a Public client using the following parameters:

Parameter Value
Client ID N1nwOnhAUyEjJcA0l4eI7dCfYKNVizSDE4Le0J4FRqc
Code verifier HLBvz1g_bbLZ31kjvlXJ5Rl0W1GgxU8rjYJdQIIEH_Y
Scopes account.read list.read subscriber.read
Redirect URI https://127.0.0.1/oauth2-callback
State 62cdb1ee8a5c40f6ba0d5de1dfa83113
Authorization code VhXKzYi5paFfs1aYqgikSw

The web application initiates the authorization flow.

GET /oauth2/authorize?response_type=code&client_id=N1nwOnhAUyEjJcA0l4eI7dCfYKNVizSDE4Le0J4FRqc&code_challenge=-oiamT7-EafhQ27P3V9cGEtu3crg731kec-GWhgrTV8&code_challenge_method=S256&redirect_uri=https%3A%2F%2F127.0.0.1%2Foauth2-callback&scope=account.read+list.read+subscriber.read&state=62cdb1ee8a5c40f6ba0d5de1dfa83113 HTTP/1.1
Host: auth.aweber.com

HTTP/1.1 200 OK
Content-Type: text/html

<html>.... authorization form ....</html>

The authorization form action initiates a POST to the AWeber authorization server which redirects the user to the application-specified redirect URL.

The user authenticates and authorizes the application.

POST /oauth2/authorize HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded

parameters-omitted

HTTP/1.1 302 Found
Location: https://127.0.0.1/oauth2-callback?state=62cdb1ee8a5c40f6ba0d5de1dfa83113&code=VhXKzYi5paFfs1aYqgikSw

The external application exchanges the authorization code for an access token.

POST /oauth2/token HTTP/1.1
Host: auth.aweber.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code&code=VhXKzYi5paFfs1aYqgikSw&code_verifier=HLBvz1g_bbLZ31kjvlXJ5Rl0W1GgxU8rjYJdQIIEH_Y&client_id=N1nwOnhAUyEjJcA0l4eI7dCfYKNVizSDE4Le0J4FRqc

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "uPloUGQL689I9qYk1nkwjb2yZirWnoja",
  "refresh_token": "XF2OZN3dmSSphGimcoNbq839UGT0lGo2",
  "expires_in": 7200,
  "state": "62cdb1ee8a5c40f6ba0d5de1dfa83113"
}

OAuth 2.0 Reference

These endpoints are used to authenticate with the api. The AWeber API uses the OAuth 2.0 model to handle authentication. OAuth is a standardized way for services to grant permission on a user's behalf to another application, without exposing their credentials (ie - username and password).

Get a token

post /oauth2/token
https://auth.aweber.com/oauth2/token

This endpoint is used to get an access token. This endpoint can obtain an access point from one of two grant types.

In the initial authorization, a grant_type of authorization_code is used with the authorization_code received from the URL the user is redirected to after authorizing the integration to their account.

If an access token is expired this endpoint can be used with a grant_type of refresh_token and the refresh_token stored for the user's access token.

This endpoint must be provided with the client_id and client_secret either in the Authorization header (preferred) or in the request body.

header Parameters
Authorization
string
Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

A base-64 encoded string for client_id:client_secret.

Request Body schema: application/json
One of
  • Authorization Code
  • Refresh Token (Confidential)
  • Refresh Token (Public)
  • Proof Key for Code Exchange (PKCE)
client_id
required
string

The client ID of the application. Available on the My Apps Page.
Not required if Authorization header is set.

client_secret
required
string

The client secret of the application. Available on the My Apps Page.
Not required if Authorization header is set.

grant_type
required
string
Value: "authorization_code"

The grant type of the token.

code
required
string

The authorization code received from the authorization call.

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "client_id": "***************",
  • "client_secret": "***************",
  • "grant_type": "authorization_code",
  • "code": "***************"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "access_token": "***************",
  • "expires_in": 7200,
  • "refresh_token": "***************",
  • "token_type": "bearer"
}

Revoke a token

post /oauth2/revoke
https://auth.aweber.com/oauth2/revoke

This endpoint is used to revoke an access or refresh token.

header Parameters
Authorization
string
Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

A base-64 encoded string for client_id:client_secret. The client_secret must be left blank for public clients.

Request Body schema:
One of
  • Confidential
  • Proof Key for Code Exchange (PKCE)
client_id
required
string

The client ID of the application. Available on the My Apps Page.
Not required if Authorization header is set.

client_secret
required
string

The client secret of the application. Available on the My Apps Page.
Not required if Authorization header is set.

token
string

The access token or refresh token to revoke

token_type_hint
string
Enum: "access_token" "refresh_token"

Type of token given in the token parameter. Valid values are

  • access_token
  • refresh_token

If not specified, search for both kinds of tokens.

Responses

200

The token has been deleted

400

OAuth 2 error response (see RFC-6749)

401

OAuth 2 error response (see RFC-6749)

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

Request samples

Content type
Example
Copy
Expand all Collapse all
{
  • "client_id": "*********",
  • "client_secret": "*********",
  • "token": "gTCFZykztNGFcQlKViqkXN_uKG5fDl0SAGcEQNjSePk",
  • "token_type_hint": "access_token"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error": "invalid_request",
  • "error_description": "Missing parameter or other invalid request, or trying to pass in a client secret for a public client",
  • "error_uri": "https://api.aweber.com"
}

OAuth 1.0a Reference

Get a request token

post /oauth/request_token
https://auth.aweber.com/1.0/oauth/request_token

This endpoint is used to get a request token.

Request Body schema: application/x-www-form-urlencoded

This request body requires the application/x-www-form-urlencoded MIME type.

oauth_consumer_key
string

The consumer key assigned to your application, available on the My Apps Page

oauth_callback
string

A url that will be sent the verifier token when authorizing the request token in a future step. If you don't have a callback, use oob as the value, this will indicate that the callback is 'out of band' and will display an html page after authorization, containing the verifier token.

oauth_nonce
string

A unique, randomly generated string. Each request should have a unique nonce.

oauth_signature
string

This is an HMAC-SHA1 hash of the entire request, including the application's secret, and the customer's oauth_token_secret. Generating the signature is a complex process, and we highly recommend using an OAuth library that will handle this for you.

oauth_signature_method
string

The hashing algorithm that was used to generate the signature. AWeber only supports the HMAC-SHA1 hash, so that's what this parameter should always be.

oauth_timestamp
string

Timestamp for the request. This is in the format of a Unix timestamp, or seconds since January 1st, 1970.

oauth_token
string

This is the token that represents the user of the application. This will be either the request token, when in the process of gaining an access token, or the access token when making requests to the AWeber API. The oauth_token parameter will be blank when you are getting a request token for a new user.

oauth_version
string

This identifies which version of the OAuth protocol you are using, and should always be 1.0 when working with the AWeber API.

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Response samples

Content type
application/json
Copy
Expand all Collapse all
"oauth_token_secret=******************&oauth_token=******************&oauth_callback_confirmed=true"

Get an access token

post /oauth/access_token
https://auth.aweber.com/1.0/oauth/access_token

This endpoint is used to get an access token.

Request Body schema: application/x-www-form-urlencoded

This request body requires the application/x-www-form-urlencoded MIME type.

oauth_consumer_key
string

The consumer key assigned to your application, available on the My Apps Page

oauth_callback
string

A url that will be sent the verifier token when authorizing the request token in a future step. If you don't have a callback, use oob as the value, this will indicate that the callback is 'out of band' and will display an html page after authorization, containing the verifier token.

oauth_nonce
string

A unique, randomly generated string. Each request should have a unique nonce.

oauth_signature
string

This is an HMAC-SHA1 hash of the entire request, including the application's secret, and the customer's oauth_token_secret. Generating the signature is a complex process, and we highly recommend using an OAuth library that will handle this for you.

oauth_signature_method
string

The hashing algorithm that was used to generate the signature. AWeber only supports the HMAC-SHA1 hash, so that's what this parameter should always be.

oauth_timestamp
string

Timestamp for the request. This is in the format of a Unix timestamp, or seconds since January 1st, 1970.

oauth_token
string

This is the token that represents the user of the application. This will be either the request token, when in the process of gaining an access token, or the access token when making requests to the AWeber API. The oauth_token parameter will be blank when you are getting a request token for a new user.

oauth_version
string

This identifies which version of the OAuth protocol you are using, and should always be 1.0 when working with the AWeber API.

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Response samples

Content type
application/json
Copy
Expand all Collapse all
"oauth_token_secret=******************&oauth_token=******************"

Accounts

What is it?

Represents AWeber Customer Accounts that have authorized your application.

The Account collection contains a single account entry for the AWeber Customer Account that has authorized your application. You can use the links in the Account entry to retrieve the lists owned by the account as well as the social integrations associated with the account.

Get accounts

get /accounts
/1.0/accounts

This endpoint is used to get a paginated collection of accounts.

Check out examples for Python, PHP, Postman, C#.NET, Ruby, and Node.js.

Authorizations:
OAuth 2.0 (account.read)
query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get account

get /accounts/{accountId}
/1.0/accounts/{accountId}

This endpoint is used to retrieve information for a specific account.

Check out examples for Python, PHP, Postman, C#.NET, Ruby, and Node.js.

Authorizations:
OAuth 2.0 (account.read)
path Parameters
accountId
required
integer <int32>

The account ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Broadcasts

What is it?

Represents broadcast messages associated with a specific list.

Use this set of resources to create, retrieve, modify, schedule, and delete broadcast messages on a list.

The broadcast collection is paginated in pages of 100 items by default and sorted based on the message status. Each response page includes next_collection_link and prev_collection_link properties to traverse the collection. See How Collections are Represented for traversal details and the following table for sorting.

Status Sort attribute Description
draft broadcast_id A Broadcast Message that has been created via the Create Broadcast endpoint and is currently unscheduled
scheduled scheduled_for A Broadcast Message that has scheduled but not sent
sent sent_at A Broadcast Message that has been sent

Get broadcasts

get /accounts/{accountId}/lists/{listId}/broadcasts
/1.0/accounts/{accountId}/lists/{listId}/broadcasts

This endpoint is used to get a paginated collection of broadcasts under the specified account and list. The sort order is dependent on the requested status.

  • draft messages are sorted by broadcast_id and only include API created broadcast drafts
  • scheduled messages are sorted by scheduled_for
  • sent messages are sorted by sent_at

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
status
required
string
Enum: "draft" "scheduled" "sent"

The status of the broadcasts to retrieve. (Please be aware that draft only returns API created Broadcast drafts)

ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \
  -d status=sent \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json

Create broadcast

post /accounts/{accountId}/lists/{listId}/broadcasts
/1.0/accounts/{accountId}/lists/{listId}/broadcasts

This endpoint is used to create a broadcast message draft. This POST request is limited to 1 million bytes.

Check out related examples:

Authorizations:
OAuth 2.0 (email.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

Request Body schema: application/x-www-form-urlencoded

Request Body

body_html
required
string <html>

The content of the message in html format. If body_text is not provided, it will be auto-generated. If body_text is not provided, body_html must be provided.

body_text
required
string

The content of the message in plain text, used when HTML is not supported. If body_html is not provided, the broadcast will be sent using only the body_text. If body_text is not provided, body_html must be provided.

body_amp
string <amp>

[Please read our KB article before using this field.]
The content of the message in AMP format.

click_tracking_enabled
boolean
Default: true

Enables links in the email message to be tracked

exclude_lists
string
Default: []

JSON encoded list of Lists URLs to exclude in the delivery of this broadcast.
Use the self_link of the list here - e.g. https://api.aweber.com/1.0/accounts/<account_id>/lists/<list_id>. If updated, this value will replace the existing excluded_lists.

include_lists
string
Default: []

JSON encoded list of Lists URLs to include in the delivery of this broadcast.
Use the self_link of the list here - e.g. https://api.aweber.com/1.0/accounts/<account_id>/lists/<list_id>. If updated, this value will replace the existing included_lists.

facebook_integration
string <uri>

URL to the Facebook broadcast integration to use for this broadcast. When the broadcast is sent, the subject of the broadcast will be posted to this Facebook integration - e.g., https://api.aweber.com/1.0/accounts/<account_id>/integrations/<integration_id>

is_archived
boolean
Default: true

Whether the broadcast enabled sharing via an archive url

notify_on_send
boolean
Default: true

If true, notify when stats are available on a sent broadcast message

segment_link
any

URL to the Segment to send this broadcast to. Use the self_link of the segment here - e.g. https://api.aweber.com/1.0/accounts/<account_id>/lists/<list_id>/segments/<segment_id>. If not specified, the broadcast will be sent to the “Active Subscribers” segment.

subject
required
string <= 120

The broadcast subject line. Subject must not be empty nor contain only whitespace.

twitter_integration
string <uri>

URL to the Twitter broadcast integration to use for this broadcast. When the broadcast is sent, the subject of the broadcast will be tweeted - e.g., https://api.aweber.com/1.0/accounts/<account_id>/integrations/<integration_id>

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

410

The request has been blocked

415

The enclosed body has a media type that is not application/x-www-form-urlencoded

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X POST \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts \
  --data-urlencode 'body_html=<html><h1>title</h1><body>message body.</body></html>' \
  --data-urlencode 'body_text=this is the content of my message' \
  --data-urlencode 'click_tracking_enabled=True' \
  --data-urlencode 'exclude_lists=["https://api.aweber.com/1.0/accounts/123/lists/456"]' \
  --data-urlencode 'facebook_integration=https://api.aweber.com/1.0/accounts/123/integrations/1' \
  --data-urlencode 'include_lists=["https://api.aweber.com/1.0/accounts/123/lists/456"]' \
  --data-urlencode 'is_archived=True' \
  --data-urlencode 'notify_on_send=True' \
  --data-urlencode 'subject=weekly recipes' \
  --data-urlencode 'twitter_integration=https://api.aweber.com/1.0/accounts/123/integrations/2' \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get broadcast

get /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}

This endpoint is used to retrieve a broadcast message.

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Update broadcast

put /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}

This endpoint is used to replace existing details of a broadcast message in a draft state. (Please be aware that only broadcast drafts created by the API are available to update)

Check out related examples:

Authorizations:
OAuth 2.0 (email.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

Request Body schema: application/x-www-form-urlencoded

Request Body

body_html
string <html>

The content of the message in html format. If body_text is not provided, it will be auto-generated.

body_text
string

The content of the message in plain text, used when HTML is not supported. If body_html is not provided, the broadcast will be sent using only the body_text.

body_amp
string <amp>

[Please read our KB article before using this field.]
The content of the message in AMP format.

click_tracking_enabled
boolean

Enables links in the email message to be tracked.

exclude_lists
string
Default: []

JSON encoded list of Lists URLs to exclude in the delivery of this broadcast.
Use the self_link of the list here - e.g. https://api.aweber.com/1.0/accounts/<account_id>/lists/<list_id>. If updated, this value will replace the existing excluded_lists.

include_lists
string
Default: []

JSON encoded list of Lists URLs to include in the delivery of this broadcast.
Use the self_link of the list here - e.g. https://api.aweber.com/1.0/accounts/<account_id>/lists/<list_id>. If updated, this value will replace the existing included_lists.

facebook_integration
string <uri>

URL to the Facebook broadcast integration to use for this broadcast. When the broadcast is sent, the subject of the broadcast will be posted to this Facebook integration - e.g., https://api.aweber.com/1.0/accounts/<account_id>/integrations/<integration_id>

is_archived
boolean

Whether the broadcast enabled sharing via an archive url.

notify_on_send
boolean

If true, notify when stats are available on a sent broadcast message, defaults to true.

subject
string <= 120

The broadcast subject line. Subject must not be empty nor contain only whitespace.

twitter_integration
string <uri>

URL to the Twitter broadcast integration to use for this broadcast. When the broadcast is sent, the subject of the broadcast will be tweeted - e.g., https://api.aweber.com/1.0/accounts/<account_id>/integrations/<integration_id>

segment_link
string <url>

URL to the Segment to send this broadcast to. Use the self_link of the segment here - e.g. https://api.aweber.com/1.0/accounts/<account_id>/lists/<list_id>/segments/<segment_id>. If not specified, the broadcast will be sent to the “Active Subscribers” segment.

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

409

The request could not be completed due to a conflict with the current state of the target resource

410

The request has been blocked

415

The enclosed body has a media type that is not application/x-www-form-urlencoded

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X PUT \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \
  --data-urlencode 'body_html=<html><h1>title</h1><body>message body.</body></html>' \
  --data-urlencode 'body_text=this is the content of my message' \
  --data-urlencode 'click_tracking_enabled=True' \
  --data-urlencode 'exclude_lists=["https://api.aweber.com/1.0/accounts/123/lists/456"]' \
  --data-urlencode 'facebook_integration=https://api.aweber.com/1.0/accounts/123/integrations/1' \
  --data-urlencode 'include_lists=["https://api.aweber.com/1.0/accounts/123/lists/456"]' \
  --data-urlencode 'is_archived=True' \
  --data-urlencode 'notify_on_send=True' \
  --data-urlencode 'subject=weekly recipes' \
  --data-urlencode 'twitter_integration=https://api.aweber.com/1.0/accounts/123/integrations/2' \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Delete broadcast

delete /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}

This endpoint is used to delete a broadcast message draft. (Please be aware that only drafts created the API are able to be deleted)

Check out related examples:

Authorizations:
OAuth 2.0 (email.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

Responses

204

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

409

The request could not be completed due to a conflict with the current state of the target resource

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X DELETE \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Cancel scheduled broadcast

post /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/cancel
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/cancel

This endpoint is used to cancel a currently scheduled broadcast.

Check out related examples:

Authorizations:
OAuth 2.0 (email.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

409

The request could not be completed due to a conflict with the current state of the target resource

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X POST \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/cancel \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all

Get total broadcasts

get /accounts/{accountId}/lists/{listId}/broadcasts/total
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/total

This endpoint is used to get the total number of broadcasts in a particular state.

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
status
required
string
Enum: "draft" "scheduled" "sent"

The status of the broadcasts to retrieve. (Please be aware that draft only returns API created Broadcast drafts)

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/total \
  -d status=sent \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "total_size": 4
}

Schedule broadcast

post /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/schedule
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/schedule

This endpoint is used to schedule a broadcast.

Check out related examples:

Authorizations:
OAuth 2.0 (email.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

Request Body schema: application/x-www-form-urlencoded

Request Body

scheduled_for
required
string <date-time>

Scheduled time for sending broadcast message, ISO-8601 formatted.

Responses

200

The broadcast successfully scheduled

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

409

The request could not be completed due to a conflict with the current state of the target resource

410

The request has been blocked

415

The enclosed body has a media type that is not application/x-www-form-urlencoded

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X POST \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/schedule \
  -d scheduled_for=2022-11-11T00:00:00Z \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all

Get broadcast opens

get /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/opens
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/opens

This endpoint is used to retrieve a broadcast message's unique opens. If a subscriber has opened several times, the first open record will be returned for the subscriber. The subscriber's email address will only be returned if the token has the subscriber.read scope.

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

query Parameters
before
string

The pagination key when paging in reverse. Cannot be combined with after.

after
string

The pagination key when paging forward. Cannot be combined with before.

page_size
integer [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/opens \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json

Get broadcast clicks

get /accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/clicks
/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/clicks

This endpoint is used to retrieve a broadcast message's unique clicks. If a subscriber has clicked several times, the first click record will be returned for the subscriber. The subscriber's email address will only be returned if the token has the subscriber.read scope.

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

broadcastId
required
integer <int32>

The broadcast ID

query Parameters
before
string

The pagination key when paging in reverse. Cannot be combined with after.

after
string

The pagination key when paging forward. Cannot be combined with before.

page_size
integer [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Manage Email permission

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/clicks \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json

Campaigns

What is it?

Represents followup and broadcast messages associated with a list.

The Campaigns email automation platform within the AWeber web platform is not currently supported by the AWeber API.

Use this set of resources to retrieve information and statistics for messages on a list by type of message (e.g., followup or broadcast). The collection responses are sorted based on message type and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal and the individual endpoints for sorting characteristics.

Get campaigns

get /accounts/{accountId}/lists/{listId}/campaigns
/1.0/accounts/{accountId}/lists/{listId}/campaigns

The collection of followup ("f") or broadcast ("b") campaigns for the list. The collection is ordered with followups messages followed by broadcast messages. The followup messages are sorted by id ascending and the broadcast messages are sorted by sent_at descending.

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaignss \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get campaign

get /accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}
/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}

A followup or broadcast campaign

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignType
required
string
Enum: "b" "f"

The campaign type (b - broadcast, f - followup)

campaignId
required
integer <int32>

The campaign ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Find campaigns

get /accounts/{accountId}/lists/{listId}/campaigns?ws.op=find
/1.0/accounts/{accountId}/lists/{listId}/campaigns?ws.op=find

Find a collection of either followup("f") or broadcast("b") Campaigns. The collection is ordered with followups messages followed by broadcast messages. The followup messages are sorted by id ascending and the broadcast messages are sorted by sent_at descending.

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.op
string
Value: "find"

The method name - expecting "find"

campaign_type
required
string
Enum: "b" "f"

The campaign type (b - broadcast, f - followup)

ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

ws.show
string
Value: "total_size"

A flag to show the total size only - expecting "total_size", when added the response will be an integer

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns \
  -d ws.op=find \
  -d campaign_type=b \
  -d ws.start=0 \
  -d ws.size=100 \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get links

get /accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links
/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links

A paginated collection of Links in a followup or broadcast campaign sorted by link id.

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignType
required
string
Enum: "b" "f"

The campaign type (b - broadcast, f - followup)

campaignId
required
integer <int32>

The campaign ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all

Get link

get /accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}
/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}

A link in a followup or broadcast campaign

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignType
required
string
Enum: "b" "f"

The campaign type (b - broadcast, f - followup)

campaignId
required
integer <int32>

The campaign ID

linkId
required
integer <int32>

The link ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get clicks

get /accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks
/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks

A paginated collection of link clicks in a followup or broadcast campaign sorted by link id.

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignType
required
string
Enum: "b" "f"

The campaign type (b - broadcast, f - followup)

campaignId
required
integer <int32>

The campaign ID

linkId
required
integer <int32>

The link ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all

Get click

get /accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks/{clickId}
/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks/{clickId}

A non-unique click on a link in a followup or broadcast campaign

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignType
required
string
Enum: "b" "f"

The campaign type (b - broadcast, f - followup)

campaignId
required
integer <int32>

The campaign ID

linkId
required
integer <int32>

The link ID

clickId
required
integer <int32>

The click ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks/{clickId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get broadcast statistics

get /accounts/{accountId}/lists/{listId}/campaigns/b{campaignId}/stats
/1.0/accounts/{accountId}/lists/{listId}/campaigns/b{campaignId}/stats

A paginated collection of statistics for a broadcast campaign message sorted by "statistics ID"

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignId
required
integer <int32>

The campaign ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/b{campaignId}/stats \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get broadcast statistic

get /accounts/{accountId}/lists/{listId}/campaigns/b{campaignId}/stats/{statsId}
/1.0/accounts/{accountId}/lists/{listId}/campaigns/b{campaignId}/stats/{statsId}

A statistic for a broadcast campaign message

Check out related examples:

Authorizations:
OAuth 2.0 (email.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

campaignId
required
integer <int32>

The campaign ID

statsId
required
string
Enum: "total_clicks" "unique_clicks" "total_opens" "unique_opens" "total_sales" "total_sales_dollars" "total_unsubscribed" "hourly_opens" "hourly_clicks" "hourly_webhits" "hourly_sales" "hourly_unsubscribed" "daily_opens" "daily_clicks" "daily_webhits" "daily_sales" "daily_unsubscribed" "clicks_by_link" "webhits_by_link" "opens_by_subscriber" "sales_by_subscriber"

The statistic's ID.

The datatype of the ID may be different for each Stat.

Below is a list of the statistic IDs that can be passed in.

Aggregate Statistics

Stat ID Description
total_clicks Total number of times a subscriber clicked any link appearing in your campaign except the unsubscribe link (includes multiple clicks of the same link)
unique_clicks Total number of subscribers who clicked any link in your campaign
total_opens Total number of times your campaign was opened by any subscriber your campaign was sent to (including multiple opens by the same subscriber)
unique_opens Total number of subscribers who opened your campaign
total_sales Total number of sales made by subscribers who received your campaign
total_sales_dollars Total monetary value of sales made by subscribers who received your campaign
total_unsubscribed Total number of subscribers who unsubscribed by clicking the unsubscribe link in your campaign

Time Related Statistics

Stat ID Description
hourly_clicks Hourly breakdown of unique and total clicks for the first 24 hours after a campaign was sent
hourly_opens Hourly breakdown of unique and total opens for the first 24 hours after a campaign was sent
hourly_sales Hourly breakdown of sales for the first 24 hours after a campaign was sent
hourly_unsubscribed Hourly breakdown of subscribers who unsubscribed by clicking the unsubscribed link for the first 24 hours after a campaign was sent
hourly_webhits Hourly breakdown of webhits to your website from subscribers sent this message for the first 24 hours after a campaign was sent
daily_clicks Daily breakdown of unique and total clicks for the first 14 days after a campaign was sent
daily_opens Daily breakdown of unique and total opens for the first 14 days after a campaign was sent
daily_sales Daily breakdown of sales for the first 14 days after a campaign was sent
daily_unsubscribed Daily breakdown of subscribers who unsuscribed by clicking the unsubscribed link for the first 14 days after a campaign was sent
daily_webhits Daily breakdown of webhits to your website from subscribers sent this message for the first 14 days after a campaign was sent

Top 10 URL Statistics

Stat ID Description
clicks_by_link Top 10 links that were clicked (ranked by total_clicked)
webhits_by_link Top 10 webhits by click (ranked by total clicks)

Top 10 Subscriber Statistics (Requires access to subscriber data)

Stat ID Description
opens_by_subscriber Top 10 subscribers that opened your message (ranked by total opens)
sales_by_subscriber Top 10 subscribers that made a sale from your message (ranked by total sales dollars)

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/stats/{statsId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Custom Fields

What is it?

Represents the custom fields associated with a list.

Use this set of resources to retrieve, create, modify, and delete the custom fields that are defined for subscribers on the list. The single collection response is sorted by the generated custom field id and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal.

Warning about modifying Custom Fields

Modifying or deleting a custom field has a number of side-effects that need to be understood BEFORE you change them. See Why could changing my custom field names cause problems for more details.

Get custom fields

get /accounts/{accountId}/lists/{listId}/custom_fields
/1.0/accounts/{accountId}/lists/{listId}/custom_fields

This endpoint is used to get a paginated collection of custom fields under the specified account and list

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/custom_fields \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Add custom field

post /accounts/{accountId}/lists/{listId}/custom_fields
/1.0/accounts/{accountId}/lists/{listId}/custom_fields

This endpoint is used to add a new custom field to the specified account and list.

Check out related examples:

Authorizations:
OAuth 2.0 (list.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

Request Body schema:

Request Body

name
required
string

The name of the custom field

ws.op
required
string
Value: "create"

The method name - expecting "create"

Responses

201

The custom field was created successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The maximum number of custom fields has been exceeded

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "Favorite color",
  • "ws.op": "create"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get custom field

get /accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId}
/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId}

This endpoint is used to retrieve the information for the specified custom field.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

customFieldId
required
integer <int32>

The custom field ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Update custom field

patch /accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId}
/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId}

This endpoint is used to update the information for the specified custom field. See Why could changing my custom field names cause problems before changing the name of a Custom Field.

Check out related examples:

Authorizations:
OAuth 2.0 (list.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

customFieldId
required
integer <int32>

The custom field ID

Request Body schema:

Request Body

name
string

The name of the custom field

is_subscriber_updateable
boolean

Whether the subscriber is allowed to update the custom field

Responses

209

The custom field was updated successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "Favorite color",
  • "is_subscriber_updateable": true
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Delete custom field

delete /accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId}
/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId}

This endpoint is used to delete a custom field entry See Why could changing my custom field names cause problems before removing a Custom Field.

Check out related examples:

Authorizations:
OAuth 2.0 (list.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

customFieldId
required
integer <int32>

The custom field ID

Responses

200

The custom field was deleted successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X DELETE \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Integrations

What is it?

Represents the 3rd Party Services that are integrated with the AWeber Customer Account.

Use this set of resources to retrieve the integrations that are available for use when creating broadcasts. For example, use the integration self_link as a parameter when creating a broadcast to cross-post to Twitter and Facebook when a broadcast is sent. The integrations returned include Facebook, Twitter, PayPal and Shopify, if connected.

The collection response is sorted by the generated integration id and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal.

Get integrations

get /accounts/{accountId}/integrations
/1.0/accounts/{accountId}/integrations

This endpoint is used to get a paginated collection of integrations. The integrations returned include Facebook, Twitter, PayPal and Shopify, if connected. The integrations are typically used when creating a broadcast and cross-posting the broadcast to Twitter or Facebook, the integration self_link is needed in this case.

Check out related examples:

Authorizations:
OAuth 2.0 (account.read)
path Parameters
accountId
required
integer <int32>

The account ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/integrations \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get integration

get /accounts/{accountId}/integrations/{integrationId}
/1.0/accounts/{accountId}/integrations/{integrationId}

This endpoint is used to retrieve the information for a specific connected integration. A specific integration will be Facebook, Twitter, PayPal or Shopify. The integration is typically used when creating a broadcast and cross-posting the broadcast to Twitter or Facebook, the integration self_link is needed in this case.

Check out related examples:

Authorizations:
OAuth 2.0 (account.read)
path Parameters
accountId
required
integer <int32>

The account ID

integrationId
required
integer <int32>

The integration ID

Responses

200

The request completed successfully

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/integrations/{integrationId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Landing Pages

What is it?

Represents the landing pages associated with a list.

Use this resource to retrieve the landing pages that are defined for the list. The single collection response is sorted by the generated landing page id and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal.

Get landing pages

get /accounts/{accountId}/lists/{listId}/landing_pages
/1.0/accounts/{accountId}/lists/{listId}/landing_pages

This endpoint is used to get a paginated collection of list landing pages.

Authorizations:
OAuth 2.0 (landing-page.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/landing_pages \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get landing page

get /accounts/{accountId}/lists/{listId}/landing_pages/{landingPageId}
/1.0/accounts/{accountId}/lists/{listId}/landing_pages/{landingPageId}

This endpoint is used to retrieve the information for the specified landing page.

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

landingPageId
required
string <uuid>

The landing page ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/landing_pages/{landingPageId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Lists

What is it?

Represents the individual subscriber lists within the AWeber Customer Account.

Use this set of resources to retrieve the available lists and information about each list. The list collection response is sorted by the generated list id and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal.

Get lists

get /accounts/{accountId}/lists
/1.0/accounts/{accountId}/lists

This endpoint is used to get a paginated collection of subscriber lists.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get list

get /accounts/{accountId}/lists/{listId}
/1.0/accounts/{accountId}/lists/{listId}

This endpoint is used to retrieve the information for a specific subscriber list.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Find lists

get /accounts/{accountId}/lists?ws.op=find
/1.0/accounts/{accountId}/lists?ws.op=find

This endpoint is used to search for lists when you do not have a link nor know the list ID.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

query Parameters
ws.op
required
string
Value: "find"

The method name - expecting "find"

name
string [ 1 .. 100 ] characters

Name or unique list ID of the list

ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

ws.show
string
Value: "total_size"

A flag to show the total size only - expecting "total_size", when added the response will be an integer

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists \
  -d ws.op=find \
  --data-urlencode "name=Weekly Newsletter" \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get tags for list

get /accounts/{accountId}/lists/{listId}/tags
/1.0/accounts/{accountId}/lists/{listId}/tags

Get the most popular tags for a list. This will return an array containing up to 500 tags sorted by descending popularity.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/tags \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • "alpha",
  • "beta",
  • "gamma"
]

Segments

What is it?

Represents the segments associated with a list.

Use this resource to retrieve the segments that are defined for the list. The single collection response is sorted by the generated segment id and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal.

Get segments

get /accounts/{accountId}/lists/{listId}/segments
/1.0/accounts/{accountId}/lists/{listId}/segments

This endpoint is used to get a paginated collection of list segments.

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/segments \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get segment

get /accounts/{accountId}/lists/{listId}/segments/{segmentId}
/1.0/accounts/{accountId}/lists/{listId}/segments/{segmentId}

This endpoint is used to retrieve the information for the specified segment.

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

segmentId
required
integer <int32>

The segment ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/segments/{segmentId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Subscribers

What is it?

Represents a collection of subscribers.

Use this set of resources to add, remove, find, and update an AWeber Customer Account's subscribers. The collection responses are ordered and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal and the individual endpoint descriptions for ordering constraints. Many of the subscriber-related endpoints support the sort_order query parameter to control the sorting direction in the response collection.

Subscribers are one of the most important elements in the AWeber API so care must be taken before adding a subscriber to a list. Read more about adding subscribers in AWeber Knowledge Base article "Can I use this list?".

Although not required, it's strongly recommended that you provide the IP address of the Subscriber if it is known. For web based Apps, the ip_address that you should use is the REMOTE_ADDRESS of their requests to your App server, not the server's IP address. The IP address is used in the Geo Location parameters and for send windows in the AWeber Control Panel. The IP address can only be specified when ADDING a new subscriber.

Get subscribers

get /accounts/{accountId}/lists/{listId}/subscribers
/1.0/accounts/{accountId}/lists/{listId}/subscribers

This endpoint is used to get a paginated collection of subscribers under the specified account and list. The subscribers are returned in the order that they were added to the list starting with the oldest subscriber. The order can be changed using the sort_order query parameter. Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

sort_order
string
Default: "asc"
Enum: "asc" "desc"

The collection will be sorted by the order in which the subscribers were added to the list. To specify the order, use the value asc for ascending or desc for descending.

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Add subscriber

post /accounts/{accountId}/lists/{listId}/subscribers
/1.0/accounts/{accountId}/lists/{listId}/subscribers

This endpoint is used to add subscribers to the specified account and list. Before adding a subscriber to a list, read Can I use this list? to understand the ramifications. If you have a large list of subscribers, please use our list importer. Attempting to use the endpoint to bulk add subscribers is considered abuse which violates our Terms of Service.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

Request Body schema:

Request body to add a subscriber

ad_tracking
string [ 1 .. 20 ] characters

The customer ad tracking field

custom_fields
object

The custom fields specified on the subscriber. Note that the custom fields are required to already exist for the list. See Custom Fields for details.

email
required
string <email> [ 1 .. 50 ] characters

The subscriber's email address

ip_address
string <ipv4> [ 1 .. 60 ] characters

The subscriber's IP address. This field is used to determine the following Geo Location fields: area_code, city, country, dma_code, latitude, longitude, postal_code, and region. IP address can only be specified when Subscribers are initially created. Internal, private, or reserved IP addresses are not acceptable.

last_followup_message_number_sent
integer [ 0 .. 1001 ]

The sequence number of the last followup message sent to the subscriber. This field determines the next followup message to be sent to the Subscriber. When set to 0 (default), the Subscriber should receive the 1st (autoresponse) Followup message. Set the value of this field to 1001 if you do not want any Followups to be sent to this Subscriber.

misc_notes
string [ 1 .. 60 ] characters

Miscellaneous notes

name
string [ 1 .. 60 ] characters

The subscriber's name

strict_custom_fields
string
Enum: "true" "false"

If this parameter is present and set to true, then custom field names are matched case sensitively. Enabling this option also causes the operation to fail if a custom field is included that is not defined for the list.

update_existing
string
Enum: "true" "false"

If this parameter is present and set to true, then if a subscriber is already present on the list, the subscriber will be updated.

Note:

  • Only the fields defined in the patch endpoint will be updated.
  • Any tags in the request will be appended to the existing Subscriber.
tags
Array of strings

A list of tags added to the subscriber. This field is used to apply a list of tags to a Subscriber. With Campaigns, you can trigger a series of messages based on what Tags have been applied to your subscribers.

Responses

201

The subscriber was created successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error, due to account being on hold, or because the subscriber limit has been reached.

404

The requested list could not be found

410

The request has been blocked

415

The request entity has a media type that is not application/x-www-form-urlencoded or application/json

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
Copy
Expand all Collapse all
{
  • "ad_tracking": "ebook",
  • "custom_fields":
    {
    },
  • "email": "[email protected]",
  • "ip_address": "192.168.0.1",
  • "last_followup_message_number_sent": 0,
  • "misc_notes": "string",
  • "name": "John Doe",
  • "strict_custom_fields": "true",
  • "update_existing": "true",
  • "tags":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Update subscriber by email

patch /accounts/{accountId}/lists/{listId}/subscribers
/1.0/accounts/{accountId}/lists/{listId}/subscribers

This endpoint is used to update the information for the specified subscriber by email.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
subscriber_email
required
string <email> [ 1 .. 50 ] characters

The subscriber's email address

Request Body schema:

Request body to update a subscriber

ad_tracking
string [ 1 .. 20 ] characters

The customer ad tracking field

custom_fields
object

The custom fields specified on the subscriber. Custom fields are represented as a sub-object where only the values can be modified.

Note: If updating custom field values, all fields must be included in the request. If all fields are not included, the omitted fields will be set to null.

In order to modify custom field values:

  • Retrieve the custom fields and values for the subscriber.
  • Add all fields and their values to the PATCH request.
  • Modify the value only for the fields you wish to update.
  • Submit the request containing all the custom fields and their respective values.
email
string <email> <= 50

The subscriber's email address

last_followup_message_number_sent
integer [ 0 .. 1001 ]

The sequence number of the last followup message sent to the subscriber. This field determines the next followup message to be sent to the Subscriber. When set to 0, the Subscriber will receive the 1st (autoresponse) Followup message. Set the value of this field to 1001 if you do not want any Followups to be sent to this Subscriber.

misc_notes
string

Miscellaneous notes

name
string [ 1 .. 60 ] characters

The subscriber's name

status
string
Enum: "subscribed" "unsubscribed"

The subscriber's status.
Note you cannot set a subscriber's status to "unconfirmed".

strict_custom_fields
string
Enum: "true" "false"

If this parameter is present and set to true, then custom field names are matched case sensitively. Enabling this option also causes the operation to fail if a custom field is included that is not defined for the list.

tags
object

An object with the keys "add" and/or "remove" and values of lists of tags

Responses

209

The subscriber was updated successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

415

The request entity has a media type that is not application/x-www-form-urlencoded or application/json

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
Copy
Expand all Collapse all
{
  • "ad_tracking": "ebook",
  • "custom_fields":
    {
    },
  • "email": "[email protected]",
  • "last_followup_message_number_sent": 0,
  • "misc_notes": "Open House 2015",
  • "name": "John Doe",
  • "status": "subscribed",
  • "strict_custom_fields": "true",
  • "tags":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Delete subscriber by email

delete /accounts/{accountId}/lists/{listId}/subscribers
/1.0/accounts/{accountId}/lists/{listId}/subscribers

This endpoint is used to delete a subscriber and related information by the subscriber's email.

If you just want to unsubscribe the subscriber, then make a PATCH request to set the status to "unsubscribed" instead. When a subscriber is DELETED, the subscriber is unsubscribed from the list and all related analytics activity is removed from the customer account for the subscriber. Any references to clicks or opens are shown as "Deleted Subscriber" afterwards.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
subscriber_email
required
string <email> [ 1 .. 50 ] characters

The subscriber's email address

Responses

200

The subscriber was deleted successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested subscriber resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X DELETE \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers \
  -d '[email protected]'
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Update subscriber by ID

patch /accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}
/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}

This endpoint is used to update the information for the specified subscriber by ID

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

subscriberId
required
integer <int32>

The subscriber ID

Request Body schema:

Request body to update a subscriber

ad_tracking
string [ 1 .. 20 ] characters

The customer ad tracking field

custom_fields
object

The custom fields specified on the subscriber. Custom fields are represented as a sub-object where only the values can be modified.

Note: If updating custom field values, all fields must be included in the request. If all fields are not included, the omitted fields will be set to null.

In order to modify custom field values:

  • Retrieve the custom fields and values for the subscriber.
  • Add all fields and their values to the PATCH request.
  • Modify the value only for the fields you wish to update.
  • Submit the request containing all the custom fields and their respective values.
email
string <email> <= 50

The subscriber's email address

last_followup_message_number_sent
integer [ 0 .. 1001 ]

The sequence number of the last followup message sent to the subscriber. This field determines the next followup message to be sent to the Subscriber. When set to 0, the Subscriber will receive the 1st (autoresponse) Followup message. Set the value of this field to 1001 if you do not want any Followups to be sent to this Subscriber.

misc_notes
string

Miscellaneous notes

name
string [ 1 .. 60 ] characters

The subscriber's name

status
string
Enum: "subscribed" "unsubscribed"

The subscriber's status.
Note you cannot set a subscriber's status to "unconfirmed".

strict_custom_fields
string
Enum: "true" "false"

If this parameter is present and set to true, then custom field names are matched case sensitively. Enabling this option also causes the operation to fail if a custom field is included that is not defined for the list.

tags
object

An object with the keys "add" and/or "remove" and values of lists of tags

Responses

209

The subscriber was updated successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

415

The request entity has a media type that is not application/x-www-form-urlencoded or application/json

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
Copy
Expand all Collapse all
{
  • "ad_tracking": "ebook",
  • "custom_fields":
    {
    },
  • "email": "[email protected]",
  • "last_followup_message_number_sent": 0,
  • "misc_notes": "Open House 2015",
  • "name": "John Doe",
  • "status": "subscribed",
  • "strict_custom_fields": "true",
  • "tags":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Delete subscriber by ID

delete /accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}
/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}

This endpoint is used to delete a subscriber and related information by the subscriber's ID.

If you just want to unsubscribe the subscriber, then make a PATCH request to set the status to "unsubscribed" instead. When a subscriber is DELETED, the subscriber is unsubscribed from the list and all related analytics activity is removed from the customer account for the subscriber. Any references to clicks or opens are shown as "Deleted Subscriber" afterwards.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

subscriberId
required
integer <int32>

The subscriber ID

Responses

200

The subscriber was deleted successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested subscriber resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X DELETE \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get subscriber

get /accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}
/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}

This endpoint is used to retrieve the information for the specified subscriber. Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

subscriberId
required
integer <int32>

The subscriber ID

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Move subscriber

post /accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}
/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}

This endpoint is used to move a subscriber from one list to another on the specified account. The subscriber will be unsubscribed from the original list and subscribed to the destination list without sending a verification message. By default, the subscriber will be set to the beginning of the followup sequence on the destination list. You can explicitly set the position in the followup list by specifying the last_followup_message_number_sent body parameter.

If either the source or destination list has custom fields defined, read our Knowledge Base article.

Requirements

  • the subscriber MUST have a status of "subscribed"
  • the destination list MUST be owned by the same account as the source list

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

subscriberId
required
integer <int32>

The subscriber ID

Request Body schema: application/x-www-form-urlencoded

Request body to move subscriber

enforce_custom_field_mapping
boolean <bool>

If set to true, this will cause the move of a subscriber to fail if the custom fields from the origin list do not match (case insensitively) to the target list

last_followup_message_number_sent
integer [ 0 .. 1001 ]

The sequence number of the last followup message sent to the subscriber. This field determines the next followup message to be sent to the Subscriber. When set to 0, the Subscriber will receive the 1st (autoresponse) Followup message. Set the value of this field to 1001 if you do not want any Followups to be sent to this Subscriber.

list_link
required
string <uri>

The link to the destination List

ws.op
required
string
Value: "move"

The method name - expecting "move"

Responses

201

The subscriber was moved successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

A request method is not supported for the requested resource

410

The request has been blocked

415

The request entity has a media type that is not application/x-www-form-urlencoded or application/json

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -X POST \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \
  -d ws.op=move \
  -d enforce_custom_field_mapping=true \
  -d last_followup_message_number_sent=0 \
  -d list_link=https://api.aweber.com/1.0/accounts/123/lists/456 \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Find subscribers for list

get /accounts/{accountId}/lists/{listId}/subscribers?ws.op=find
/1.0/accounts/{accountId}/lists/{listId}/subscribers?ws.op=find

This endpoint is used to find the collection of subscribers that match a search criteria for the specified account and list.

  • All parameters match on the full value and are case sensitive. (Partial matches are NOT supported)

  • For Date parameters, include the date as 'YYYY-MM-DD' or 'MM-DD-YYYY' and any subscriber matching the query will be returned.

  • Date parameters are entered as single days, but may search multiple days depending on the parameter. For example: subscribed_at=2017-07-16 or subscribed_before=2018-12-25

  • Values that are empty (or empty string) are treated the same as if they were omitted entirely.

The subscribers are returned in the order that they were added to the list starting with the oldest subscriber first. This order can be changed using the sort_order query parameter.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.op
required
string
Value: "find"

The method name - expecting "find"

ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

ws.show
string
Value: "total_size"

A flag to show the total size only - expecting "total_size", when added the response will be an integer

sort_key
string
Enum: "subscribed_at" "unsubscribed_at"

The collection will be sorted by the field key specified. If no key is spcified the search will default to the order in which the subscribers were added to the list.

sort_order
string
Default: "asc"
Enum: "asc" "desc"

The collection will be sorted in the order specified by the key entered for sort_key. To specify the order, use the value asc for ascending or desc for descending.

ad_tracking
string [ 1 .. 20 ] characters
Example: ad_tracking=ebook

The customer ad tracking field

area_code
integer <int32> [ 0 .. 999 ]
Example: area_code=555

The subscriber's area code

city
string [ 1 .. 100 ] characters
Example: city=Chalfont

The subscriber's city

country
string [ 1 .. 100 ] characters
Example: country=United States

The subscriber's country

custom_fields
string
Example: custom_fields={"apple": "fuji", "pear": "bosc"}

The JSON encoded custom field key value pairs

dma_code
integer <int32> <= 881
Example: dma_code=504

The subscriber's designated market area code (usa and canada only)

email
string <email> [ 1 .. 50 ] characters

The subscriber's email address

last_followup_message_number_sent
integer <int32> <= 1001

The sequence number of the last followup message sent to the subscriber

last_followup_message_sent_at
string <date> [ 1 .. 10 ] characters
Example: last_followup_message_sent_at=2017-11-28

The day when the last followup message was sent to the subscriber

latitude
number <double> [ -90 .. 90 ]
Example: latitude=37.751

The subscriber's geographical latitude

longitude
number <double> [ -180 .. 180 ]
Example: longitude=-97.822

The subscriber's geographical longitude

misc_notes
string <= 60 characters
Example: misc_notes=ebook

Miscellaneous notes

name
string [ 1 .. 60 ] characters
Example: name=John Doe

The subscriber's name

postal_code
string [ 1 .. 100 ] characters
Example: postal_code=99999-9999

The subscriber's postal or zip code

region
string [ 1 .. 100 ] characters
Example: region=PA

The subscriber's state or region abbreviation

status
string
Enum: "subscribed" "unsubscribed" "unconfirmed"

The subscriber's status

subscribed_before
string <date>
Example: subscribed_before=2017-07-16

The day on or before the subscriber subscribed

subscribed_after
string <date>
Example: subscribed_after=2017-07-16

The day on or after the subscriber subscribed

subscribed_at
string <date>
Example: subscribed_at=2017-07-16

The day in which the subscriber subscribed

subscription_method
string
Enum: "api" "email" "import" "webform"

How the subscriber was subscribed

tags
string
Example: tags=["tag1", "tag2"]

A string containing a JSON-formatted array of tags. All tags must match for the subscriber to match.

tags_not_in
string
Example: tags_not_in=["tag1", "tag2"]

A string containing a JSON-formatted array of tags. Checks that all tags are not matched to a subscriber.

unsubscribe_method
string
Enum: "unsubscribe link" "customer cp" "undeliverable" "api: unsubscribe" "api: move"

How the subscriber unsubscribed

unsubscribed_before
string <date>
Example: unsubscribed_before=2017-10-13

The day on or before the subscriber unsubscribed

unsubscribed_after
string <date>
Example: unsubscribed_after=2017-10-13

The day on or after the subscriber unsubscribed

unsubscribed_at
string <date>
Example: unsubscribed_at=2017-10-13

The day in which the subscriber unsubscribed

verified_at
string <date>
Example: verified_at=2017-07-18

The day in which the subscriber confirmed their email address

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Request Subscriber Data permission

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers \
  --data-urlencode 'ws.op=find' \
  --data-urlencode 'ad_tracking=ebook' \
  --data-urlencode 'area_code=555' \
  --data-urlencode 'city=Chalfont' \
  --data-urlencode 'country=United States' \
  --data-urlencode 'custom_fields={"apple": "fuji", "pear": "bosc"}' \
  --data-urlencode 'dma_code=504' \
  --data-urlencode '[email protected]' \
  --data-urlencode 'last_followup_message_number_sent=0' \
  --data-urlencode 'last_followup_message_sent_at=2017-11-28' \
  --data-urlencode 'latitude=37.751' \
  --data-urlencode 'longitude=-97.822' \
  --data-urlencode 'misc_notes=ebook' \
  --data-urlencode 'name=John Doe' \
  --data-urlencode 'postal_code=99999-9999' \
  --data-urlencode 'region=PA' \
  --data-urlencode 'status=unconfirmed' \
  --data-urlencode 'subscribed_at=2017-07-16' \
  --data-urlencode 'subscription_method=api' \
  --data-urlencode 'tags=["fast"]' \
  --data-urlencode 'tags_not_in=["slow"]' \
  --data-urlencode 'unsubscribe_method=api: move' \
  --data-urlencode 'unsubscribed_at=2017-10-13' \
  --data-urlencode 'verified_at=2017-07-18' \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Find subscribers for account

get /accounts/{accountId}?ws.op=findSubscribers
/1.0/accounts/{accountId}?ws.op=findSubscribers

This endpoint is used to find the collection of subscribers that match a search criteria for the specified account across all lists.

  • All parameters match on the full value and are case sensitive. (No partial matches are accepted)

  • For Date parameters, include the date as 'YYYY-MM-DD' or 'MM-DD-YYYY' and any subscriber matching the query will be returned.

  • Date parameters are entered as single days, but may search multiple days depending on the parameter. For example: subscribed_at=2017-07-16 or subscribed_before=2018-12-25

  • Values that are empty (or empty string) are treated the same as if they were omitted entirely.

  • If no search parameters are included, all subscribers from all lists will be returned.

The subscribers are returned in the order that they were added to the list starting with the oldest subscriber first.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.read)
path Parameters
accountId
required
integer <int32>

The account ID

query Parameters
ws.op
required
string
Value: "findSubscribers"

The method name - expecting "findSubscribers"

ad_tracking
string [ 1 .. 20 ] characters
Example: ad_tracking=ebook

The customer ad tracking field

area_code
integer <int32> [ 0 .. 999 ]
Example: area_code=555

The subscriber's area code

city
string [ 1 .. 100 ] characters
Example: city=Chalfont

The subscriber's city

country
string [ 1 .. 100 ] characters
Example: country=United States

The subscriber's country

custom_fields
string
Example: custom_fields={"apple": "fuji", "pear": "bosc"}

The JSON encoded custom field key value pairs

dma_code
integer <int32> <= 881
Example: dma_code=504

The subscriber's designated market area code (usa and canada only)

email
string <email> [ 1 .. 50 ] characters

The subscriber's email address

last_followup_message_number_sent
integer <int32> <= 1001

The sequence number of the last followup message sent to the subscriber

last_followup_message_sent_at
string <date> [ 1 .. 10 ] characters
Example: last_followup_message_sent_at=2017-11-28

The day when the last followup message was sent to the subscriber

latitude
number <double> [ -90 .. 90 ]
Example: latitude=37.751

The subscriber's geographical latitude

longitude
number <double> [ -180 .. 180 ]
Example: longitude=-97.822

The subscriber's geographical longitude

misc_notes
string <= 60 characters
Example: misc_notes=ebook

Miscellaneous notes

name
string [ 1 .. 60 ] characters
Example: name=John Doe

The subscriber's name

postal_code
string [ 1 .. 100 ] characters
Example: postal_code=99999-9999

The subscriber's postal or zip code

region
string [ 1 .. 100 ] characters
Example: region=PA

The subscriber's state or region abbreviation

status
string
Enum: "subscribed" "unsubscribed" "unconfirmed"

The subscriber's status

subscribed_before
string <date>
Example: subscribed_before=2017-07-16

The day on or before the subscriber subscribed

subscribed_after
string <date>
Example: subscribed_after=2017-07-16

The day on or after the subscriber subscribed

subscribed_at
string <date>
Example: subscribed_at=2017-07-16

The day in which the subscriber subscribed

subscription_method
string
Enum: "api" "email" "import" "webform"

How the subscriber was subscribed

tags
string
Example: tags=["tag1", "tag2"]

A string containing a JSON-formatted array of tags. All tags must match for the subscriber to match.

tags_not_in
string
Example: tags_not_in=["tag1", "tag2"]

A string containing a JSON-formatted array of tags. Checks that all tags are not matched to a subscriber.

unsubscribe_method
string
Enum: "unsubscribe link" "customer cp" "undeliverable" "api: unsubscribe" "api: move"

How the subscriber unsubscribed

unsubscribed_before
string <date>
Example: unsubscribed_before=2017-10-13

The day on or before the subscriber unsubscribed

unsubscribed_after
string <date>
Example: unsubscribed_after=2017-10-13

The day on or after the subscriber unsubscribed

unsubscribed_at
string <date>
Example: unsubscribed_at=2017-10-13

The day in which the subscriber unsubscribed

verified_at
string <date>
Example: verified_at=2017-07-18

The day in which the subscriber confirmed their email address

ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

ws.show
string
Value: "total_size"

A flag to show the total size only - expecting "total_size", when added the response will be an integer

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

Forbidden due to rate limit or missing Request Subscriber Data permission

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId} \
  --data-urlencode 'ws.op=findSubscribers' \
  --data-urlencode 'ad_tracking=ebook' \
  --data-urlencode 'area_code=555' \
  --data-urlencode 'city=Chalfont' \
  --data-urlencode 'country=United States' \
  --data-urlencode 'custom_fields={"apple": "fuji", "pear": "bosc"}'
  --data-urlencode 'dma_code=504' \
  --data-urlencode '[email protected]' \
  --data-urlencode 'last_followup_message_number_sent=0' \
  --data-urlencode 'last_followup_message_sent_at=2017-11-28' \
  --data-urlencode 'latitude=37.751' \
  --data-urlencode 'longitude=-97.822' \
  --data-urlencode 'misc_notes=ebook' \
  --data-urlencode 'name=John Doe' \
  --data-urlencode 'postal_code=99999-9999' \
  --data-urlencode 'region=PA' \
  --data-urlencode 'status=unconfirmed' \
  --data-urlencode 'subscribed_at=2017-07-16' \
  --data-urlencode 'subscription_method=api' \
  --data-urlencode 'tags=["fast"]' \
  --data-urlencode 'tags_not_in=["slow"]' \
  --data-urlencode 'unsubscribe_method=api: move' \
  --data-urlencode 'unsubscribed_at=2017-10-13' \
  --data-urlencode 'verified_at=2017-07-18' \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get subscriber activity

get /accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}?ws.op=getActivity
/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId}?ws.op=getActivity

This endpoint is used to retrieve the analytics activity for a subscriber. The activity is returned as a chronological list of events and includes: When they subscribed to the list. When they verified their subscription. What messages were sent to them. When sent messages were opened. When links were clicked (if click tracking was enabled). When a subscriber made a sale or other TrackedEvent. Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

subscriberId
required
integer <int32>

The subscriber ID

query Parameters
ws.op
required
string
Value: "getActivity"

The method name - expecting "getActivity"

ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \
  -d ws.op=getActivity \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Create a purchase

post /accounts/{accountId}/lists/{listId}/purchases
/1.0/accounts/{accountId}/lists/{listId}/purchases

This endpoint creates a purchase (a pageview tracked event) for a subscriber. If the subscriber does not exist, it is created. If the subscriber exists, then it will be updated. This endpoint combines 3 api calls into one, which will account toward the rate limit.

Check out related examples:

Authorizations:
OAuth 2.0 (subscriber.readsubscriber.write)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

Request Body schema: application/json
event_time
required
string

The timestamp of when the event occurred

currency
required
string

Three-letter ISO currency code.

event_note
required
string

A custom note associated with this specific tracked event

product_name
required
string

A custom description for the page or event

value
required
number

The monetary value associated with this tracked event.

vendor
required
string

The sales tracking url profile for the web page

url
required
string

The URL for the tracked event

ad_tracking
string [ 1 .. 20 ] characters

The customer ad tracking field

custom_fields
object

The custom fields specified on the subscriber

email
required
string <email> [ 1 .. 50 ] characters

The subscriber's email address

ip_address
required
string <ipv4> [ 1 .. 60 ] characters

The subscriber's IP address. This must be a public IP address.

misc_notes
string <= 60 characters

Miscellaneous notes

name
string [ 1 .. 60 ] characters

The subscriber's name

tags
Array of strings

A list of tags added to the subscriber

Responses

202

The event was accepted and is being processed.

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

410

The request has been blocked

415

The request entity has a media type that is not application/x-www-form-urlencoded or application/json

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "event_time": "2015-07-31T15:36:34.000Z",
  • "currency": "string",
  • "event_note": "string",
  • "product_name": "string",
  • "value": 0,
  • "vendor": "string",
  • "url": "string",
  • "ad_tracking": "ebook",
  • "custom_fields":
    {
    },
  • "email": "[email protected]",
  • "ip_address": "204.194.222.28",
  • "misc_notes": "ebook",
  • "name": "John Doe",
  • "tags":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Webforms

What is it?

Represents the collection of sign-up forms associated with the AWeber Customer Account's lists.

Webforms are sets of customized HTML and javascript that are used to put up a sign-up forms on a customer's website. The Webform can be modified in the AWeber Control Panel and if you include the javascript source link on any web page, that form will be displayed.

Webforms can also be subject to split-tests to compare conversion effectiveness. Webforms that belong to a split test are listed as components of the split test and can be retrieved by following the components_collection_link of the split test. The statistics of each component include only displays of that Webform where it was displayed from a split test.

Use this set of resources to retrieve information about the available sign-up forms and associated split tests. The collection responses are sorted by the appropriate identifier and paginated using next_collection_link and prev_collection_link properties. See How Collections are Represented for details on collection traversal.

Get webforms for account

get /accounts/{accountId}?ws.op=getWebForms
/1.0/accounts/{accountId}?ws.op=getWebForms

This endpoint is used to retrieve webforms for all lists on an account.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

query Parameters
ws.op
required
string
Value: "getWebForms"

The method name - expecting "getWebForms"

ws.size
required
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

ws.start
required
integer <int32> >= 0
Default: 0

The pagination starting offset

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId} \
  -d ws.op=getWebForms \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get split tests for account

get /accounts/{accountId}?ws.op=getWebFormSplitTests
/1.0/accounts/{accountId}?ws.op=getWebFormSplitTests

This endpoint is used to retrieve webform split tests for all lists on an account.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

query Parameters
ws.op
required
string
Value: "getWebFormSplitTests"

The method name - expecting "getWebFormSplitTests"

ws.size
required
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

ws.start
required
integer <int32> >= 0
Default: 0

The pagination starting offset

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId} \
  -d ws.op=getWebFormSplitTests \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get webforms for list

get /accounts/{accountId}/lists/{listId}/web_forms
/1.0/accounts/{accountId}/lists/{listId}/web_forms

This endpoint is used to retrieve a collection of webforms for a list

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_forms \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get webform for list

get /accounts/{accountId}/lists/{listId}/web_forms/{webformId}
/1.0/accounts/{accountId}/lists/{listId}/web_forms/{webformId}

This endpoint is used to retrieve single webform for a list

Check out related examples:

path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

webformId
required
integer <int32>

The webform ID

Responses

200

The request completed successfully

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_forms/{webformId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get split tests for list

get /accounts/{accountId}/lists/{listId}/web_form_split_tests
/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests

This endpoint is used to retrieve webform split tests for a list.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get split test for list

get /accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}
/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}

This endpoint is used to retrieve a specific webform split test.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

splitTestId
required
integer <int32>

The webform split test ID

Responses

200

The request completed successfully

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get split test components

get /accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components
/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components

This endpoint is used to retrieve a collection of webform split test components.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

splitTestId
required
integer <int32>

The webform split test ID

query Parameters
ws.start
integer <int32> >= 0
Default: 0

The pagination starting offset

ws.size
integer <int32> [ 1 .. 100 ]
Default: 100

The pagination total entries to retrieve

Responses

200

The request completed successfully

400

The server cannot or will not process the request due to a client error

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get split test component

get /accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components/{splitTestComponentId}
/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components/{splitTestComponentId}

This endpoint is used to retrieve a collection of webform split test components.

Check out related examples:

Authorizations:
OAuth 2.0 (list.read)
path Parameters
accountId
required
integer <int32>

The account ID

listId
required
integer <int32>

The list ID

splitTestId
required
integer <int32>

The webform split test ID

splitTestComponentId
required
string

The webform split test component ID

Responses

200

The request completed successfully

401

The request could not be completed due to an authentication error

403

The request could not be completed due to a rate limit error

404

The requested resource could not be found

405

The method received in the request-line is known by the origin server but not supported by the target resource.

410

The request has been blocked

500

The request failed due to an internal error in the code or because of an external dependency failure

503

The server is currently unavailable

Request samples

Copy
curl -G \
  https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components/{splitTestComponentId} \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Webhooks

Getting Started

AWeber offers support for webhooks including subscriber.added, subscriber.subscribed and subscriber.unsubscribed events. The integration will receive notifications when the events occur for each AWeber User Account that is connected. The notifications are sent to a callback URL that is configured by the AWeber User when they connect your integration. You will need to provide the valid patterns for the URLs that your integration will receive notifications on.

When you create or edit an integration, you enable webhooks by:

  1. providing one or more URL prefixes as the Callback URL Allow-list
  2. selecting one or more events to be notified for

The Callback URL Allow-list is the list of exact URL prefixes that can be configured by the AWeber User when they connect their account to your integration. For example, if the "allow list" contains https://example.com/api then customers can use any callback URL that starts with https://example.com/api including https://example.com/api/V1StGXR8_Z5jdHi6B-myT, https://example.com/api/1A2E05D9-741D-4F1C-8937-6DFD984840ED, or even https://example.com/api-unexpected-suffix. You usually want to end "allow list" entries with an explicit / to avoid that last one.

Authorizing Webhooks

To authorize your webhooks-enabled integration, you will need to grant the subscriber.read and account.read permissions from your AWeber User Account. For more information about AWeber OAuth scopes see here.

Open an OAuth 2.0 authorize URL in your browser:

https://auth.aweber.com/oauth2/authorize?client_id={client_id}&scope=subscriber.read%20account.read

Replace {client_id} with the Client ID of your webhooks-enabled integration. The Client ID is available in your AWeber Developer account. The scope parameter may be any valid set of scopes as long as it contains subscriber.read and account.read.

You may continue the OAuth 2.0 flow to retrieve an access token if you need one. More detailed instructions on OAuth 2.0 are available here.

Providing a Callback URL

Once authorized, you must configure the callback URL for your webhooks-enabled integration in the AWeber control panel. This is required to match a prefix in your integration's Callback URL Allow-list.

Open this link in your browser.

You may be prompted to log in with your AWeber User Account (not your AWeber Developer Account).

[My Apps]

Click on your integration in the list of connected integrations.

[My Apps]

Enter the URL to receive webhook requests in the Webhook URL field (1) and press the Save button (2). The URL you entered must match the whitelisted base URL you provided to us when your integration was set up. Your test account should start receiving webhooks at that URL.

If no Webhook URL field is visible, the selected application does not have webhooks enabled.

If the Webhook URL field is disabled, your test user has not authorized webhooks yet. See the Authorizing Webhooks section for more information.

How do I trigger a webhook?

Navigate to the Sign Up Forms screen here. If you aren’t logged in, you will need to provide your AWeber Customer Account credentials. Click the Publish link for the desired sign up form.

[My Apps]

When the Publish screen appears, click on the Use My Form as a Landing Page section. Copy and paste the URL provided into a new window. Complete the fields on the sign up form. This will trigger our subscriber.added webhook outlined further down in this document.

Alternatively: You can add subscribers via our Add Subscriber endpoint in our API.

Verifying Webhook Payloads

Procedure

When you receive a request to your webhook URL, you should first verify that the request came from AWeber. The Verification Key is the key of an HMAC-SHA256 hash of the request's Date header and request body.

The message to hash is constructed by:
rstrip('date:' + date_header_value + '\n' + request_body)

Where:

  • rstrip is a function that removes all space, tab, line feed, carriage return, vertical tab, and form feed characters (0x20, 0x09, 0x0a, 0x0d, 0x0b, and 0x0c) from the end of a string
  • date_header_value is the value of the Date request header
  • request_body is the full HTTP request body

Example

Given this HTTP Request

POST /my-callback HTTP/1.1
AWeber-Delivery-ID: 238D534C-2101-4440-98D7-7404938C3675
AWeber-Signature: sha256=74856469e8a97c0939a8d398460e1ffc83e4e40a46e657c61e9d3723035df10a
Content-Length: 130
Content-Type: application/vnd.aweber.webhook+json; version=1.0
Date: Mon, 21 Oct 2019 19:05:20 GMT


{"account": null
,"client_id": "fKcKvImyD2pQmRDWYSFx92rReytdL4Jh"
,"callback": "5AB10F8A-EC5A-40E8-AF0B-7DC8DF580E55"
,"data": []}

The message to verify would be:

date:Mon, 21 Oct 2019 19:05:20 GMT\n{"account": null\n,"client_id": "fKcKvImyD2pQmRDWYSFx92rReytdL4Jh"\n,"callback":"5AB10F8A-EC5A-40E8-AF0B-7DC8DF580E55"\n,"data": []}

Given a base64 encoded verification key bXktdmVyaWZpY2F0aW9uLWtleQ== the expected signature can be calculated:

sha256hmac(key=b64decode('bXktdmVyaWZpY2F0aW9uLWtleQ=='), message='date:Mon, 21 Oct 2019 19:05:20 GMT\n{"account": null\n,"client_id": "fKcKvImyD2pQmRDWYSFx92rReytdL4Jh"\n,"callback": "5AB10F8A-EC5A-40E8-AF0B-7DC8DF580E55"\n,"data": []}')

The result, 74856469e8a97c0939a8d398460e1ffc83e4e40a46e657c61e9d3723035df10a, should match the hex digest following sha256= from the AWeber-Signature header.

Once the message has been verified, you should check that the client_id field matches the Client ID of your integration.

Python Verification Script

The following Python script implements webhook verification. It defines these variables:

  • request_headers: a dictionary mapping HTTP request headers to their values
  • request_body: the full HTTP request body
  • key_b64: the base64 encoded verification key
#!/usr/bin/env python
import base64
import hmac

request_headers = {
    'Date': 'Mon, 21 Oct 2019 19:05:20 GMT',
    'AWeber-Signature': ('sha256=74856469e8a97c0939a8d398460e1ffc83e4e40a46e65'
                         '7c61e9d3723035df10a'),
}

request_body = b"""\
{"account": null
,"client_id": "fKcKvImyD2pQmRDWYSFx92rReytdL4Jh"
,"callback": "5AB10F8A-EC5A-40E8-AF0B-7DC8DF580E55"
,"data": []}"""

key_b64 = 'bXktdmVyaWZpY2F0aW9uLWtleQ=='

# The verification key is encoded in base64
key = base64.b64decode(key_b64)

# The AWeber-Signature header contains the hash type and hash separated by '='
alg, _, expected_hash = request_headers['AWeber-Signature'].partition('=')
if alg != 'sha256':
    raise ValueError('Unexpected hash type: ' + alg)

message = (b'date:' +
           request_headers['Date'].encode('utf-8') +
           b'\n' +
           request_body)
calculated_hash = hmac.HMAC(key, msg=message.rstrip(), digestmod='SHA256')
if calculated_hash.hexdigest() != expected_hash:
    raise ValueError('Invalid signature')

print('Signature validated!')

Returning a Response

If you successfully process the message, you should return a 200 status code in your response. The response body will be ignored.

If you return a non-2XX level status code due to a failure, we may retry the message or stop sending webhooks entirely.

Webhook Reference

Headers

AWeber webhook callback requests will include the following HTTP headers:

Header
Description
AWeber-Delivery-ID Unique identifier for this request. This is helpful to include if you need support.
AWeber-Signature Hash type and message digest separated by an equals sign (=). The only defined hash type is sha256 for HMAC-SHA256. See RFC-2104 for more details.
Date Date the message was generated. See RFC-7231§7.1.1.2 and RFC-5322§3.3 for more details.

Body

Name
Type Description
account string Uniquely identifies the account that this event was fired for.
client_id string OAuth 2 client ID assigned to the application.
callback string Unique identifier for the callback.
data array of objects Each object contains two members: event and payload. The event is the name of the event and the payload is the data associated with the event.

Events

Events that occur in short succession will be batched together. Event batch sizes can range in size. Batches are multiple events that are predetermined for a single callback url.

subscriber.added

Triggered when a subscriber is added to a list regardless of the status of the subscriber. This event is fired for both verified and unverified subscribers.

The payload of a subscriber.added event is a JSON object with these members:

Name
Type Description
account string Uniquely identifies the AWeber account this is attached to.
ad_tracking string Optional customer-specified ad-tracking field that was included with the subscription request.
custom_fields object Mapping of current custom field values. Fields without values will be omitted.
email string Email address of the subscriber at the time of event generation.
id string Uniquely identifies this subscriber.
links object Links to related entity URLs. These should be used to retrieve those entities from the API.

It will contain the following members:
  • account: The account this subscriber is attached to.
  • list: This list the subscriber is part of.
  • subscriber: This subscriber.
list string Uniquely identifies the list that this subscriber is part of.
misc_notes string Optional notes that were included with the subscription request.
name string Display name of the subscriber.
signup_ip string IPv4 or IPv6 address that the subscription was created from.
signup_location object Mapping of signup location fields to values if the location was known at the time of signup. This field will be null otherwise.

It will contain the following members:
  • city: string
  • country_code: string
  • country_name: string
  • latitude: number
  • longitude: number
  • metro_code: number
  • postal_code: string
  • region_code: string
  • region_name: string
Fields without values are included with the value set to null.
status string One of subscribed, unconfirmed, unsubscribed, or deleted.
subscribed_at string ISO-8601 date-time at which the subscriber record was created.
subscription_method string One of api, email, import, or webform.
subscription_url string URL that the subscriber was added with.
tags array of strings Possibly empty array of tags that the subscriber is marked with.
unsubscribe_method string One of unsubscribe link, customer cp, undeliverable, api: unsubscribe, or api: move.
unsubscribed_at string ISO-8601 date-time at which the subscriber was unsubscribed.
verified_at string ISO-8601 date-time at which the subscriber was verified.
Example HTTP Request
POST /example HTTP/1.1
AWeber-Delivery-ID: 238D534C-2101-4440-98D7-7404938C3675
AWeber-Signature: sha256=99e0837dff15e0e27dc6729db56ac23860bd2d2da7ba07eb173f07628a7c7bad
Content-Length: 1646
Content-Type: application/vnd.aweber.webhook+json; version=1.0
Date: Mon, 21 Oct 2019 19:05:20 GMT

{
  "account": "c6501188-693a-472d-b426-296833f7e0ac",
  "client_id": "EmfELYyHkpYQMioIs7WidJf73csfev3b",
  "callback": "dd16587a-f7d1-4fdf-9f53-98f0353089a7",
  "data": [
    {
      "event": "subscriber.added",
      "payload": {
        "account": "c6501188-693a-472d-b426-296833f7e0ac",
        "ad_tracking": "control panel",
        "custom_fields": {
          "apple": "fuji",
          "pear": null
        },
        "email": "[email protected]",
        "id": "7941c272-6189-4318-b07f-c108368df796",
        "links": {
          "account": "https://api.aweber.com/1.0/accounts/000000",
          "list": "https://api.aweber.com/1.0/accounts/000000/lists/000000",
          "subscriber": "https://api.aweber.com/1.0/accounts/000000/lists/000000/subscribers/000000"
        },
        "list": "6011a920-d7d1-4829-a62a-b1c9309e2465",
        "misc_notes": "",
        "name": "Webhooks Tester",
        "signup_ip": "204.194.222.28",
        "signup_location": {
          "city": "Chalfont",
          "country_code": "US",
          "country_name": "United States",
          "latitude": 40.2964,
          "longitude": -75.2053,
          "metro_code": "504",
          "postal_code": "18914",
          "region_code": "PA",
          "region_name": "Pennsylvania"
        },
        "status": "unconfirmed",
        "subscribed_at": "2019-10-16T19:05:20-05:00",
        "subscription_method": "webform",
        "subscription_url": "https://www.aweber.com/users/leads/add",
        "tags": [],
        "unsubscribe_method": null,
        "unsubscribed_at": null,
        "verified_at": null
      }
    }
  ]
}

subscriber.subscribed

Triggered when a subscriber is subscribed to a list. This event is fired for subscribers on both COI and SOI lists.

The payload of a subscriber.subscribed event is a JSON object with these members:

Name
Type Description
account string Uniquely identifies the AWeber account this is attached to.
ad_tracking string Optional customer-specified ad-tracking field that was included with the subscription request.
custom_fields object Mapping of current custom field values. Fields without values will be omitted.
email string Email address of the subscriber at the time of event generation.
id string Uniquely identifies this subscriber.
links object Links to related entity URLs. These should be used to retrieve those entities from the API.

It will contain the following members:
  • account: The account this subscriber is attached to.
  • list: This list the subscriber is part of.
  • subscriber: This subscriber.
list string Uniquely identifies the list that this subscriber is part of.
misc_notes string Optional notes that were included with the subscription request.
name string Display name of the subscriber.
signup_ip string IPv4 or IPv6 address that the subscription was created from.
signup_location object Mapping of signup location fields to values if the location was known at the time of signup. This field will be null otherwise.

It will contain the following members:
  • city: string
  • country_code: string
  • country_name: string
  • latitude: number
  • longitude: number
  • metro_code: number
  • postal_code: string
  • region_code: string
  • region_name: string
Fields without values are included with the value set to null.
status string One of subscribed, unconfirmed, unsubscribed, or deleted.
subscribed_at string ISO-8601 date-time at which the subscriber record was created.
subscription_method string One of api, email, import, or webform.
subscription_url string URL that the subscriber was added with.
tags array of strings Possibly empty array of tags that the subscriber is marked with.
unsubscribe_method string One of unsubscribe link, customer cp, undeliverable, api: unsubscribe, or api: move.
unsubscribed_at string ISO-8601 date-time at which the subscriber was unsubscribed.
verified_at string ISO-8601 date-time at which the subscriber was verified.
Example HTTP Request
POST /example HTTP/1.1
AWeber-Delivery-ID: 375e9b8b-7cfe-4bb4-aeb4-aa530310559d
AWeber-Signature: sha256=ef62e7301aa8a9b322d65b21ed685fa53290df00da6156076466d5dec760e45f
Content-Length: 1647
Content-Type: application/vnd.aweber.webhook+json; version=1.0
Date: Fri, 27 Dec 2019 14:12:32 GMT

{
  "account": "c6501188-693a-472d-b426-296833f7e0ac",
  "client_id": "EmfELYyHkpYQMioIs7WidJf73csfev3b",
  "callback": "dd16587a-f7d1-4fdf-9f53-98f0353089a7",
  "data": [
    {
      "event": "subscriber.subscribed",
      "payload": {
        "account": "c6501188-693a-472d-b426-296833f7e0ac",
        "ad_tracking": "control panel",
        "custom_fields": {
          "apple": "fuji",
          "pear": null
        },
        "email": "[email protected]",
        "id": "e5423b61-8bff-4555-b791-927645e3bc4e",
        "links": {
          "account": "https://api.aweber.com/1.0/accounts/000000",
          "list": "https://api.aweber.com/1.0/accounts/000000/lists/000000",
          "subscriber": "https://api.aweber.com/1.0/accounts/000000/lists/000000/subscribers/000000"
        },
        "list": "6011a920-d7d1-4829-a62a-b1c9309e2465",
        "misc_notes": "",
        "name": "Webhooks Tester",
        "signup_ip": "204.194.222.28",
        "signup_location": {
          "city": "Chalfont",
          "country_code": "US",
          "country_name": "United States",
          "latitude": 40.2964,
          "longitude": -75.2053,
          "metro_code": "504",
          "postal_code": "18914",
          "region_code": "PA",
          "region_name": "Pennsylvania"
        },
        "status": "subscribed",
        "subscribed_at": "2019-10-16T19:05:20-05:00",
        "subscription_method": "webform",
        "subscription_url": "https://www.aweber.com/users/leads/add",
        "tags": [],
        "unsubscribe_method": null,
        "unsubscribed_at": null,
        "verified_at": "2019-12-27T10:11:55"
      }
    }
  ]
}

subscriber.unsubscribed

Triggered when a subscriber is unsubscribed from a list.

The payload of a subscriber.unsubscribed event is a JSON object with these members:

Name
Type Description
account string Uniquely identifies the AWeber account this is attached to.
ad_tracking string Optional customer-specified ad-tracking field that was included with the subscription request.
custom_fields object Mapping of current custom field values. Fields without values will be omitted.
email string Email address of the subscriber at the time of event generation.
id string Uniquely identifies this subscriber.
links object Links to related entity URLs. These should be used to retrieve those entities from the API.

It will contain the following members:
  • account: The account this subscriber is attached to.
  • list: This list the subscriber is part of.
  • subscriber: This subscriber.
list string Uniquely identifies the list that this subscriber is part of.
misc_notes string Optional notes that were included with the subscription request.
name string Display name of the subscriber.
signup_ip string IPv4 or IPv6 address that the subscription was created from.
signup_location object Mapping of signup location fields to values if the location was known at the time of signup. This field will be null otherwise.

It will contain the following members:
  • city: string
  • country_code: string
  • country_name: string
  • latitude: number
  • longitude: number
  • metro_code: number
  • postal_code: string
  • region_code: string
  • region_name: string
Fields without values are included with the value set to null.
status string One of subscribed, unconfirmed, unsubscribed, or deleted.
subscribed_at string ISO-8601 date-time at which the subscriber record was created.
subscription_method string One of api, email, import, or webform.
subscription_url string URL that the subscriber was added with.
tags array of strings Possibly empty array of tags that the subscriber is marked with.
unsubscribe_method string One of unsubscribe link, customer cp, undeliverable, api: unsubscribe, or api: move.
unsubscribed_at string ISO-8601 date-time at which the subscriber was unsubscribed.
verified_at string ISO-8601 date-time at which the subscriber was verified.
Example HTTP Request
POST /example HTTP/1.1
AWeber-Delivery-ID: ca154dc4-cbc1-4fd7-91a6-a326de9a5265
AWeber-Signature: sha256=2783917cb0ffc64afd383dada36fa5ecac1c7c0465375d566b03f876aecb1e4b
Content-Length: 1686
Content-Type: application/vnd.aweber.webhook+json; version=1.0
Date: Fri, 27 Dec 2019 17:32:32 GMT

{
  "account": "c6501188-693a-472d-b426-296833f7e0ac",
  "client_id": "EmfELYyHkpYQMioIs7WidJf73csfev3b",
  "callback": "dd16587a-f7d1-4fdf-9f53-98f0353089a7",
  "data": [
    {
      "event": "subscriber.unsubscribed",
      "payload": {
        "account": "c6501188-693a-472d-b426-296833f7e0ac",
        "ad_tracking": "control panel",
        "custom_fields": {
          "apple": "fuji",
          "pear": null
        },
        "email": "[email protected]",
        "id": "cf8eb994-dce4-4c1c-8bad-2c6284692d18",
        "links": {
          "account": "https://api.aweber.com/1.0/accounts/000000",
          "list": "https://api.aweber.com/1.0/accounts/000000/lists/000000",
          "subscriber": "https://api.aweber.com/1.0/accounts/000000/lists/000000/subscribers/000000"
        },
        "list": "6011a920-d7d1-4829-a62a-b1c9309e2465",
        "misc_notes": "",
        "name": "Webhooks Tester",
        "signup_ip": "204.194.222.28",
        "signup_location": {
          "city": "Chalfont",
          "country_code": "US",
          "country_name": "United States",
          "latitude": 40.2964,
          "longitude": -75.2053,
          "metro_code": "504",
          "postal_code": "18914",
          "region_code": "PA",
          "region_name": "Pennsylvania"
        },
        "status": "unsubscribed",
        "subscribed_at": "2019-10-16T19:05:20-05:00",
        "subscription_method": "webform",
        "subscription_url": "https://www.aweber.com/users/leads/add",
        "tags": [],
        "unsubscribe_method": "unsubscribe link",
        "unsubscribed_at": "2019-27-12T17:32:09+0000",
        "verified_at": "2019-12-27T10:11:55"
      }
    }
  ]
}

Considerations

Webhooks are not guaranteed to be published. They are sent on a best effort basis. To catch any events you may have missed, you should query the API with a scheduled job.

Duplicate webhook requests may be sent. To prevent taking action on a message that you have already received, you can use the AWeber-Delivery-ID as a unique identifier for that message.

You should not rely on the order in which webhook messages are published. Due to differences in processing time, they may arrive out of order.

Introduction

We have created code samples to help you complete common tasks that your application may need to perform. We have provided samples in PHP, Python, Postman, C#.NET, and Node.js. All of our examples are available on Github.

If you wish to see samples in another language Request It Here.

Find a List and Get Tags

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Find a list on an account
  • Get the list's tags

Manage a Subscriber

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Find a subscriber on a list
  • Add the subscriber if not found
  • Update the subscriber
  • Get the subscriber's activity
  • Delete the subscriber

Create a Purchase

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Create a purchase
  • Get the subscriber's activity

Manage Custom Fields

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Create a custom field
  • Update the custom field
  • Delete the custom field

Find Subscribers Across Lists

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Find a subscriber in an account by email address

Move Subscriber to Another List

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get subscribers for a list
  • Get a specific subscriber
  • Move the subscriber to the another list

Create and Schedule a Broadcast

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Create a broadcast
  • Schedule the broadcast

Broadcasts are an email sent to the subscribers within a list.

Get Sent Broadcast Details

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get all broadcasts for a list
  • Get total number of draft, scheduled and sent broadcasts
  • Get the subject of the first draft, scheduled and sent broadcasts

Get Broadcast Statistics

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get broadcasts for a list
  • Get statistics for a broadcast (campaign)

Get Subscribers Who Opened or Clicked a Broadcast

PHP | Python | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get broadcasts for a list
  • Get messages for a broadcast
  • Get subscribers for all messages of the broadcast
  • Get Email address for a subscriber of the message
  • Get message opens and clicks

Get Webforms Detail

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get webforms for a list
  • Get webform split tests for a list
  • Get split test components

Get Integrations List

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get integrations used for email sharing

Get Segments

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get segments associated with a list

Get Landing Pages

PHP | Python | Postman | C#.NET | Ruby | Node.js

The linked code samples demonstrate how to:

  • Get landing pages associated with a list

Developer Changelog

We have an email newsletter just for developers. It contains information about new features and upcoming changes to the API. It’s a great way to stay informed. Check out previous newsletters here. When you sign up for a developer account you are automatically subscribed. If you previously unsubscribed or would like to have another email address receive updates, feel free to sign up here: AWeber Developer Newsletter

Webhooks

Version 1.3.0


Release Date: Jun 21, 2022

  • Webhook support no longer requires a request to the API team. They can be enabled for any OAuth 2 application on labs.aweber.com.

Version 1.2.1


Release Date: Apr 20, 2020

Version 1.2.0


Release Date: Apr 14, 2020

  • Added support for imports and large batches.

Version 1.1.0


Release Date: Jan 3, 2020

  • Added webhooks for subscriber.subscribed and subscriber.unsubscribed events.

Version 1.0.0


Release Date: Nov 26, 2019

  • Added webhooks support. The first webhook offered is a subscriber.added event.

API

Version 1.2.3


Release Date: Dec 27, 2023

  • Adds 410 error response to list of possible API Responses
  • Replaces documentation links in code examples from labs.aweber.com/docs/troubleshooting to use api.aweber.com

Version 1.2.2


Release Date: Oct 12, 2023

Version 1.2.1


Release Date: Dec 14, 2022

  • Add company field to the Account endpoints.

Version 1.2.0


Release Date: Dec 15, 2021

  • Add Purchase creation endpoint. This allows for the creation of a tracked event (purchase) and a subscriber to be made.

Version 1.1.1


Release Date: Nov 17, 2021

  • Add uuid field to the Subscriber entry endpoint response.

Version 1.1.0


Release Date: June 16, 2021

  • Replace usage of the subscriber.read-extended scope with subscriber.read. If you were requesting subscriber.read-extended then you should change your application to request the subscriber.read scope instead. Existing tokens already that have the subscriber.read-extended scope have already been granted subscriber.read implicitly. The subscriber.read-extended scope can still be requested; however it is no longer required and is the same as requesting the subscriber.read scope.

Version 1.0.67


Release Date: Mar 3, 2021

  • Remove http_etag field from the Campaigns endpoints.
  • Add vapid_public_key field to the Lists endpoints.

Version 1.0.66


Release Date: Feb 19, 2021

Version 1.0.65


Release Date: Feb 18, 2021

  • Add uuid field to the Accounts endpoints.

Version 1.0.64


Release Date: Sep 25, 2020

Version 1.0.63


Release Date: Sep 21, 2020

Version 1.0.62


Release Date: Sep 15, 2020

Version 1.0.61


Release Date: Jul 30, 2020

Version 1.0.60


Release Date: Jun 11, 2020

Version 1.0.59


Release Date: May 8, 2020

  • Modify the behavior of the ws.size and ws.start parameters to only accept valid values.
    • ws.size only accepts integer values between 1 and 100.
    • ws.start only accepts integer values greater than or equal to 0.
    • A 400 WebServiceError will be returned for all invalid values.

Version 1.0.58


Release Date: Apr 23, 2020

Version 1.0.57


Release Date: Apr 13, 2020

Version 1.0.56


Release Date: Mar 5, 2020

  • Add links to Ruby code examples.

Version 1.0.55


Release Date: Feb 14, 2020

  • Add links to Node.js code examples.

Version 1.0.54


Release Date: Jan 17, 2020

  • Added update_existing parameter to the POST Subscriber endpoint. Please see the endpoint documentation for details.

Version 1.0.53


Release Date: Dec 10, 2019

  • Added uuid field to the Lists endpoints.

Version 1.0.52


Release Date: Oct 17, 2019

Version 1.0.51


Release Date: Sep 5, 2019

Version 1.0.50


Release Date: Aug 7, 2019

  • Add cURL code samples to endpoints.

Version 1.0.49


Release Date: Jul 16, 2019

  • Add links to C#.NET code examples.

Version 1.0.48


Release Date: Jul 2, 2019

  • The body_amp field in the Broadcasts endpoints is no longer in BETA.

Version 1.0.49


Release Date: Jun 27, 2019

  • Updated OAuth 2.0 to allow passing an authorization code out-of-band using a redirect_uri value of urn:ietf:wg:oauth:2.0:oob. Documentation for it can be found in the Authentication Overview.

Version 1.0.48


Release Date: Jun 21, 2019

  • Added analytics_src to the Accounts endpoints. analytics_src is used for event tracking on a website. See our knowledge base article for more details.

Version 1.0.47


Release Date: Jun 17, 2019

Version 1.0.46


Release Date: Jun 17, 2019

Version 1.0.45


Release Date: May 23, 2019

Version 1.0.44


Release Date: May 15, 2019

Version 1.0.43


Release Date: May 10, 2019

Version 1.0.42


Release Date: Apr 15, 2019

  • Released support for OAuth 2.0 along with updated API documentation, code samples, and knowledge base articles.

Version 1.0.41


Release Date: Feb 26, 2019

  • Find Subscribers for List can now accept query parameter sort_key with value subscribed_at or unsubscribed_at. This will sort the results by that key and the direction specified by sort_order.

Version 1.0.40


Release Date: Feb 21, 2019

Version 1.0.39


Release Date: Jan 3, 2019

  • Find Subscribers for List can now accept subscribed_before, subscribed_after, unsubscribed_before, and unsubscribed_after as search parameters.
  • Update Broadcast can now accept include_lists and exclude_lists as update parameters.

Version 1.0.38


Release Date: Dec 28, 2018

  • Find Subscribers for Account can now accept subscribed_before, subscribed_after, unsubscribed_before, and unsubscribed_after as search parameters.

Version 1.0.37


Release Date: Dec 19, 2018

Version 1.0.36


Release Date: Dec 11, 2018

Version 1.0.35


Release Date: Nov 16, 2018

Version 1.0.34


Release Date: Nov 07, 2018

  • Add broadcast links to the list entries. There are three new links that were added to the list collection, list entry and the list find responses: draft_broadcasts_link, scheduled_broadcasts_link and sent_broadcasts_link.

Version 1.0.33


Release Date: Sep 10, 2018

  • Add list_link and list_name to the find and findSubscribers endpoints. This will show the list info for the subscribers returned.

Version 1.0.32


Release Date: May 2, 2018

  • Add unsubscribed_at to the find and findSubscribers endpoints. This will show the list info for the subscribers returned.

Version 1.0.31


Release Date: Jan 19, 2018

Version 1.0.30


Release Date: Jan 10, 2018

  • Add tags to the response body of the findSubscribers endpoint.
  • Add tags to the findSubscribers findSubscribers endpoint to allow searching on a tag as a parameter.

Version 1.0.29


Release Date: Dec 22, 2017

  • Add tags to the response body of the find endpoint.
  • Add tags to the find endpoint to allow searching on a tag as a parameter.
  • Update subscriber subscription_method value from "signup form" to "webform" to match the Subscriber Collection and Subscriber Entry endpoints.
  • Remove http_etag field from entries in the Subscriber Collection find endpoint.

Version 1.0.28


Release Date: Dec 14, 2017

Version 1.0.27


Release Date: Jul 22, 2016

  • Update the sort order of the Subscriber Collection endpoint to be the order in which the subscribers were added to a list.

Version 1.0.26


Release Date: Jul 8, 2016

Version 1.0.25


Release Date: Apr 8, 2016

Version 1.0.25


Release Date: Nov 6, 2015

  • Sorted and documented the sort order for the following collection responses:
    • Broadcasts
    • Campaigns
    • Clicks
    • Components
    • Custom Fields
    • Docs
    • Integrations
    • Links
    • Lists
    • Messages
    • Opens
    • Stats
    • Subscribers
    • Tracked Events
    • Web Form Split Tests
    • Web Forms
  • Documented the pagination control parameters ws.size and ws.start.
  • Clarified the use of the term campaigns in the API as distinct from the Campaigns email automation platform.

Version 1.0.24


Release Date: Apr 24, 2015

Version 1.0.23


Release Date: Mar 24, 2015

Version 1.0.22


Release Date: Nov 10, 2014

  • Add the ability to Schedule Broadcast.
  • Add schedule broadcast permissions to application permissions.

Version 1.0.21


Release Date: Jun 23, 2014

  • Return unique_list_id attribute of a List.
  • Update API reference docs for Lists.

Version 1.0.20


Release Date: Jun 11, 2014

  • Return customized name of a list as the value of the name attribute of the List.
  • Modify find method of List collection to search for lists by both the unique and customized name.
  • Update API reference docs for Lists.

Version 1.0.19


Release Date: Jan 20, 2014

Version 1.0.18


Release Date: Mar 25, 2013

  • Add a new API Documentation collection.
  • Update labs docs with better API Documentation.
  • Performance Tweaks.

Version 1.0.17


Release Date: Jan 3, 2013

  • Add Campaign Stats to the Broadcast Campaign endpoint.
    • Clicks:
      • total clicks.
      • unique clicks.
      • clicks over time (first 24 hours).
      • clicks over time (first 2 weeks).
      • top 10 clicked links.
    • Opens:
      • total opens.
      • unique opens.
      • opens over time (first 24 hours).
      • opens over time (first 2 weeks).
      • top 10 subscribers who opened your message the most.
    • Sales:
      • total sales (number of sales).
      • total sales (dollar amount).
      • sales over time (first 24 hours).
      • sales over time (first 2 weeks).
      • top 10 grossing subscribers who purchased from you after receiving your broadcast.
    • Unsubscribed Subscribers:
      • total unsubscribed.
      • unsubscribed over time (first 24 hours).
      • unsubscribed over time (first 2 weeks).
    • Web Hits:
      • web hits over time (first 24 hours).
      • web hits over time (first 2 weeks).
      • top 10 web hits that were clicked.

Version 1.0.16


Release Date: Dec 10, 2012

  • Add ability to specify last_followup_message_number_sent when performing a Subscriber Move to a different list.
    • This enables an app to move a subscriber and control how they receive follow up messages.

Version 1.0.15


Release Date: Nov 19, 2012

Version 1.0.14


Release Date: Aug 30, 2012

  • Add the ability to Find a Campaign by campaign type.
    • This allows you to query the api for followups or broadcasts.
    • Refer to the Code Samples for examples.
  • Add additional search parameters for the find and findSubscribers endpoints.
    • Most attributes including custom fields are now searchable.

Version 1.0.13


Release Date: Aug 22, 2012

  • Add the ability to Find Lists by name.
  • Change default sort order of the Campaigns Collection endpoint.
    • Followups are sorted in order of the message_number attribute.
    • Broadcasts are sorted in descending order by the sent_at attribute.

Version 1.0.12


Release Date: Nov 16, 2011

  • Add the ability to POST Subscriber to a list.
    • You can now add Subscribers via the API!
    • Please refer to our php and python code samples for examples of adding Subscribers.

Version 1.0.11


Release Date: Sep 22, 2011

Version 1.0.10


Release Date: Jul 26, 2011

Version 1.0.9


Release Date: Jul 11, 2011

  • Fix formatting consistency issue for timestamps.
  • Fix bug in the "type" attribute for Webforms and Components.
  • Fix error message for throttled API requests.

Version 1.0.8


Release Date: Jun 29, 2011

  • Add total_subscribers, total_subscribed, total_unsubscribed, total_subscribers_subscribed_today, and total_subscribers_subscribed_yesterday to the Subscriber statistics.
  • Fix inconsistency with date formatting.

Version 1.0.7


Release Date: Jun 1, 2011

Version 1.0.6


Release Date: May 23, 2011

  • Add application/json responses for all 400 and 500 HTTP statuses

Version 1.0.5


Release Date: May 11, 2011

Version 1.0.4


Release Date: Apr 20, 2011

  • Fix various bugs the Subscriber Entry and other resources.
  • Increas API performance for Subscribers and Campaigns.

Version 1.0.3


Release Date: Mar 31, 2011

Version 1.0.2


Release Date: Mar 16, 2011

  • Add the ability to Find Subscribers by email address.
  • Add the ability to Move Subscribers to another list on the same account.
    • Subscriber is unsubscribed from original List
    • Subscriber is subscribed to the new List with the original Subscriber"s data.
  • Add the additional attributes to Subscriber Entry.
    • Unsubscribe Method

Version 1.0.1


Release Date: Jan 13, 2011

  • Add the ability to modify and delete subscriber data
  • Add additional attributes based on ip_address to the Subscriber Entry:
    • Country
    • Region
    • City
    • Postal Code
    • Latitude
    • Longitude
    • DMA Code
    • Area Code
    • Last Followup Message Number
    • Custom Field Key/Value Pairs
  • Allow modification of Subscriber attributes thru POST Subscriber endpoint.
    • Ad Tracking
    • Last Followup Message Number
    • Name
    • Email Address
    • Status (Subscribed or Unsubscribed)
    • Misc Notes

Version 1.0.0


Release Date: Nov 17, 2010

FAQ

Do I need to be an AWeber customer to develop an application?


To develop an API application, you will need to open an AWeber Labs account which is 100% free and entirely unrelated to AWeber customer accounts.

If you are not an AWeber customer already, you may also want to create an AWeber customer account using a free 1 month trial. This account can be used to test the API application which you are developing.

How does AWeber's API handle user authentication?


The AWeber API uses OAuth to handle authenticating requests on behalf of AWeber users. OAuth provides a standardized way for providing third party applications access to a user's data without the need for that customer to give out their username and password. For more information on how authentication is implemented in the AWeber API, please read our authentication guide.

What character encoding does the API use?


The AWeber API uses UTF-8 character encoding. UTF-8 was chosen due to its widespread usage online and is supported by a majority of the programming languages in use today.

When passing data to the AWeber API, it's up to the app developer to ensure that the data is sent to us using the proper character encoding. The API will return a Bad Request with 'Invalid Character Encoding' if the data sent to the API is not UTF-8 encoded.

How do I update customer account information / add subscribers?


You can add a subscriber to a list by invoking the POST Subscriber endpoint. Please refer to our php and python code samples for examples of adding Subscribers.

Customer account information cannot currently be edited via the API. Please refer to our reference documentation or changelog for more details.

What formats of data are returned by the AWeber API?


All requests in the AWeber API, including error messages, are returned as JSON formatted strings. JSON was chosen due to its ease of readability and because it is well supported in a large number of languages.

How many requests can my application make in a given amount of time?


AWeber API requests are limited to 120 requests per minute, per customer account.

Troubleshooting

Authentication Errors

When authenticating an application, there are a few errors which a user may encounter. This section will provide you with input into some of the authentication errors and how to resolve them.

Common Issues

Invalid redirect URI

If this error is encountered, it is due to a mismatch between the redirect_uri being submitted and the OAuth Redirect URL specified when creating the application in your AWeber Developer account.

[OAuth2 Redirect]

Troubleshooting Checklist

  • Ensure the submitted redirect_uri exactly matches the OAuth Redirect URL specified for your application.
    • Make sure there are no characters added/missing.

Public Applications

PKCE Errors

These errors are raised when you try to authorize a public application, but do not include a code_challenge in your original request.

  • Public Client MUST Use PKCE
  • code_challenge is required for public client

Troubleshooting Checklist

  • See here for steps on how to authenticate a public application.

Confidential Applications

PKCE Errors

These errors are raised when you try to authorize a confidential application and include a code_verifier, challenge, or challenge_method in your request

  • Confidential Client MUST NOT Use PKCE
  • code_challenge and code_challenge_method are disallowed for confidential clients

Troubleshooting Checklist

  • See here for steps on how to authenticate a confidential application.

API Errors

If an API call results in an error, the API response will return details about the error using JSON. Most errors encountered with the API can be easily handled and corrected in your application. To provide a better user experience, you should design your API applications to expect errors and handle them appropriately. When an error is returned:

  • The appropriate HTTP status will be set in the response headers.
  • Content-Type will be set to application/json.
  • The body will consist of a JSON formatted dictionary with a single key called "error" containing the status, error type, message, and documentation URL.

Here is a sample API error response:

{"error": 
  {"status": 401, 
   "message": "Consumer key is invalid.", 
   "type": "UnauthorizedError", 
   "documentation_url": "https://api.aweber.com"}}

400 BadRequestError

This error is raised when you make a properly authenticated request to a valid resource with incorrect parameters. If you receive 400 BAD REQUEST errors, refer to the actual error message as well as the appropriate documentation for the method you are calling.

Examples

  • Attempting to modify a read-only field.
  • Invoking the find() method on a subscriber entry without supplying an email address
  • Invoking the move() method on a subscriber entry without supplying a list
  • Creating or modifying resources using invalid character encodings. (See FAQ)
  • Creating or modifying a resource while missing required parameters
  • Passing through a private or reserved IP address when adding a subscriber ("Invalid Subscriber IP address. The address is part of a reserved block.")

Troubleshooting Checklist

  • Refer to the error message for a summary of what is wrong.
  • Refer to the API reference documentation for the method you're calling to find out what it requires.

401 UnauthorizedError

This class of errors represents authentication errors. In order to troubleshoot authentication errors, a basic understanding of the OAuth 2.0 Authentication Protocol is required. Please refer to the following documentation for more information on how we handle authentication with the AWeber API as well as specific examples of how to handle each kind of authentication error.

AWeber API Authentication
RFC5849 OAuth 2.0 Specification

Invalid Token

This error is raised when your access token key is expired or invalid. The most common causes for this error is that the AWeber Customer disconnected your application from their account, you're access token has expired, or you have a typographical error in the access token key.

Troubleshooting Checklist

  • Obtain a new access token key.

Invalid Account

This error is raised when the AWeber Customer account is no longer active. The most common causes for this error are that the AWeber Customer cancelled their account or you are using an invalid account id.

Troubleshooting Checklist

  • Contact support to reactivate the AWeber Customer account.

Invalid Request

This error is raised when your application attempts to communicate to the AWeber API without using the OAuth 2.0 protocol. You must fully implement the OAuth 2.0 protocol to access the AWeber API.

Troubleshooting Checklist

403 ForbiddenError

This class of errors is used when the API understands your request but has refused to grant access to the requested resource.

Account Temporarily Suspended

This error is raised when the AWeber Customer account is temporarily suspended. The most common causes for this error are that the AWeber Customer has a billing issue or you are using an invalid account id.

Troubleshooting Checklist

  • Contact support to reactivate the AWeber Customer account.

Adding subscribers is not available while the account is on hold.

This error is raised when the AWeber Customer account is on hold. The customer has decided to switch their account to the hold package which does not allow subscribers to be added.

Troubleshooting Checklist

  • Switch the AWeber Customer account off of the hold package.

Application not authorized to manage email.

This error is raised when you make a request to create or schedule a Broadcast, but your application has not been authorized by the AWeber Customer to manage email.

Troubleshooting Checklist

  • Ensure that your application has specified that it requires the Manage All Email Communications permission.
  • Ensure that the AWeber Customer has authorized your application after it was modified to require the Manage All Email Communications permission. The AWeber Customer may need to disable and re-enable your application to grant this authorization.

Rate Limit Error.

This error is raised when the number of API requests made by your application exceed its predefined limit. These rate limits are outlined in our knowledge base.

Troubleshooting Checklist

  • Reduce the frequency that you make API requests.
  • Utilize a local cache in your application to prevent making unnecessary API requests.
  • See our knowledge base documentation on how to handle rate limits.

Subscriber Complaints Error.

This error is raised when the number of complaints reported by subscribers is too high. Complaints generally occur when subscribers receive email they did not sign up for or do not want. Continued complaints reported by subscribers can lead to the suspension of the AWeber account.

Troubleshooting Checklist

  • Review and implement these best practices to lower subscriber complaints.
  • Wait for those complaints to lessen.

Resource temporarily unavailable

This error is raised when the POST or PUT request length exceeds 1 million bytes of data when creating a broadcast message.

Troubleshooting Checklist

  • Send a smaller POST/PUT payload.

The email address provided cannot be accepted at this time

This error is raised when the subscriber email address is not currently acceptable.

Troubleshooting Checklist

  • Try again using an exponential backoff

This account is not accepting requests at this time

Troubleshooting Checklist

  • Try again using an exponential backoff

Your request cannot be processed at this time

Troubleshooting Checklist

  • Try again using an exponential backoff

Subscriber limit reached.

  • You've reached the subscriber limit for your current plan. Upgrade to continue adding subscribers.

404 NotFoundError

This error is raised when the requested resource does not exist.

Troubleshooting Checklist

405 MethodNotAllowedError

This error is raised when a properly authenticated request is made to a valid resource, but the HTTP method you used is not allowed.

Examples

  • Attempting to modify a read-only resource using the PUT or PATCH method.
  • Invoking the move() method on a subscriber entry that has a status of 'unconfirmed'.

Troubleshooting Checklist

  • Check the URL of the resource you are requesting.
  • Make sure the resource supports the HTTP method you are using.
  • Check the response from the error message for further details.
  • Refer to the API Reference Documentation for more information.

409 Conflict


This error is raised when the request could not be completed due to a conflict with the current state of the resource.

Examples

  • Attempting to schedule a Broadcast that has already been sent.

410 BlockedError

This error is raised when the request is blocked.

Troubleshooting Checklist

This request has been blocked. If you feel this is a mistake, please contact [email protected] and include your IP Address, the name of your integration, the API endpoint URL you were attempting to reach, and any other information you feel would be helpful

415 InvalidContentType

This error is raised when the request is in a format that is not supported by the resource for the method.

Examples

  • Making a POST request with a Content-Type other than application/x-www-form-urlencode.

500 InternalServerError

This error is raised when the API experiences an internal error.

Troubleshooting Checklist

  • Try your request again.
  • Contact support if the problem persists.

503 ServiceUnavailableError

This error is raised when the API is down for maintenance.

Troubleshooting Checklist

  • Try your request again.
  • Contact support if the problem persists.

Troubleshooting Checklist

  • Use a version of the Python Client Library >= 1.2.1
  • Contact support if the problem persists.

Non-Error Responses

204 NoContent

A 204 No Content status is returned when an API resource was successfully updated and there is no content to return.

209 ContentModified

A 209 Content Modified status is returned along with a JSON representation when an API resource was successfully updated with an HTTP PATCH request.