AdRoll Email API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use, AdRoll Email Services Addendum and AdRoll Services Privacy Note

Note

We’ve introduced API keys, please read Migrating to API Keys

Description

AdRoll Email API v1 by AdRoll

External documentation

AdRoll API Documentation

Operations

POST /sendroll/api/v1/advertisables/(advertisable_eid)/campaign

Creates a new SendRoll campaign with the given data.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "emails": [
    {
      "body": "string", 
      "cta_destination": "string", 
      "cta_label": "string", 
      "delay_hours": 0, 
      "email_subject": "string", 
      "headline": "string", 
      "hero_image_url": "string"
    }
  ], 
  "end_date": "string", 
  "footer_postal_address": "string", 
  "sender_address": "string", 
  "sender_name": "string", 
  "source": "string", 
  "start_date": "string"
}
Schema
Type:object
end_date

Date and time in which the campaign should stop sending emails. In "YYYY-MM-DDThh:mm:ss" format. Can not be before the start date if it is set. Defaults to never.

Type:string
Format:date-time
sender_name

The name of the email sender.

Type:string
emails

Optional campaign email content.

Type:array of CampaignEmailRegister
sender_address

The email address of the sender.

Type:string
source

The identity of the service that triggers the creation of this campaign.

Type:string
footer_postal_address

The legal mailing address of the sender.

Type:string
start_date

Date and time in which the campaign should start sending emails. In "YYYY-MM-DDThh:mm:ss" format. Can not be in the past or after the end_date if it is set. Defaults to immediately when the status changes to ‘running’.

Type:string
Format:date-time

Responses:

200 OK

Campaign was created successfully.

Schema as JSON:

{
  "eid": "Unknown type"
}
Schema
Type:object
eid

The EID for the newly created campaign.

400 Bad Request

One or more parameters are invalid.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
401 Unauthorized

Action not allowed for this user.

Returns ErrorObjectResponse

403 Forbidden

Action not allowed for this user.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
416 Requested Range Not Satisfiable

The given start/end dates are invalid.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
GET /sendroll/api/v1/advertisables/(advertisable_eid)/messages

Endpoint to manage current advertisable alerts similar to AdRoll’s /events/ API.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string A valid Advertisable EID.
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Active messages object.

Schema as JSON:

{
  "results": [
    {
      "created_date": "string", 
      "type": "string", 
      "viewed": true
    }
  ]
}
Schema
Type:object
results
Type:array of AdvertisableMessages
401 Unauthorized
Action not allowed for this user.
POST /sendroll/api/v1/advertisables/(advertisable_eid)/messages

Endpoint to manage current advertisable alerts similar to AdRoll’s /events/ API.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string A valid Advertisable EID.
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Active messages object.

Schema as JSON:

{
  "results": [
    {
      "created_date": "string", 
      "type": "string", 
      "viewed": true
    }
  ]
}
Schema
Type:object
results
Type:array of AdvertisableMessages
401 Unauthorized
Action not allowed for this user.
POST /sendroll/api/v1/advertisables/(advertisable_eid)/opt-out

Endpoint that allows an admin or an advertisable owner to deactivate (Join Beta + Reject TOS) an advertisable.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string The advertisable that will be deactivated.
Query Parameters
Name Required Type Description
agent False string Provide a meaningful identification of the service that triggered the opt out.
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Success

Returns SuccessfulActionResponse

400 Bad Request
The agent parameter is missing.
401 Unauthorized
Action not allowed for this user.
PATCH /sendroll/api/v1/advertisables/(advertisable_eid)/sender_info

Updates the sender info for the advertisable.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "footer_postal_address": "string", 
  "sender_address": "string", 
  "sender_name": "string"
}
Schema
Type:object
sender_address

The email address of the sender.

Type:string
footer_postal_address

The legal mailing address of the sender.

Type:string
sender_name

The name of the email sender.

Type:string

Responses:

200 OK

Success

Returns SuccessfulActionResponse

401 Unauthorized
Action not allowed for this user.
GET /sendroll/api/v1/advertisables/(advertisable_eid)/settings

Gets or updates the settings for the advertisable.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Settings for given advertisable.

Schema as JSON:

{
  "country": "string", 
  "footer_postal_address": "string", 
  "sender_address": "string", 
  "sender_name": "string"
}
Schema
Type:object
sender_address

Email sender’s address.

Type:string
country

ISO-3166 country code for advertisable.

Type:string
sender_name

Email sender’s name.

Type:string
footer_postal_address

Legal postal address for email footer.

Type:string
401 Unauthorized
Action not allowed for this user.
404 Not Found
Specified advertisable is not known to AdRoll Email
PATCH /sendroll/api/v1/advertisables/(advertisable_eid)/settings

Gets or updates the settings for the advertisable.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "country": "string"
}
Schema
Type:object
country

ISO-3166 country code for advertisable.

Type:string

Responses:

200 OK

Success

Returns SuccessfulActionResponse

401 Unauthorized
Action not allowed for this user.
404 Not Found
Specified advertisable is not known to AdRoll Email
GET /sendroll/api/v1/advertisables/(advertisable_eid)/unsubscribers

Provides a list of unsubscribed email addresses for the given Advertisable.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string The advertisable referenced in this request.
Query Parameters
Name Required Type Description
since False string UTC timestamp "YYYY-MM-DDThh:mm:ss". If provided, the endpoint will return only unsubscribers created after this timestamp.
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

All unsubscribers set for the advertisable.

Schema as JSON:

{
  "unsubscribers": [
    {
      "date": "string", 
      "email_address": "string"
    }
  ]
}
Schema
Type:object
unsubscribers

List of unsubscribers.

Type:array of UnsubscriberEmail
POST /sendroll/api/v1/advertisables/(advertisable_eid)/unsubscribers

Records a list of unsubscribed email addresses for the given Advertisable.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string The advertisable referenced in this request.
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

[
  "string"
]
Schema
Type:array

Responses:

200 OK

Success

Schema as JSON:

{
  "ignored": [
    "string"
  ]
}
Schema
Type:object
ignored

A list of strings with the malformed email addresses provided that had to be ignored.

Type:array of items
PATCH /sendroll/api/v1/campaigns/(campaign_eid)/

Update campaign

Parameters:

Path Parameters
Name Required Type Description
campaign_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "end_date": "string", 
  "name": "string", 
  "start_date": "string"
}
Schema
Type:object
name

Name of campaign.

Type:string
end_date

Date and time in which the campaign should stop sending emails. In "YYYY-MM-DDThh:mm:ss" format. Can not be before the start date if it is set. Defaults to never.

Type:string
Format:date-time
start_date

Date and time in which the campaign should start sending emails. In "YYYY-MM-DDThh:mm:ss" format. Can not be in the past or after the end_date if it is set. Defaults to immediately when the status changes to ‘running’.

Type:string
Format:date-time

Responses:

200 OK

Success

Returns SuccessfulActionResponse

400 Bad Request

Invalid campaign source.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
401 Unauthorized
Action not allowed for this user.
416 Requested Range Not Satisfiable

The given start/end dates are invalid.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
GET /sendroll/api/v1/campaigns/(campaign_eid)/emails

Manage campaign emails.

View a campaign’s email data in drip sequence order.

Parameters:

Path Parameters
Name Required Type Description
campaign_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Success

Schema as JSON:

{
  "emails": [
    {
      "content": "string", 
      "delay_hours": 0, 
      "eid": "string", 
      "email_subject": "string", 
      "preview_text": "string", 
      "utm_campaign": "string", 
      "utm_medium": "string", 
      "utm_source": "string"
    }
  ]
}
Schema
Type:object
emails

The emails.

Type:array of CampaignEmailResultRegister
401 Unauthorized
Action not allowed for this user.
PATCH /sendroll/api/v1/campaigns/(campaign_eid)/emails

Manage campaign emails.

Edit specific properties in a campaign’s emails.

Parameters:

Path Parameters
Name Required Type Description
campaign_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

[
  {
    "body": "string", 
    "cta_destination": "string", 
    "cta_label": "string", 
    "delay_hours": 0, 
    "email_subject": "string", 
    "headline": "string", 
    "hero_image_url": "string"
  }
]
Schema
Type:array

Responses:

200 OK

Success

Returns SuccessfulActionResponse

401 Unauthorized
Action not allowed for this user.
413 Request Entity Too Large
More campaign emails were given in body than exist in campaign.
PUT /sendroll/api/v1/campaigns/(campaign_eid)/status

Change a campaign’s status to ‘running’ or ‘paused’.

Parameters:

Path Parameters
Name Required Type Description
campaign_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "status": "string"
}
Schema
Type:object
status
Required:True
Type:string
Enum:paused, running

Responses:

200 OK

Success

Returns SuccessfulActionResponse

400 Bad Request

New campaign status is invalid.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
401 Unauthorized
Action not allowed for this user.
403 Forbidden

Action not allowed for this user.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
404 Not Found
Specified campaign does not exist.
412 Precondition Failed

Campaign launch requirements have not been fulfilled.

Schema as JSON:

[
  {
    "error": "string", 
    "name": "string"
  }
]
Schema
Type:array
GET /sendroll/api/v1/(advertisable_eid)/activation_status

Endpoint that allows a user to check the current status of their TOS acceptance.

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string The advertisable to check activation status.
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Response object.

Schema as JSON:

{
  "terms_accepted": true
}
Schema
Type:object
terms_accepted

true if the advertisable has accepted the current SendRoll terms of service.

Type:boolean
401 Unauthorized
Action not allowed for this user.

Definitions

CampaignEmailRegister
Type:object
body

Body text of the email in the template.

Type:string
headline

Headline of the email in the template.

Type:string
cta_destination

Click URL for CTA button.

Type:string
hero_image_url

URL of hero image to use in the template. The image will be captured and stored on AdRoll servers, within an hour of request, for use at email send time.

Type:string
email_subject

Subject of the email.

Type:string
cta_label

Text of CTA button.

Type:string
delay_hours

Delay in hours between the previous event in the drip sequence and when this email is scheduled to be sent.

Type:integer
SuccessfulActionResponse

Standard success response for a successful action performed through this API.

Type:object
success

Always true.

Type:boolean
UnsubscriberEmail
Type:object
date

The UTC timestamp “YYYY-MM-DDThh:mm:ss” when the unsubscription was created.

Type:string
Format:date-time
email_address

The email address that has been unsubscribed.

Type:string
AdvertisableMessages
Type:object
type

Constant used for ar-navbar to interpret current messages for adv. One of email_unsubscriber, email_pixel, email_forms_new, email_forms_blocked, email_forms_missing

Type:string
viewed

required in ar-navbar to show the message so will always be right now since we only show active alerts/messages.

Type:boolean
created_date

Date in ISO format.

Type:string
Format:date-time string
ErrorObjectResponse

Detailed description of error.

Type:object
name

Name of parameter in error.

Type:string
error

Description of error for parameter.

Type:string
CampaignEmailResultRegister
Type:object
utm_campaign

Email link utm_campaign tracking param.

Type:string
utm_source

Email link utm_source tracking param.

Type:string
content

The email HTML content.

Type:string
utm_medium

Email link utm_medium tracking param.

Type:string
eid

The campaign email EID.

Type:string
email_subject

Subject of the email.

Type:string
preview_text

Email preview text.

Type:string
delay_hours

Delay in hours between the previous event in the drip sequence and when this email is scheduled to be sent.

Type:integer