Mail Domain Audiences

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

Overview

A mail domain audience is an audience segment that is comprised of Yahoo Mail customers that are associated with one or more email domains. A mail domain audience may include consumers that have received email from one or more specified domains, consumers that have not received email one ore more specified domains, or a combination of the two.

All mail domain audiences are defined by one or more mail domains (domains). Mail domains are grouped together into mail domain categories, which are identified by their categoryIds. The Oath Ad Platforms DSP provides resources that enable you to read these objects as well.

Hierarchy

A Mail Domain audience can be defined at either the seat-level or advertiser-level.

  • Seat-level audiences are shared by every advertiser account in the seat.
  • Advertiser-level audiences are specific to a single advertiser account.

Endpoint

/traffic/audiences/mrt
  • Use the GET method to read an existing mail domain audience.
  • Use the POST method to create a new mail domain audience.
  • Use the PUT method to update an existing mail domain audience.

The Read Mail Domain resource returns mail domain data:

/traffic/audience/domainlookups

The Read Mail Domain Category resource returns domain category data:

/traffic/audience/mrt/categories

Resource

The Mail Domain audience object contains the following fields:

Table 44 Mail Domain 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.

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

[2](1, 2) Required if the audience is defined at the advertiser level.
integer Optional [2] Optional [2]
retentionDays

Specifies the number of retention days, which determines whether consumers are included in the segment based on the date email was received.

Retention days are counted back from the the current date. Allowed values: 3, 4, 5, 7, 10, 14, 15, 21, 30, 45, 60, 90.

[3]If not specified when creating the audience, defaults to 30.
integer Optional [3] Optional
domains

Specifies an array of domains. The audience includes all consumers that have received mail from any of the specified domains. You can search for available domains or provide other values.

The Mail Domains resource enables you to retrieve available domains. To learn more, see Read Mail Domains.

[4]To remove existing values, specify an empty array.
array Optional Optional [4]
excludeDomains

Specifies an array of domains. The consumer is excluded in the audience if they receive mail from any of the specified domains.

The Mail Domains resource enables you to retrieve available domains. To learn more, see Read Mail Domains.

[5]To remove existing values, specify an empty array.
array Optional Optional [5]
categoryIds

Specifies an array of categories. The audience includes all consumers that have received mail from any domain belonging to the specified categories.

The Mail Domains Audience Categories resource enables you to retrieve available mail domain audience categories. To learn more, see Read Mail Domain Categories.

[6]Required if domains or excludeDomains is not specified.
[7]To remove existing values, specify an empty array.
array Optional [6] Optional [7]
createdAt A read-only field that specifies when the audience was created. string N/A N/A

Read Mail Domain Audience

Get data for a specific mail domain audience.

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

Parameters

Table 45 Read Mail Domain Audience Parameters
Parameters Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query

Specifies the advertiser ID.

[8]Required for advertiser-level audiences.
integer N [8]

Example Request URL (Seat-Level)

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/50305006

Example Response (Seat-Level)

{
  "response": {
    "id": 50305006,
    "name": "mail_mrt3303",
    "domains": [
      "yahoo.com"
    ],
    "excludeDomains": [
      "supportnetflixupt.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "categoryIds": [
       1,
       2,
       3
    ],
    "retentionDays": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:30:08Z"
}

Example Request URL (Advertiser-Level)

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/50305018?accountId=1356341

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50305018,
    "name": "mail_mrt33035",
    "accountId": 1356341,
    "domains": [
      "yahoo.com"
    ],
    "excludeDomains": [
      "supportnetflixupt.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "categoryIds": [
       1,
       2,
       3
    ],
    "retentionDays": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:40:44Z"
}

Update Mail Domain Audience

Update an existing mail domain audience.

PUT /traffic/audiences/mrt/{id}

Partial updates are supported for all fields except excludeDomains; 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 (Seat-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/50305006

Example Request Body (Seat-Level)

{
  "domains": [
    "yahoo.com",
    "gmail.com"
  ],
  "categoryIds": [
     7,
     8,
     9
    ]
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50305006,
    "name": "mail_mrt3303",
    "domains": [
      "yahoo.com",
      "gmail.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "categoryIds": [
       7,
       8,
       9
    ],
    "retentionDays": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T22:41:36Z"
}

Example Request URL (Advertiser-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/50305018?accountId=1356341

Example Request Body (Advertiser-Level)

{
  "name": "mail_mrt33035",
  "status": "INACTIVE"
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50305018,
    "name": "mail_mrt33035",
    "accountId": 1356341,
    "domains": [
      "google.com"
    ],
    "createdAt": "2017-08-21",
    "status": "INACTIVE",
    "categoryIds": [
       7,
       8,
       9
    ],
    "retentionDays": 7
  },
  "errors": null,
  "timeStamp": "2017-08-21T22:29:22Z"
}

Create Mail Domain Audience

Create a new mail domain audience.

POST /traffic/audiences/mrt

Note

Mail domain audiences take about 48 hours to populate.

Parameters

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

Example Request URL

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

Example Request Body (Seat-Level)

{
  "retentionDays": 30,
  "name": "mail_mrt330322",
  "domains": [
    "yahoo.com"
  ],
  "excludeDomains": [
    "supportnetflixupt.com"
  ],
  "categoryIds": [
     7,
     8,
     9
  ],
  "status": "ACTIVE"
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50305059,
    "name": "mail_mrt330322",
    "domains": [
      "yahoo.com"
    ],
    "excludeDomains": [
      "supportnetflixupt.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "categoryIds": [
       7,
       8,
       9
    ],
    "retentionDays": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T22:53:03Z"
}

Example Request Body (Advertiser-Level)

{
  "retentionDays": 30,
  "name": "mail_mrt33035",
  "domains": [
    "yahoo.com"
  ],
  "excludeDomains": [
    "supportnetflixupt.com"
  ],
  "categoryIds": [
     7,
     8,
     9
  ],
  "status": "ACTIVE",
  "accountId": 1356341
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50305018,
    "name": "mail_mrt33035",
    "accountId": 1356341,
    "domains": [
      "yahoo.com"
    ],
    "excludeDomains": [
      "supportnetflixupt.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "categoryIds": [
       7,
       8,
       9
    ],
    "retentionDays": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:39:10Z"
}

Delete Mail Domain Audience

The DSP Traffic API does not support deletion of mail domain audiences.

Read Mail Domains

Search for available mail domains.

GET /traffic/audiences/domainlookups?query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

Parameters

Table 46 Read Mail Domains Parameters
Name Type Description Data Type Required
query query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the column to sort by. string N
dir query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.
  • DESC: data is sorted in decending order.
string N

The response will be a list of matching domains with the number of unique users for each entry.

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/domainlookups?query=netflix&limit=2

Example Response

{
  "response": [
    {
      "id": 1,
      "name": "mailer.netflix.com",
      "metrics": {
        "uniqueUsers": 22198906
      }
    },
    {
      "id": 2,
      "name": "whats-on-netflix.com",
      "metrics": {
        "uniqueUsers": 5930
      }
    }
  ],
  "errors": null,
  "timeStamp": "2017-08-19T04:54:34Z"
}

Read Mail Domain Categories

Advertisers can easily create audiences and target them using mail domain categories and subcategories. For example, Automotive domains, Animal and Pet related domains, etc.

The Read Mail Domain Categories resource enables you to retrieve a list of MRT (mail retargeting) categories that may be used to specify mail domain audiences for targeting.

GET /traffic/audiences/mrt/categories

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/categories

The resource takes no parameters.

Example Response

{
  "response": [
    {
      "id": 1,
      "category": "Animals and Pets"
    },
    {
      "id": 2,
      "category": "Automotive"
    },
    {
      "id": 3,
      "category": "Computers"
    },
    {
      "id": 4,
      "category": "Coupons"
    },
    {
      "id": 5,
      "category": "Entertainment"
    },
    {
      "id": 6,
      "category": "Movies",
      "parentCategoryId": 5
    },
    {
      "id": 7,
      "category": "Music",
      "parentCategoryId": 5
    },
    {
      "id": 8,
      "category": "Television",
      "parentCategoryId": 5
    },
    {
      "id": 9,
      "category": "Ticketing and Live Events",
      "parentCategoryId": 5
    },
    {
      "id": 10,
      "category": "Entertainment—Other",
      "parentCategoryId": 5
    },
    {
      "id": 11,
      "category": "Finance"
    },
    {
      "id": 12,
      "category": "Banking",
      "parentCategoryId": 11
    },
    {
      "id": 13,
      "category": "Credit Cards",
      "parentCategoryId": 11
    },
    {
      "id": 14,
      "category": "Identity Theft and Fraud Protection",
      "parentCategoryId": 11
    },
    {
      "id": 15,
      "category": "Insurance",
      "parentCategoryId": 11
    },
    {
      "id": 16,
      "category": "Investment",
      "parentCategoryId": 11
    },
    {
      "id": 17,
      "category": "Loans and Mortgages",
      "parentCategoryId": 11
    },
    {
      "id": 18,
      "category": "Tax",
      "parentCategoryId": 11
    },
    {
      "id": 19,
      "category": "Finance—Other",
      "parentCategoryId": 11
    },
    {
      "id": 20,
      "category": "Food and Nutrition"
    },
    {
      "id": 21,
      "category": "Beverages",
      "parentCategoryId": 20
    },
    {
      "id": 22,
      "category": "Groceries",
      "parentCategoryId": 20
    },
    {
      "id": 23,
      "category": "Nutrition and Supplements",
      "parentCategoryId": 20
    },
    {
      "id": 24,
      "category": "Recipes",
      "parentCategoryId": 20
    },
    {
      "id": 25,
      "category": "Restaurants",
      "parentCategoryId": 20
    },
    {
      "id": 26,
      "category": "Health and Beauty"
    },
    {
      "id": 27,
      "category": "Beauty and Personal Care",
      "parentCategoryId": 26
    },
    {
      "id": 28,
      "category": "Health",
      "parentCategoryId": 26
    },
    {
      "id": 29,
      "category": "Hobbies"
    },
    {
      "id": 30,
      "category": "Jobs"
    },
    {
      "id": 31,
      "category": "Life Stages"
    },
    {
      "id": 32,
      "category": "Education",
      "parentCategoryId": 31
    },
    {
      "id": 33,
      "category": "Moving",
      "parentCategoryId": 31
    },
    {
      "id": 34,
      "category": "Parenting and Children",
      "parentCategoryId": 31
    },
    {
      "id": 35,
      "category": "Wedding",
      "parentCategoryId": 31
    },
    {
      "id": 36,
      "category": "Life Stages—Other",
      "parentCategoryId": 31
    },
    {
      "id": 37,
      "category": "Marketing and Advertising"
    },
    {
      "id": 39,
      "category": "Marketing and Advertising—Other",
      "parentCategoryId": 37
    },
    {
      "id": 40,
      "category": "Military"
    },
    {
      "id": 41,
      "category": "News"
    },
    {
      "id": 42,
      "category": "Politics"
    },
    {
      "id": 43,
      "category": "Religion"
    },
    {
      "id": 44,
      "category": "Retail"
    },
    {
      "id": 45,
      "category": "Apparel",
      "parentCategoryId": 44
    },
    {
      "id": 46,
      "category": "Gifts",
      "parentCategoryId": 44
    },
    {
      "id": 47,
      "category": "Home",
      "parentCategoryId": 44
    },
    {
      "id": 48,
      "category": "Home Improvement",
      "parentCategoryId": 44
    },
    {
      "id": 49,
      "category": "Luxury Goods",
      "parentCategoryId": 44
    },
    {
      "id": 50,
      "category": "Office Supply",
      "parentCategoryId": 44
    },
    {
      "id": 51,
      "category": "Retail—Other",
      "parentCategoryId": 44
    },
    {
      "id": 52,
      "category": "Romance and Dating"
    },
    {
      "id": 53,
      "category": "Small Business and B2B"
    },
    {
      "id": 54,
      "category": "Social Networks"
    },
    {
      "id": 55,
      "category": "Sports"
    },
    {
      "id": 56,
      "category": "Technology and Electronics"
    },
    {
      "id": 57,
      "category": "Telecommunications"
    },
    {
      "id": 58,
      "category": "Travel"
    },
    {
      "id": 59,
      "category": "Vacations",
      "parentCategoryId": 58
    },
    {
      "id": 60,
      "category": "Air and Charter",
      "parentCategoryId": 58
    },
    {
      "id": 61,
      "category": "Car Rental",
      "parentCategoryId": 58
    },
    {
      "id": 62,
      "category": "Cruises",
      "parentCategoryId": 58
    },
    {
      "id": 63,
      "category": "Hotels and Lodging",
      "parentCategoryId": 58
    },
    {
      "id": 64,
      "category": "Travel—Other",
      "parentCategoryId": 58
    },
    {
      "id": 65,
      "category": "Trucking and Freight"
    },
    {
      "id": 66,
      "category": "Utilities and Energy"
    }
  ],
  "errors": null,
  "timeStamp": "2018-01-05T21:52:10Z"
}