Email API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use, Email Service Addendum and Service Privacy Notice

Note

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

Description

AdRoll Email API v1

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 NextRoll Developer site

Schema for request body:

{
  "emails": [
    {
      "body": "string",
      "cta_destination": "string",
      "cta_label": "string",
      "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

emails

Optional campaign email content.

Type

array of CampaignEmailRegister

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

footer_postal_address

The legal mailing address of the sender.

Type

string

sender_address

The email address of the sender.

Type

string

sender_name

The name of the email sender.

Type

string

source

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

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

Campaign was created successfully.

Schema as JSON:

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

object

eid

The EID for the newly created campaign.

400

One or more parameters are invalid.

Schema as JSON:

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

array

403

Action not allowed for this user.

Schema as JSON:

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

array

416

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 NextRoll Developer site

Responses:

200

Active messages object.

Schema as JSON:

{
  "results": [
    {
      "created_date": "string",
      "type": "string",
      "viewed": true
    }
  ]
}
Schema
Type

object

results
Type

array of AdvertisableMessages

403

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 NextRoll Developer site

Responses:

200

Active messages object.

Schema as JSON:

{
  "results": [
    {
      "created_date": "string",
      "type": "string",
      "viewed": true
    }
  ]
}
Schema
Type

object

results
Type

array of AdvertisableMessages

403

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 NextRoll Developer site

Responses:

200

Success

Returns SuccessfulActionResponse

400

The agent parameter is missing.

403

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 NextRoll Developer site

Schema for request body:

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

object

footer_postal_address

The legal mailing address of the sender.

Type

string

sender_address

The email address of the sender.

Type

string

sender_name

The name of the email sender.

Type

string

Responses:

200

Success

Returns SuccessfulActionResponse

403

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 NextRoll Developer site

Responses:

200

Settings for given advertisable.

Schema as JSON:

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

object

country

ISO-3166 country code for advertisable.

Type

string

footer_postal_address

Legal postal address for email footer.

Type

string

sender_address

Email sender’s address.

Type

string

sender_name

Email sender’s name.

Type

string

403

Action not allowed for this user.

404

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 NextRoll Developer site

Schema for request body:

{
  "country": "string"
}
Schema
Type

object

country

ISO-3166 country code for advertisable.

Type

string

Responses:

200

Success

Returns SuccessfulActionResponse

403

Action not allowed for this user.

404

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 NextRoll Developer site

Responses:

200

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 NextRoll Developer site

Schema for request body:

[
  "string"
]
Schema
Type

array

Responses:

200

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 NextRoll Developer site

Schema for request body:

{
  "end_date": "string",
  "name": "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

name

Name of campaign.

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

Success

Returns SuccessfulActionResponse

400

Invalid campaign source.

Schema as JSON:

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

array

403

Action not allowed for this user.

416

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 NextRoll Developer site

Responses:

200

Success

Schema as JSON:

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

object

emails

The emails.

Type

array of CampaignEmailResultRegister

403

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 NextRoll Developer site

Schema for request body:

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

array

Responses:

200

Success

Returns SuccessfulActionResponse

403

Action not allowed for this user.

413

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 NextRoll Developer site

Schema for request body:

{
  "status": "string"
}
Schema
Type

object

status
Required

True

Type

string

Enum

running, paused

Responses:

200

Success

Returns SuccessfulActionResponse

400

New campaign status is invalid or campaign launch requirements have not been fulfilled.

Schema as JSON:

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

array

403

Action not allowed for this user.

404

Specified campaign does not exist.

422

Campaign is stopped and cannot be restarted.

Schema as JSON:

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

array

423

The advertisable is suspended.

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 NextRoll Developer site

Responses:

200

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

403

Action not allowed for this user.

Definitions

AdvertisableMessages
Type

object

created_date

Date in ISO format.

Type

string

Format

date-time string

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

CampaignEmailRegister
Type

object

body

Body text of the email in the template.

Type

string

cta_destination

Click URL for CTA button.

Type

string

cta_label

Text of CTA button.

Type

string

email_subject

Subject of the email.

Type

string

headline

Headline of the email in the template.

Type

string

hero_image_url

URL of hero image to use in the template.

Type

string

CampaignEmailResultRegister
Type

object

content

The email HTML content.

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

eid

The campaign email EID.

Type

string

email_subject

Subject of the email.

Type

string

preview_text

Email preview text.

Type

string

scheduled_date

Date -in "YYYY-MM-DDTHH:MM:SS" format- the date that this email is scheduled to be sent, if any.

Type

string

Format

date-time

utm_campaign

Email link utm_campaign tracking param.

Type

string

utm_medium

Email link utm_medium tracking param.

Type

string

utm_source

Email link utm_source tracking param.

Type

string

ErrorObjectResponse

Detailed description of error.

Type

object

error

Description of error for parameter.

Type

string

name

Name of parameter in error.

Type

string

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