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:
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.
AWeber provides a REST API and Webhooks. For more information about webhooks please navigate to the Webhooks section within this documentation.
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:
Within this document, campaigns is a generic term that refers to both Broadcast and Follow Up messages. Currently the AWeber API does not support Campaigns, which is an email automation platform available to customers within the AWeber web platform.
Before you can make requests to the API, you need to support our authentication protocol. We currently require all 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.
API resources are arranged in the AWeber API based on their relationships to each other. We illustrate these relationships on the image below with the URLs of the resources. When we refer to the relationships of the resources, we say an Account has Lists, a List has Subscribers, etc. We can also say Subscribers belong to a List, or Lists belong to an Account, and so on.
A single resource is referred to as an Entry and is shown as a yellow circle on the image. Entries are contained in Collections which are shown as a blue box on the image. These resources are contained under version '1.0' of the API.
Collections are represented as an ordered sequence of entries. They are paginated using the ws.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.
The AWeber API uses the OAuth 2.0 specification for authentication. OAuth 2.0 is the successor to OAuth 1, which AWeber’s API formerly used. If you have an existing OAuth 1 application, documentation regarding how to connect with OAuth 1 is available. Please plan to move to OAuth 2.0 as soon as you are able.
Connecting your integration to an AWeber customer account requires the use of OAuth 2.0. This step is required before you start making requests to AWeber’s API in order to do things like add subscribers, check your broadcast stats, or sending messages. We use OAuth 2.0 in order to ensure that an integration has permission to access a given AWeber account.
You'll need the following to get started:
If you need a customer account you can sign up for a free trial to get started. These examples will be using Python 3 and requests_oauthlib as the HTTP library. You will find there are lots of good libraries available for every programming language. The set up and usage varies between libraries. Be sure to read the documentation for the library you select. For a full sample in Python as well as PHP, C#.NET, Ruby, and Node.js please see our code samples on GitHub.
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:
|
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:
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.
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.
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.
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)
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)
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.
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.
This step is unchanged from the standard authorization code flow.
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
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.
Sometimes an integration is used by many AWeber customers. You can have as many users as you like with this authentication process. Just start at the top and make a new request token for each user of your integration. Access tokens are tied to AWeber customer accounts so each account will have a new set of tokens. You can store them safely in a database and use the account ID to differentiate them.
Here are some solutions to common problems:
If you still can’t figure it out we’re always happy to help you work through any errors. Send us an email at [email protected] and be sure to note any errors or information about the problem you’re having.
Below is a python example using the requests_oauthlib
OAuth library to
obtain an accounts access tokens.
You will need:
Client ID
, Client Secret
, and Redirect URI
from your integration,
available on the My Apps Page.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.
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:
Client ID
, and Redirect URI
from your integration, available on the
My Apps Page.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())
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"
}
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"
}
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).
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.
Authorization | string Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= A base-64 encoded string for |
client_id required | string The client ID of the application. Available on the My Apps Page. |
client_secret required | string The client secret of the application. Available on the My Apps Page. |
grant_type required | string Value: "authorization_code" The grant type of the token. |
code required | string The authorization code received from the authorization call. |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "client_id": "***************",
- "client_secret": "***************",
- "grant_type": "authorization_code",
- "code": "***************"
}
{- "access_token": "***************",
- "expires_in": 7200,
- "refresh_token": "***************",
- "token_type": "bearer"
}
This endpoint is used to revoke an access or refresh token.
Authorization | string Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= A base-64 encoded string for |
client_id required | string The client ID of the application. Available on the My Apps Page. |
client_secret required | string The client secret of the application. Available on the My Apps Page. |
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
If not specified, search for both kinds of tokens. |
{- "client_id": "*********",
- "client_secret": "*********",
- "token": "gTCFZykztNGFcQlKViqkXN_uKG5fDl0SAGcEQNjSePk",
- "token_type_hint": "access_token"
}
{- "error": "invalid_request",
- "error_description": "Missing parameter or other invalid request, or trying to pass in a client secret for a public client",
}
This endpoint is used to get a request token.
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 |
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. |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
"oauth_token_secret=******************&oauth_token=******************&oauth_callback_confirmed=true"
This endpoint is used to get an access token.
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 |
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. |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
"oauth_token_secret=******************&oauth_token=******************"
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.
account.read
) 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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "analytics_src": "//analytics.aweber.com/js/awt_analytics.js?id=123",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 123,
- "uuid": "b619e767-9de6-43b7-a914-9a8d77a08ee5",
- "company": "Example Company 1"
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/custom_fields?ws.start=0&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/custom_fields?ws.start=0",
- "start": 0,
- "total_size": 100
}
account.read
) accountId required | integer <int32> The account ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "analytics_src": "//analytics.aweber.com/js/awt_analytics.js?id=123",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 123,
- "uuid": "b619e767-9de6-43b7-a914-9a8d77a08ee5",
- "company": "Example Company 1"
}
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 |
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.
broadcast_id
and only include API created broadcast draftsscheduled_for
sent_at
Check out related examples:
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
status required | string Enum: "draft" "scheduled" "sent" The status of the broadcasts to retrieve. (Please be aware that |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \ -d status=sent \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "status": "sent",
- "scheduled_for": "2017-11-15T15:46:07.926Z",
- "sent_at": "2017-11-15T19:26:36.210Z",
- "subject": "Weekly Recipes"
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=sent&ws.size=1&ws.start=1",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=sent&ws.size=1&ws.start=0",
- "start": 0,
- "total_size_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/total?status=draft"
}
This endpoint is used to create a broadcast message draft. This POST request is limited to 1 million bytes.
Check out related examples:
email.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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.] |
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. |
include_lists | string Default: [] JSON encoded list of Lists URLs to include in the delivery of this broadcast. |
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., |
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 |
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., |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request has been blocked
The enclosed body has a media type that is not application/x-www-form-urlencoded
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "body_html": "<html><h1>Title</h1><body>Message body.</body></html>",
- "body_text": "This is the content of my message",
- "body_amp": "<html amp4email><body>content</body></html>",
- "broadcast_id": 12345,
- "click_tracking_enabled": true,
- "clicks_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/3456789/clicks",
- "created_at": "2015-10-23T16:19:20.000Z",
- "has_customized_body_text": true,
- "is_archived": true,
- "links": [
], - "notify_on_send": true,
- "opens_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/3456789/opens",
- "scheduled_for": "2017-11-15T15:46:07.926Z",
- "segment_link": null,
- "segment_name": "my_segment",
- "sent_at": "2024-09-27T20:01:29Z",
- "stats": {
- "num_complaints": 0,
- "num_emailed": 1,
- "num_undeliv": 0,
- "unique_clicks": 1,
- "unique_opens": 1
}, - "status": "admin_hold",
- "subject": "Weekly Recipes",
}
This endpoint is used to retrieve a broadcast message.
Check out related examples:
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "body_html": "<html><h1>Title</h1><body>Message body.</body></html>",
- "body_text": "This is the content of my message",
- "body_amp": "<html amp4email><body>content</body></html>",
- "broadcast_id": 12345,
- "click_tracking_enabled": true,
- "clicks_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/3456789/clicks",
- "created_at": "2015-10-23T16:19:20.000Z",
- "has_customized_body_text": true,
- "is_archived": true,
- "links": [
], - "notify_on_send": true,
- "opens_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/3456789/opens",
- "scheduled_for": "2017-11-15T15:46:07.926Z",
- "segment_link": null,
- "segment_name": "my_segment",
- "sent_at": "2024-09-27T20:01:29Z",
- "stats": {
- "num_complaints": 0,
- "num_emailed": 1,
- "num_undeliv": 0,
- "unique_clicks": 1,
- "unique_opens": 1
}, - "status": "admin_hold",
- "subject": "Weekly Recipes",
}
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:
email.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
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.] |
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. |
include_lists | string Default: [] JSON encoded list of Lists URLs to include in the delivery of this broadcast. |
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., |
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., |
segment_link | string <url> URL to the Segment to send this broadcast to. Use the |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request could not be completed due to a conflict with the current state of the target resource
The request has been blocked
The enclosed body has a media type that is not application/x-www-form-urlencoded
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "body_html": "<html><h1>Title</h1><body>Message body.</body></html>",
- "body_text": "This is the content of my message",
- "body_amp": "<html amp4email><body>content</body></html>",
- "broadcast_id": 12345,
- "click_tracking_enabled": true,
- "clicks_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/3456789/clicks",
- "created_at": "2015-10-23T16:19:20.000Z",
- "has_customized_body_text": true,
- "is_archived": true,
- "links": [
], - "notify_on_send": true,
- "opens_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts/3456789/opens",
- "scheduled_for": "2017-11-15T15:46:07.926Z",
- "segment_link": null,
- "segment_name": "my_segment",
- "sent_at": "2024-09-27T20:01:29Z",
- "stats": {
- "num_complaints": 0,
- "num_emailed": 1,
- "num_undeliv": 0,
- "unique_clicks": 1,
- "unique_opens": 1
}, - "status": "admin_hold",
- "subject": "Weekly Recipes",
}
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:
email.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request could not be completed due to a conflict with the current state of the target resource
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -X DELETE \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "error": {
- "message": "Maximum for \"ws.size\" parameter is 100.",
- "status": 400,
- "type": "BadRequestError"
}
}
This endpoint is used to cancel a currently scheduled broadcast.
Check out related examples:
email.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request could not be completed due to a conflict with the current state of the target resource
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -X POST \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/cancel \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{
}
This endpoint is used to get the total number of broadcasts in a particular state.
Check out related examples:
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
status required | string Enum: "draft" "scheduled" "sent" The status of the broadcasts to retrieve. (Please be aware that |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/total \ -d status=sent \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "total_size": 4
}
This endpoint is used to schedule a broadcast.
Check out related examples:
email.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
Request Body
scheduled_for required | string <date-time> Scheduled time for sending broadcast message, ISO-8601 formatted. |
The broadcast successfully scheduled
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request could not be completed due to a conflict with the current state of the target resource
The request has been blocked
The enclosed body has a media type that is not application/x-www-form-urlencoded
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{
}
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.
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
before | string The pagination key when paging in reverse. Cannot be combined with |
after | string The pagination key when paging forward. Cannot be combined with |
page_size | integer [ 1 .. 100 ] Default: 100 The pagination total entries to retrieve |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/opens \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "event_time": "2017-07-18T20:53:02.000Z",
- "type": "open"
}
], - "total_size": 1
}
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.
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
broadcastId required | integer <int32> The broadcast ID |
before | string The pagination key when paging in reverse. Cannot be combined with |
after | string The pagination key when paging forward. Cannot be combined with |
page_size | integer [ 1 .. 100 ] Default: 100 The pagination total entries to retrieve |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Manage Email permission
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/broadcasts/{broadcastId}/clicks \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "event_time": "2017-07-18T20:53:02.000Z",
- "type": "click"
}
], - "total_size": 1
}
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.
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:
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaignss \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "campaign_type": "b",
- "click_tracking_enabled": true,
- "content_type": "Text",
- "id": 1234567,
- "is_archived": true,
- "links_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b3456789/links",
- "message_interval": 1,
- "message_number": 1,
- "scheduled_at": "2017-07-18 16:53:02-04:00",
- "sent_at": "2017-07-18 16:53:07-04:00",
- "spam_assassin_score": 2.1,
- "stats_collection_link": "https://api.aweber.com/1.0/accounts/accounts/123/lists/456/campaigns/b3456789/stats",
- "subject": "Weekly Recipes",
- "total_clicks": 0,
- "total_opens": 0,
- "total_sent": 0,
- "total_spam_complaints": 0,
- "total_undelivered": 0,
- "total_unsubscribes": 0,
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns?ws.start=101&ws.size=100",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns?ws.start=0&ws.size=100",
- "start": 0,
- "total_size": 0
}
email.read
) 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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "campaign_type": "b",
- "click_tracking_enabled": true,
- "content_type": "Text",
- "id": 1234567,
- "is_archived": true,
- "links_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b3456789/links",
- "message_interval": 1,
- "message_number": 1,
- "scheduled_at": "2017-07-18 16:53:02-04:00",
- "sent_at": "2017-07-18 16:53:07-04:00",
- "spam_assassin_score": 2.1,
- "stats_collection_link": "https://api.aweber.com/1.0/accounts/accounts/123/lists/456/campaigns/b3456789/stats",
- "subject": "Weekly Recipes",
- "total_clicks": 0,
- "total_opens": 0,
- "total_sent": 0,
- "total_spam_complaints": 0,
- "total_undelivered": 0,
- "total_unsubscribes": 0,
}
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:
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "entries": [
- {
- "campaign_type": "b",
- "click_tracking_enabled": true,
- "content_type": "Text",
- "id": 1234567,
- "is_archived": true,
- "links_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b3456789/links",
- "message_interval": 1,
- "message_number": 1,
- "scheduled_at": "2017-07-18 16:53:02-04:00",
- "sent_at": "2017-07-18 16:53:07-04:00",
- "spam_assassin_score": 2.1,
- "stats_collection_link": "https://api.aweber.com/1.0/accounts/accounts/123/lists/456/campaigns/b3456789/stats",
- "subject": "Weekly Recipes",
- "total_clicks": 0,
- "total_opens": 0,
- "total_sent": 0,
- "total_spam_complaints": 0,
- "total_undelivered": 0,
- "total_unsubscribes": 0,
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns?ws.start=101&ws.size=100",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns?ws.start=0&ws.size=100",
- "start": 0,
}
A paginated collection of Links in a followup or broadcast campaign sorted by link id
.
Check out related examples:
email.read
) 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 |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "clicks_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/links/2/clicks",
- "id": 2,
- "total_clicks": 200,
- "total_unique_clicks": 150,
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/links?ws.start=2&ws.size=1",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/links?ws.start=0&ws.size=1",
- "start": 1,
- "total_size": 10
}
email.read
) 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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "clicks_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/links/2/clicks",
- "id": 2,
- "total_clicks": 200,
- "total_unique_clicks": 150,
}
A paginated collection of link clicks in a followup or broadcast campaign sorted by link id
.
Check out related examples:
email.read
) 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 |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/links/{linkId}/clicks \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "id": 2,
- "event_time": "2016-12-09 14:14:49-05:00",
- "type": "click",
- "is_earliest": true
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/links/1/clicks?ws.start=2&ws.size=1",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/links/1/clicks?ws.start=0&ws.size=1",
- "start": 1,
- "total_size": 10,
}
email.read
) 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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "id": 2,
- "event_time": "2016-12-09 14:14:49-05:00",
- "type": "click",
- "is_earliest": true
}
A paginated collection of statistics for a broadcast campaign message sorted by "statistics ID"
Check out related examples:
email.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
campaignId required | integer <int32> The campaign ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/b{campaignId}/stats \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "description": "total number of times a subscriber clicked any link appearing in your campaign except the unsubscribe link (includes multiple clicks of the same link)",
- "id": "total_clicks",
- "value": 21
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/stats?ws.start=2&ws.size=1",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/stats?ws.start=0&ws.size=1",
- "start": 1,
- "total_size": 10
}
email.read
) 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 request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/campaigns/{campaignType}{campaignId}/stats/{statsId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "description": "total number of times a subscriber clicked any link appearing in your campaign except the unsubscribe link (includes multiple clicks of the same link)",
- "id": "total_clicks",
- "value": 21
}
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.
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.
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/custom_fields \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "http_etag": "902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32",
- "id": 12345,
- "is_subscriber_updateable": false,
- "name": "Favorite color",
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/custom_fields?ws.start=0&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/custom_fields?ws.start=0",
- "start": 0,
- "total_size": 100
}
list.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
Request Body
name required | string The name of the custom field |
ws.op required | string Value: "create" The method name - expecting "create" |
The custom field was created successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The maximum number of custom fields has been exceeded
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "name": "Favorite color",
- "ws.op": "create"
}
{- "error": {
- "message": "name: Must be unique",
- "status": 400,
- "type": "BadRequestError"
}
}
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
customFieldId required | integer <int32> The custom field ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "http_etag": "902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32",
- "id": 12345,
- "is_subscriber_updateable": false,
- "name": "Favorite color",
}
list.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
customFieldId required | integer <int32> The custom field ID |
Request Body
name | string The name of the custom field |
is_subscriber_updateable | boolean Whether the subscriber is allowed to update the custom field |
The custom field was updated successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "name": "Favorite color",
- "is_subscriber_updateable": true
}
{- "http_etag": "902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32",
- "id": 12345,
- "is_subscriber_updateable": false,
- "name": "Favorite color",
}
list.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
customFieldId required | integer <int32> The custom field ID |
The custom field was deleted successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -X DELETE \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/custom_fields/{customFieldId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "error": {
- "message": "Missing required argument(s)",
- "status": 400,
- "type": "BadRequestError"
}
}
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.
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:
account.read
) accountId required | integer <int32> The account ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/integrations \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "http_etag": "902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32",
- "id": 123,
- "login": "twitter",
- "service_name": "facebook",
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/custom_fields?ws.start=0&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/custom_fields?ws.start=0",
- "start": 0,
- "total_size": 100
}
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:
account.read
) accountId required | integer <int32> The account ID |
integrationId required | integer <int32> The integration ID |
The request completed successfully
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/integrations/{integrationId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "http_etag": "902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32",
- "id": 123,
- "login": "twitter",
- "service_name": "facebook",
}
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.
This endpoint is used to get a paginated collection of list landing pages.
landing-page.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/landing_pages \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "created_at": "2017-07-18T20:53:02.000Z",
- "id": "48b38cd9-a5df-4297-8987-ed31b3093b39",
- "modified_at": "2017-07-18T20:53:02.000Z",
- "name": "My Awesome Landing Page",
- "published_at": "2017-07-18T20:53:02.000Z",
- "status": "published"
}
], - "start": 0,
- "total_size": 100
}
This endpoint is used to retrieve the information for the specified landing page.
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
landingPageId required | string <uuid> The landing page ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/landing_pages/{landingPageId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "content_html": "<html><h1>Title</h1><body>Landing Page Text</body></html>",
- "published_html": "<html><h1>Title</h1><body>Landing Page Text</body></html>",
- "created_at": "2017-07-18T20:53:02.000Z",
- "id": "48b38cd9-a5df-4297-8987-ed31b3093b39",
- "modified_at": "2017-07-18T20:53:02.000Z",
- "name": "My Awesome Landing Page",
- "published_at": "2017-07-18T20:53:02.000Z",
- "status": "published"
}
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.
list.read
) accountId required | integer <int32> The account ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "draft_broadcasts_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=draft",
- "scheduled_broadcasts_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=scheduled",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 456,
- "name": "Weekly Newsletter",
- "total_subscribed_subscribers": 250,
- "total_subscribers": 275,
- "total_subscribers_subscribed_today": 4,
- "total_subscribers_subscribed_yesterday": 3,
- "total_unconfirmed_subscribers": 10,
- "total_unsubscribed_subscribers": 5,
- "unique_list_id": "awlist456",
- "uuid": "123e4567-e89b-12d3-a456-426655440000",
- "vapid_public_key": "BEJSWW8eHj_XKHt5AHpaL3tw0gee8NI2j06xyEIDmOfRGbHmqZVlwsvMO0yISFe834TaBEZRkbdHyTvSXhYCW6E",
- "web_form_split_tests_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests",
}
], - "start": 0,
- "total_size": 100
}
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "draft_broadcasts_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=draft",
- "scheduled_broadcasts_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=scheduled",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 456,
- "name": "Weekly Newsletter",
- "total_subscribed_subscribers": 250,
- "total_subscribers": 275,
- "total_subscribers_subscribed_today": 4,
- "total_subscribers_subscribed_yesterday": 3,
- "total_unconfirmed_subscribers": 10,
- "total_unsubscribed_subscribers": 5,
- "unique_list_id": "awlist456",
- "uuid": "123e4567-e89b-12d3-a456-426655440000",
- "vapid_public_key": "BEJSWW8eHj_XKHt5AHpaL3tw0gee8NI2j06xyEIDmOfRGbHmqZVlwsvMO0yISFe834TaBEZRkbdHyTvSXhYCW6E",
- "web_form_split_tests_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests",
}
list.read
) accountId required | integer <int32> The account ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "entries": [
- {
- "draft_broadcasts_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=draft",
- "scheduled_broadcasts_link": "https://api.aweber.com/1.0/accounts/123/lists/456/broadcasts?status=scheduled",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 456,
- "name": "Weekly Newsletter",
- "total_subscribed_subscribers": 250,
- "total_subscribers": 275,
- "total_subscribers_subscribed_today": 4,
- "total_subscribers_subscribed_yesterday": 3,
- "total_unconfirmed_subscribers": 10,
- "total_unsubscribed_subscribers": 5,
- "unique_list_id": "awlist456",
- "uuid": "123e4567-e89b-12d3-a456-426655440000",
- "vapid_public_key": "BEJSWW8eHj_XKHt5AHpaL3tw0gee8NI2j06xyEIDmOfRGbHmqZVlwsvMO0yISFe834TaBEZRkbdHyTvSXhYCW6E",
- "web_form_split_tests_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests",
}
], - "start": 0,
}
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.
This endpoint is used to get a paginated collection of list segments.
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/segments \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "id": 1,
- "is_split_test": false,
- "name": "All Subscribers",
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/segments?ws.start=10&ws.size=10",
- "start": 0,
- "total_size": 100
}
This endpoint is used to retrieve the information for the specified segment.
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
segmentId required | integer <int32> The segment ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/segments/{segmentId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "id": 1,
- "is_split_test": false,
- "name": "All Subscribers",
}
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.
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:
subscriber.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "ad_tracking": "ebook",
- "area_code": 555,
- "city": "Chalfont",
- "country": "United States",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "dma_code": 504,
- "id": 789,
- "ip_address": "204.194.222.28",
- "is_verified": true,
- "last_followup_message_number_sent": 0,
- "last_followup_sent_at": "2015-12-17T14:06:26.861089-05:00",
- "latitude": 37.751,
- "longitude": -97.822,
- "misc_notes": "ebook",
- "name": "John Doe",
- "postal_code": "99999-9999",
- "region": "PA",
- "status": "subscribed",
- "subscribed_at": "2015-10-13T16:19:20-04:00",
- "subscription_method": "api",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "unsubscribe_method": "unsubscribe link",
- "unsubscribed_at": "2017-10-13T10:41:43.300889-04:00",
- "verified_at": "2015-10-13T16:19:53"
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/messages?ws.start=1&ws.size=100",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/messages?ws.start=1&ws.size=100",
- "start": 0,
- "total_size": 100
}
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:
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
update_existing | string Enum: "true" "false" If this parameter is present and set to
|
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. |
The subscriber was created successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
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.
The requested list could not be found
The request has been blocked
The request entity has a media type that is not application/x-www-form-urlencoded or application/json
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "ad_tracking": "ebook",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "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": [
- "slow",
- "fast",
- "lightspeed"
]
}
{- "error": {
- "message": "Missing required argument(s)",
- "status": 400,
- "type": "BadRequestError"
}
}
This endpoint is used to update the information for the specified subscriber by email.
Check out related examples:
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriber_email required | string <email> [ 1 .. 50 ] characters The subscriber's email address |
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.
|
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. |
strict_custom_fields | string Enum: "true" "false" If this parameter is present and set to |
tags | object An object with the keys "add" and/or "remove" and values of lists of tags |
The subscriber was updated successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request entity has a media type that is not application/x-www-form-urlencoded or application/json
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "ad_tracking": "ebook",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "last_followup_message_number_sent": 0,
- "misc_notes": "Open House 2015",
- "name": "John Doe",
- "status": "subscribed",
- "strict_custom_fields": "true",
- "tags": {
- "add": [
- "fast",
- "lightspeed"
], - "remove": [
- "slow"
]
}
}
{- "ad_tracking": "ebook",
- "area_code": 555,
- "city": "Chalfont",
- "country": "United States",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "dma_code": 504,
- "id": 789,
- "ip_address": "204.194.222.28",
- "is_verified": true,
- "last_followup_message_number_sent": 0,
- "last_followup_sent_at": "2015-12-17T14:06:26.861089-05:00",
- "latitude": 37.751,
- "longitude": -97.822,
- "misc_notes": "ebook",
- "name": "John Doe",
- "postal_code": "99999-9999",
- "region": "PA",
- "status": "subscribed",
- "subscribed_at": "2015-10-13T16:19:20-04:00",
- "subscription_method": "api",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "unsubscribe_method": "unsubscribe link",
- "unsubscribed_at": "2017-10-13T10:41:43.300889-04:00",
- "verified_at": "2015-10-13T16:19:53"
}
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:
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriber_email required | string <email> [ 1 .. 50 ] characters The subscriber's email address |
The subscriber was deleted successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested subscriber resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -X DELETE \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers \ -d '[email protected]' -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "error": {
- "message": "Required parameter 'oauth_nonce' missing",
- "status": 400,
- "type": "BadRequestError"
}
}
This endpoint is used to update the information for the specified subscriber by ID
Check out related examples:
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriberId required | integer <int32> The subscriber ID |
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.
|
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. |
strict_custom_fields | string Enum: "true" "false" If this parameter is present and set to |
tags | object An object with the keys "add" and/or "remove" and values of lists of tags |
The subscriber was updated successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request entity has a media type that is not application/x-www-form-urlencoded or application/json
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "ad_tracking": "ebook",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "last_followup_message_number_sent": 0,
- "misc_notes": "Open House 2015",
- "name": "John Doe",
- "status": "subscribed",
- "strict_custom_fields": "true",
- "tags": {
- "add": [
- "fast",
- "lightspeed"
], - "remove": [
- "slow"
]
}
}
{- "ad_tracking": "ebook",
- "area_code": 555,
- "city": "Chalfont",
- "country": "United States",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "dma_code": 504,
- "id": 789,
- "ip_address": "204.194.222.28",
- "is_verified": true,
- "last_followup_message_number_sent": 0,
- "last_followup_sent_at": "2015-12-17T14:06:26.861089-05:00",
- "latitude": 37.751,
- "longitude": -97.822,
- "misc_notes": "ebook",
- "name": "John Doe",
- "postal_code": "99999-9999",
- "region": "PA",
- "status": "subscribed",
- "subscribed_at": "2015-10-13T16:19:20-04:00",
- "subscription_method": "api",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "unsubscribe_method": "unsubscribe link",
- "unsubscribed_at": "2017-10-13T10:41:43.300889-04:00",
- "verified_at": "2015-10-13T16:19:53"
}
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:
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriberId required | integer <int32> The subscriber ID |
The subscriber was deleted successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested subscriber resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -X DELETE \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "error": {
- "message": "Required parameter 'oauth_nonce' missing",
- "status": 400,
- "type": "BadRequestError"
}
}
This endpoint is used to retrieve the information for the specified subscriber. Check out related examples:
subscriber.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriberId required | integer <int32> The subscriber ID |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "ad_tracking": "ebook",
- "area_code": 555,
- "city": "Chalfont",
- "country": "United States",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "dma_code": 504,
- "id": 789,
- "ip_address": "204.194.222.28",
- "is_verified": true,
- "last_followup_message_number_sent": 0,
- "last_followup_sent_at": "2015-12-17T14:06:26.861089-05:00",
- "latitude": 37.751,
- "longitude": -97.822,
- "misc_notes": "ebook",
- "name": "John Doe",
- "postal_code": "99999-9999",
- "region": "PA",
- "status": "subscribed",
- "subscribed_at": "2015-10-13T16:19:20-04:00",
- "subscription_method": "api",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "unsubscribe_method": "unsubscribe link",
- "unsubscribed_at": "2017-10-13T10:41:43.300889-04:00",
- "verified_at": "2015-10-13T16:19:53",
- "uuid": "123e4567-e89b-12d3-a456-426655440000"
}
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
Check out related examples:
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriberId required | integer <int32> The subscriber ID |
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" |
The subscriber was moved successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
A request method is not supported for the requested resource
The request has been blocked
The request entity has a media type that is not application/x-www-form-urlencoded or application/json
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "error": {
- "message": "Missing required argument(s)",
- "status": 400,
- "type": "BadRequestError"
}
}
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:
subscriber.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
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) |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Request Subscriber Data permission
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "entries": [
- {
- "ad_tracking": "ebook",
- "area_code": 555,
- "city": "Chalfont",
- "country": "United States",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "dma_code": 504,
- "id": 789,
- "ip_address": "204.194.222.28",
- "is_verified": true,
- "last_followup_message_number_sent": 0,
- "last_followup_sent_at": "2015-12-17T14:06:26.861089-05:00",
- "latitude": 37.751,
- "list_name": "Test List",
- "longitude": -97.822,
- "misc_notes": "ebook",
- "name": "John Doe",
- "postal_code": "99999-9999",
- "region": "PA",
- "status": "subscribed",
- "subscribed_at": "2015-10-13T16:19:20-04:00",
- "subscription_method": "api",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "unsubscribe_method": "unsubscribe link",
- "unsubscribed_at": "2017-10-13T10:41:43.300889-04:00",
- "verified_at": "2015-10-13T16:19:53"
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/subscribers?ws.op=find&ws.start=1&ws.size=100",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/subscribers?ws.op=find&ws.start=1&ws.size=100",
- "start": 0,
}
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:
subscriber.read
) accountId required | integer <int32> The account ID |
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) |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
Forbidden due to rate limit or missing Request Subscriber Data permission
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "entries": [
- {
- "ad_tracking": "ebook",
- "area_code": 555,
- "city": "Chalfont",
- "country": "United States",
- "custom_fields": {
- "apple": "fuji",
- "pear": "bosc"
}, - "dma_code": 504,
- "id": 789,
- "ip_address": "204.194.222.28",
- "is_verified": true,
- "last_followup_message_number_sent": 0,
- "last_followup_sent_at": "2015-12-17T14:06:26.861089-05:00",
- "latitude": 37.751,
- "list_name": "Test List",
- "longitude": -97.822,
- "misc_notes": "ebook",
- "name": "John Doe",
- "postal_code": "99999-9999",
- "region": "PA",
- "status": "subscribed",
- "subscribed_at": "2015-10-13T16:19:20-04:00",
- "subscription_method": "api",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "unsubscribe_method": "unsubscribe link",
- "unsubscribed_at": "2017-10-13T10:41:43.300889-04:00",
- "verified_at": "2015-10-13T16:19:53"
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/messages?ws.start=1&ws.size=100",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/campaigns/b789/messages?ws.start=1&ws.size=100",
- "start": 0,
- "total_size_link": "https://api.aweber.com/1.0/accounts/123?ws.op=findSubscribers&ws.show=total_size"
}
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:
subscriber.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
subscriberId required | integer <int32> The subscriber ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/subscribers/{subscriberId} \ -d ws.op=getActivity \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": {
- "event_time": "2015-07-31T15:36:34.000Z",
- "http_etag": "abd5e0fcbab9073cf861271845859008a7e1c750-ca5feee2b7fbb6febfca8af5541541ea960aaedb",
- "id": 2701,
- "type": "subscribed"
}, - "start": 0,
- "total_size_link": "string",
}
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:
subscriber.read
subscriber.write
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The event was accepted and is being processed.
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The request has been blocked
The request entity has a media type that is not application/x-www-form-urlencoded or application/json
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
{- "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": {
- "apple": "fuji",
- "pear": "bosc"
}, - "ip_address": "204.194.222.28",
- "misc_notes": "ebook",
- "name": "John Doe",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
]
}
{- "error": {
- "message": "Missing required argument(s)",
- "status": 400,
- "type": "BadRequestError"
}
}
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.
list.read
) accountId required | integer <int32> The account ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId} \ -d ws.op=getWebForms \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "conversion_percentage": 6.451612903225806,
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 234,
- "is_active": true,
- "name": "Joker's Wild",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "total_displays": 123456789,
- "total_submissions": 123456,
- "total_unique_displays": 1234,
- "type": "exitpopup",
- "unique_conversion_percentage": 6.451612903225806
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_forms?ws.start=0&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_forms?ws.start=10&ws.size=10",
- "start": 0,
- "total_size": 100
}
list.read
) accountId required | integer <int32> The account ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId} \ -d ws.op=getWebFormSplitTests \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "components_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests/789/components",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 234,
- "is_active": true,
- "name": "Joker's Wild Split Test",
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests?ws.start=10&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests?ws.start=0",
- "start": 0,
- "total_size": 100
}
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_forms \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "conversion_percentage": 6.451612903225806,
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 234,
- "is_active": true,
- "name": "Joker's Wild",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "total_displays": 123456789,
- "total_submissions": 123456,
- "total_unique_displays": 1234,
- "type": "exitpopup",
- "unique_conversion_percentage": 6.451612903225806
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_forms?ws.start=0&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_forms?ws.start=10&ws.size=10",
- "start": 0,
- "total_size": 100
}
accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
webformId required | integer <int32> The webform ID |
The request completed successfully
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_forms/{webformId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "conversion_percentage": 6.451612903225806,
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 234,
- "is_active": true,
- "name": "Joker's Wild",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "total_displays": 123456789,
- "total_submissions": 123456,
- "total_unique_displays": 1234,
- "type": "exitpopup",
- "unique_conversion_percentage": 6.451612903225806
}
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "components_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests/789/components",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 234,
- "is_active": true,
- "name": "Joker's Wild Split Test",
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests?ws.start=10&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests?ws.start=0",
- "start": 0,
- "total_size": 100
}
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
splitTestId required | integer <int32> The webform split test ID |
The request completed successfully
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId} \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "components_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests/789/components",
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": 234,
- "is_active": true,
- "name": "Joker's Wild Split Test",
}
list.read
) accountId required | integer <int32> The account ID |
listId required | integer <int32> The list ID |
splitTestId required | integer <int32> The webform split test ID |
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 |
The request completed successfully
The server cannot or will not process the request due to a client error
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
curl -G \ https://api.aweber.com/1.0/accounts/{accountId}/lists/{listId}/web_form_split_tests/{splitTestId}/components \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
{- "entries": [
- {
- "conversion_percentage": 0,
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": "234-456",
- "is_active": true,
- "name": "Joker's Wild",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "total_displays": 123456789,
- "total_submissions": 123456,
- "total_unique_displays": 1234,
- "type": "exitpopup",
- "unique_conversion_percentage": 6.451612903225806,
- "weight": 40
}
], - "next_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests/789/components?ws.start=10&ws.size=10",
- "prev_collection_link": "https://api.aweber.com/1.0/accounts/123/lists/456/web_form_split_tests/789/components?ws.start=0",
- "start": 0,
- "total_size": 100
}
list.read
) 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 |
The request completed successfully
The request could not be completed due to an authentication error
The request could not be completed due to a rate limit error
The requested resource could not be found
The method received in the request-line is known by the origin server but not supported by the target resource.
The request has been blocked
The request failed due to an internal error in the code or because of an external dependency failure
The server is currently unavailable
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}'
{- "conversion_percentage": 0,
- "http_etag": "\\\"902ba3cda1883801594b6e1b452790cc53948fda-f83cb0ac22a8d5f792417f9b3dc0e9dc7558aa32\\\"",
- "id": "234-456",
- "is_active": true,
- "name": "Joker's Wild",
- "tags": [
- "slow",
- "fast",
- "lightspeed"
], - "total_displays": 123456789,
- "total_submissions": 123456,
- "total_unique_displays": 1234,
- "type": "exitpopup",
- "unique_conversion_percentage": 6.451612903225806,
- "weight": 40
}
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:
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.
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.
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).
Click on your integration in the list of connected integrations.
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.
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.
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.
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 stringdate_header_value
is the value of the Date
request headerrequest_body
is the full HTTP request bodyGiven 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.
The following Python script implements webhook verification. It defines these variables:
request_headers
: a dictionary mapping HTTP request headers to their valuesrequest_body
: the full HTTP request bodykey_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!')
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.
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. |
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 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.
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:
|
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:
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. |
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
}
}
]
}
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:
|
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:
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. |
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"
}
}
]
}
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:
|
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:
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. |
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"
}
}
]
}
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.
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.
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
subscriber.subscribed
and subscriber.unsubscribed
events.subscriber.added
event.labs.aweber.com/docs/troubleshooting
to use api.aweber.com
company
field to the Account endpoints.uuid
field to the Subscriber entry endpoint response.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.http_etag
field from the Campaigns endpoints.vapid_public_key
field to the Lists endpoints.uuid
field to the Accounts endpoints.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.400 WebServiceError
will be returned for all invalid values.update_existing
parameter to the POST Subscriber endpoint. Please see the endpoint documentation for details.uuid
field to the Lists endpoints.body_amp
field in the Broadcasts endpoints is no longer in BETA.redirect_uri
value of urn:ietf:wg:oauth:2.0:oob
.
Documentation for it can be found in the Authentication Overview.analytics_src
to the Accounts endpoints. analytics_src
is used for event tracking on a website. See our
knowledge base article for more details.tags_not_in
as a search filter for Find Subscribers for List and Find Subscribers for Accountbody_amp
to Broadcasts endpoints as a BETA feature.sort_key
with value subscribed_at
or unsubscribed_at
.
This will sort the results by that key and the direction specified by sort_order
.BroadcastSchedulingError
when updating fails due to broadcast status or the account being locked.BroadcastSchedulingError
when deleting fails due to broadcast status or the account being locked.admin_hold
and sending
. This affects the following endpoints:
subscribed_before
, subscribed_after
,
unsubscribed_before
, and unsubscribed_after
as search parameters.include_lists
and exclude_lists
as update parameters.subscribed_before
, subscribed_after
,
unsubscribed_before
, and unsubscribed_after
as search parameters.scheduled_for
in Schedule Broadcast request.draft_broadcasts_link
, scheduled_broadcasts_link
and sent_broadcasts_link
. 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.
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.
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.
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.
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.
AWeber API requests are limited to 120 requests per minute, per customer account.
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.
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.
redirect_uri
exactly matches the OAuth Redirect URL
specified for your application.These errors are raised when you try to authorize a public application, but do not include a code_challenge
in your original request.
These errors are raised when you try to authorize a confidential application and include a code_verifier
, challenge
,
or challenge_method
in your request
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:
Here is a sample API error response:
{"error":
{"status": 401,
"message": "Consumer key is invalid.",
"type": "UnauthorizedError",
"documentation_url": "https://api.aweber.com"}}
body_text
or body_html
must always be included.AWeber API Authentication
RFC5849 OAuth 2.0 Specification
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.
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.
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.
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.
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.
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.
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.
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.
This error is raised when the POST or PUT request length exceeds 1 million bytes of data when creating a broadcast message.
This error is raised when the subscriber email address is not currently acceptable.
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
This error is raised when the API experiences an internal error.
This error is raised when the API is down for maintenance.
A 204 No Content status is returned when an API resource was successfully updated and there is no content to return.
A 209 Content Modified status is returned along with a JSON representation when an API resource was successfully updated with an HTTP PATCH request.