SendRoll API Reference

Note

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

Description

SendRoll API v1 by AdRoll

External documentation

AdRoll API Documentation

Operations

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.

Responses:

200 OK

Success

Returns SuccessfulActionResponse

400 Bad Request
The agent parameter is missing.
401 Unauthorized
Action not allowed for this user.
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.

Responses:

200 OK

Response object.

Sample response:

{
  "terms_accepted": true
}

Response schema:

Schema-0
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.
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  

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-1

Responses:

200 OK

Campaign was created successfully.

Sample response:

{
  "eid": "Unknown type"
}

Response schema:

Schema-2
Type:object
eid

The EID for the newly created campaign.

400 Bad Request

One or more parameters are invalid.

Sample response:

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

Response schema:

Schema-3
Type:array
401 Unauthorized
Action not allowed for this user.
403 Forbidden

Action not allowed for this user.

Sample response:

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

Response schema:

Schema-4
Type:array
PATCH /sendroll/api/v1/campaigns/(campaign_eid)/

Update campaign

Parameters:

Path Parameters
Name Required Type Description
campaign_eid True string  

Schema for request body:

{
  "end_date": "string", 
  "name": "string", 
  "start_date": "string"
}
string

Responses:

200 OK

Success

Returns SuccessfulActionResponse

416 Requested Range Not Satisfiable

The given start/end dates are invalid.

Sample response:

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

Response schema:

Schema-5
Type:array
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  

Schema for request body:

{
  "footer_postal_address": "string", 
  "sender_address": "string", 
  "sender_name": "string"
}
Schema-6

Responses:

200 OK

Success

Returns SuccessfulActionResponse

401 Unauthorized
Action not allowed for this user.
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  

Schema for request body:

"string"
<built-in method title of str object at 0x2b18eea3b120>
Format:<built-in method format of str object at 0x2b18eea3b120>

Responses:

200 OK

Success

Returns SuccessfulActionResponse

400 Bad Request

New campaign status is invalid.

Sample response:

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

Response schema:

Schema-7
Type:array
401 Unauthorized
Action not allowed for this user.
403 Forbidden

Action not allowed for this user.

Sample response:

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

Response schema:

Schema-8
Type:array
404 Not Found
Specified campaign does not exist.
412 Precondition Failed

Campaign launch requirements have not been fulfilled.

Sample response:

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

Response schema:

Schema-9
Type:array
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.

Responses:

200 OK

All unsubscribers set for the advertisable.

Sample response:

{
  "unsubscribers": [
    {
      "date": "string", 
      "email_address": "string"
    }
  ]
}

Response schema:

Schema-10
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.

Schema for request body:

[
  "string"
]
Schema-11

Responses:

200 OK

Success

Sample response:

{
  "ignored": [
    "string"
  ]
}

Response schema:

Schema-12
Type:object
ignored

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

Type:array of items
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  

Responses:

200 OK

Success

Sample response:

{
  "emails": [
    {
      "content": "string", 
      "eid": "string", 
      "email_subject": "string", 
      "preview_text": "string", 
      "utm_campaign": "string", 
      "utm_medium": "string", 
      "utm_source": "string"
    }
  ]
}

Response schema:

Schema-13
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  

Schema for request body:

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

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.

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
email_subject

Subject of the email.

Type:string
cta_label

Text of CTA button.

Type:string
hero_image_url

URL of hero image to use in the template.

Type:string
ErrorObjectResponse

Detailed description of error.

Type:object
name

Name of parameter in error.

Type:string
error

Description of error for parameter.

Type:string
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
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
SuccessfulActionResponse

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

Type:object
success

Always true.

Type:boolean