Email Address Audiences

This article describes resources and services that enable you to read, create, and update email address audiences.

Overview

An email address audience is a custom audience you create by providing email addresses.

Note

You can only build an email address audience for one advertiser at a time, not for an entire seat.

Hierarchy

An Email Address audience can be defined at the advertiser-level.

  • Advertiser-level audiences are specific to a single advertiser account.

Endpoint

/traffic/audiences/email_address

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read an existing email address audience.
  • Use the POST method to create a new email address audience.
  • Use the PUT method to update an existing email address audience.

Resources

The Email Address audience object contains the following fields:

Table 36 Email Address Audience Fields
Field Description Data Type Create Update
id Specifies the audience ID. integer N/A Required
name Specifies the name of the audience. string Required Optional
status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: the audience can be targeted.
  • INACTIVE: the audience cannot be targeted.
[1]If not specified when creating the audience, defaults to ACTIVE.
string Optional [1] Optional
accountId

Specifies the advertiser ID.

The audience is tied to a specific advertiser and can only be used in that advertisers’ campaigns. To learn more, see Advertisers.

integer Required Required
seedList Specifies an array of email addresses hashed using the SHA256 cyptographic hashing algorthm. array Required Optional
createdAt A read-only field that specifies when the audience was created. string N/A N/A

Read Email Address Audience History

Get the history and status of an email address audience.

GET /traffic/audiences/email_address/{id}/history?accountId={accountId}

Parameters

Table 37 Read Email Address Audience History Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser ID associated with the audience. number Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/email_address/50346201/history?accountId=1356341

Example Response

{
  "response": [
    {
      "id": "AUDAP_Email_20171020T2233502619009",
      "status": "Active",
      "failPercentage": 0,
      "type": "SHA1EMAIL",
      "createdDate": "2017-10-20T22:33:50",
      "errorMessage": "",
      "failedRecords": [],
      "totalIds": 1,
      "duplicated": 0,
      "totalFailed": 0
    }
  ],
  "errors": null,
  "timeStamp": "2018-09-04T19:04:38Z"
}

Read Email Address Audience

Get data for a specific Email Address audience.

GET traffic/audiences/email_address/{id}?accountId={accountId}

Parameters

Table 38 Read Email Address Audience Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser ID. number Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/email_address/50351924?accountId=1356341

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 50351924,
    "name": "audienceTest",
    "accountId": 1356341,
    "createdAt": "2017-10-20",
    "retentionDays": 730
  },
  "errors": null,
  "timeStamp": "2017-10-20T19:04:17Z"
}

Update Email Address Audience

Update an existing email address audience.

PUT /traffic/audiences/email_address/{id}

Partial updates are supported; values of supported fields which are not in the payload will remain unchanged.

Parameters

The audience id is specified in the endpoint path. All other fields are specified in the body of the application/json payload.

Example Request URL

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/email_address/50351924

Example Request Body

{
  "name": "audienceTest_2",
  "accountId": 1356341
}

Example Response

{
  "response": {
    "id": 50351924,
    "name": "audienceTest_2",
    "status": "ACTIVE",
    "accountId": 1356341,
    "retentionDays": 730
  },
  "errors": null,
  "timeStamp": "2017-10-20T19:23:53Z"
}

Create Email Address Audience

Create a new email address audience.

POST /traffic/audiences/email_address

Parameters

All parameters are specified in the body of the application/json payload.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/email_address

Example Request Body

{
  "name": "audience3",
  "accountId": 1356341,
  "seedList": [
    "251014dafc651f68edac7e583edab8ed4fbdbe176b9b4c81f67e9e87a66da103",
    "afbc34416ac6e7fbb97331a21fa2823f56952c0796a615d05a07a08cc52704da",
    "42cbe7eebb412bbcd5b566945df59f67962106041ae7ea39f5bc6ee99307c19e",
    "379b4653a40878da7a58458e4d9a99f834fb12179a5d4e2a840f77dc090c9a98"
  ]
}

Example Response

{
  "response": {
    "id": 50351924,
    "name": "audience3",
    "status": "ACTIVE",
    "accountId": 1356341,
    "retentionDays": 730
  },
  "errors": null,
  "timeStamp": "2017-10-11T00:33:54Z"
}

Delete Email Address Audience

The DSP Traffic API does not support deletion of email address audiences.