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.

Endpoints

You can read, update, and create email address audiences using the email address resource.

/traffic/audiences/email_address
  • Use the GET method to retrieve email address audience data.
  • Use the POST method to create new email address audiences.
  • Use the PUT method to update existing email audience audiences.

Resources

The Email Address audience object contains the following fields:

Table 38 Email Address Audience Resource
Field Description Type Add Update
id ID of the audience segment. integer N/A Required
name Name of the segment. string Required Optional
status

Current status of the segment. By default, ACTIVE.

  • ACTIVE
  • INACTIVE
string Optional Optional
accountId Specifies the advertiser ID associated with the audience. To learn more about advertisers see Advertisers. integer Required Required
seedList Specifies an array of email addresses hashed using the SHA256 cyptographic hashing algorthm. array Required Optional
createdAt Specifies the time the audience was created. string N/A N/A

Read Email Address Audience History

Retrieve the history and status of an audience.

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

Parameters

Table 39 Read Email Address Audience History
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

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 Audiences by Audience ID

Retrieves audience data for the specified email address audience.

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

The returns data for the audience segment associated with the specified ID.

Parameters

Table 40 Read Email Address Audience by Account ID 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

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 Audiences

Updates the specified email address audience.

PUT /traffic/audiences/email_address/{id}

Partial updates are supported; fields that are either not passed or passed as null will be ignored during update.

Parameters

Table 41 Update Email Address Audience Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
name body Specifies the name of the audience. string N
status body

Specifies the status of the audience. Options include:

  • ACTIVE, the default value
  • INACTIVE
string N
accountId body Specifies the advertiser ID associated with the audience. number Y
seedList body Specifies an array of email addresses hashed using the SHA256 algorithm. array N

Example Request

The audience ID must be specified in the path.

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

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

{
  "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 Audiences

Creates a new email address audience.

POST /traffic/audiences/email_address

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

Parameters

Table 42 Create Email Address Audience Parameters
Parameter Parameter Type Description Data Type Required
name body Specifies the name of the audience. string Y
status body

Specifies the status of the audience. Options include:

  • ACTIVE, the default value
  • INACTIVE
string N
accountId body Specifies the advertiser ID associated with the audience. number Y
seedList body Specifies an array of email addresses in the SHA256 format. array Y

Example Request

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

Example Payload

{
  "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 Audiences

Audience deletion is not supported by the API.