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 at either the seat level or the advertiser level:

  • Seat-level mail domain audiences are shared by all of the advertisers across the seat.
  • Advertiser-level mail domain audiences are exclusively available to a single advertiser.

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 two auxiliary resources that enable you to read these objects as well.

Endpoints

You can read, update, and create mail domain audiences using the MRT (mail retargeting) resource.

/traffic/audiences/mrt
  • Use the GET method to read seat-level and advertiser-level mail domain audiences.
  • Use the POST method to add new mail domain audiences.
  • Use the PUT method to update existing mail domain audiences.

A mail domain audience is defined by one or more domains or mail domain categories (a grouping of multiple domains). The Oath Ad Platforms DSP provides resources that enable you to return available domain and domain category objects:

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 (mrt) object is defined by the following fields:

Table 48 mrt Object Fields
Name Description Type
id Specifies an audience segment ID. integer
name Specifies an audience segment name. string
accountId

Specifies the advertiser account associated with the audience segment.

The Oath Ad Platforms DSP allows you to create both seat-level and advertiser-level mail domain audiences. Advertiser-level audiences are associated with a single advertiser account ID. To learn more, see Advertisers.

integer
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: 3, 4, 5, 7, 10, 14, 15, 21, 30 (default value), 45, 60, 90.

integer
status

Specifies the current status of the segment.

  • ACTIVE - Active, the default value
  • INACTIVE - Inactive
string
domains

An array of domains. A consumer is included in the audience if they receive mail from any of the specified domains. You can search for available domains or provide other values.

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

array
excludeDomains

An array of domains. A consumer is included in the audience if they do not receive mail from any of the specified domains.

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

array
categoryIds

An array of mail domain categories.

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

array
createdAt A read-only field that specifies the time of creation. string

Read Seat-Level Audiences

Retrieves audience data for a specific seat-level mail domain audience. A seat-level audience is available to every advertiser in a seat.

GET /traffic/audiences/mrt/{id}

Parameters

The resource takes a single parameter specified in the path of the endpoint URL:

Table 49 Read Seat-Level Audiences Parameters
Name Type Description Data Type Required
id path Specifies the mail domain audience ID. integer Y

Example Request

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

Example Response

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

Read Advertiser-Level Audiences

Returns data for a single advertiser-level mail domain audience.

To retrieve an audience specified at the audience level, you must provide the advertiser accountId in addition to the mail domain audience id.

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

Parameters

The resource takes two parameters:

Table 50 Read Advertiser-Level Mail Domain Audiences
Name Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser accoun ID. integer Y

Example Request

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

Example Response

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

Updates an existing mail domain audience.

PUT /traffic/audiences/mrt/{id}

Note

To update an advertiser-level audience, you must provide an accountId query parameter.

The resource supports partial updates for all fields except excludeDomains; fields that are either not passed or passed as null will be ignored during update.

Parameters

The resource supports the following parameters:

Table 51 Update Audiences Parameters
Name Type Description Data Type Required
id path Specifies the audience/segment ID. integer Y
name body Specifies the name of the segment. string N
retentionDays body

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: 3, 4, 5, 7, 10, 14, 15, 21, 30 (default value), 45, 60, 90.

integer N
status body

Specifies the current status of the segment.

  • ACTIVE - Active, the default value
  • INACTIVE - Inactive
string N
accountId query

Specifies the advertiser account ID.

[1]Required to update an advertiser-level audience.
integer Y [1]
domains body

Specifies an array of domains. The audience includes all consumers that have received mail from any of the specified domains.

To receive a list of domains, see Read Mail Domains.

Note: Existing values will be removed if an empty array is supplied during an update.

array N
excludeDomains body

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

Note: Existing values will be removed if an empty array is supplied during an update.

array N
categoryIds body Specifies an array of categories. The consumer is included in the audience if they receive mail a domain belonging to a specified category. array N

Example Request (Seat-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/50305006
{
  "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 (Advertiser-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/50305006?accountId=1356341
{
  "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 Audiences

Creates a new advertiser-level or seat-level mail domain audience.

POST /traffic/audiences/mrt

Note

Mail domain audiences take about 48 hours to populate.

Parameters

Table 52 Create Mail Domain Audience Parameters
Name Type Description Data Type Required
name body Specifies the name of the segment. string Y
retentionDays body

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

Counted back from the the current date: 3, 4, 5, 7, 10, 14, 15, 21, 30 (default value), 45, 60, 90.

integer N
status body

Specifies the current status of the segment.

  • ACTIVE - Active, the default value
  • INACTIVE - Inactive
string N
accountId body

Specifies the advertiser/account ID associated with the segment.

[2]Required to create an advertiser-level audience.
integer Y [2]
domains body

Specifies an array of domains. The audience includes all consumers that have received mail from any of the specified domains.

To receive a list of domains, see Read Mail Domains.

array N
excludeDomains body Specifies an array of domains. The audience excludes all consumers that have received mail from any of the specified domains. array N
categoryIds body Specifies an array of categories. The audience includes all consumers that have received mail from any domain belonging to the specified categories. array Required if domains or excludeDomains is not specified.

Example Request

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

Example Payload (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 Payload (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 Audiences

The Oath Ad Platforms DSP does not support the deletion of mail domain audiences.

Read Mail Domains

Returns data about the available mail domains.

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

Parameters

The resource supports the following query-based parameters:

Table 53 Read Mail Domains Parameters
Name Type Description Data Type Required
page query Specifies the page number. integer N
limit query Specifies the total number of items returned. Maximum value is 100. integer N
sort query

Specifies the column sort direction.

  • ASC
  • DESC
string N
query query

Specifies the search term. Use URL encoding conventions.

  • ASC
  • DESC
string N

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

Example Request

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

The resource takes no parameters.

Example Response

The resource returns a list of Mail Domain Audience categories.

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