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

List of Operations¶

POST /sendroll/api/v1/advertisables/(advertisable_eid)/campaign
GET /sendroll/api/v1/advertisables/(advertisable_eid)/messages
POST /sendroll/api/v1/advertisables/(advertisable_eid)/messages
POST /sendroll/api/v1/advertisables/(advertisable_eid)/opt-out
PATCH /sendroll/api/v1/advertisables/(advertisable_eid)/sender_info
GET /sendroll/api/v1/advertisables/(advertisable_eid)/settings
PATCH /sendroll/api/v1/advertisables/(advertisable_eid)/settings
GET /sendroll/api/v1/advertisables/(advertisable_eid)/unsubscribers
POST /sendroll/api/v1/advertisables/(advertisable_eid)/unsubscribers
PATCH /sendroll/api/v1/campaigns/(campaign_eid)/
GET /sendroll/api/v1/campaigns/(campaign_eid)/emails
PATCH /sendroll/api/v1/campaigns/(campaign_eid)/emails
PUT /sendroll/api/v1/campaigns/(campaign_eid)/status
GET /sendroll/api/v1/(advertisable_eid)/activation_status

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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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: paused, running

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 Personal Access Tokens (PAT). 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