Email Address Audiences

This article describes resources and services you can use to view, create, and update email address audiences.

Overview

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

Hierarchy

You define an Email Address audience at the advertiser level.

Endpoint

/traffic/audiences/email_address

Use the following HTTP methods:

  • Use the GET method to view 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:

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: you can target the audience.

  • INACTIVE: you cannot target the audience.

Defaults to ACTIVE if you don’t specify a value.

string

Optional

Optional

accountId

Specifies the advertiser ID.

An audience is tied to its advertiser and you can only use it in that advertiser’s 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

View Audience

View an email address audience.

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

Parameters

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the audience ID.

integer

Y

accountId

query

Specifies the advertiser ID.

integer

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"
}

View History

Get the history and status of an email address audience.

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

Parameters

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the audience ID.

integer

Y

accountId

query

Specifies the advertiser ID.

integer

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"
}

Create Audience

Create a new email address audience.

POST /traffic/audiences/email_address

Parameters

All fields 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,
    "createdAt": "2017-10-11",
    "retentionDays": 730
  },
  "errors": null,
  "timeStamp": "2017-10-11T00:33:54Z"
}

Update Audience

Update an existing email address audience.

PUT /traffic/audiences/email_address/{id}

Partial updates are supported; values of supported fields that are not in the payload 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,
    "createdAt": "2017-10-20",
    "retentionDays": 730
  },
  "errors": null,
  "timeStamp": "2017-10-20T19:23:53Z"
}

Delete Audience

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