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

Fields

The traffic/audience/mrt resource is defined by the following fields:

Table 48 Mail Domain Audience Fields
Fields Description Data Type
id Specifies an audience segment ID. integer
name Specifies an audience segment name. string
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
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 mail domain audiences are associated with a single advertiser account ID. To learn more, see Advertisers.

integer
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

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

GET /traffic/audiences/mrt/{id}

Parameters

The resource takes a single parameter.

Table 49 Read Seat-Level Audiences Parameters
Parameter Parameter Type Description Data Type Required?
id path Specifies the audience/segment ID. integer Y

The response returns the segment associated with the specified segment ID.

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. A seat-level mail domain audience is available to a single advertiser.

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 Audiences
Parameter Parameter Type Description Data Type Required?
id path Specifies the audience/segment ID. integer Y
accountId query Specifies the account/advertiser ID. integer Y

The response will be the Audience segment associated with the given ID.

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. The audience id must be specified in the resource path. All other updates are in the body to the application/json payload.

PUT /traffic/audiences/mrt/{id}

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.

If you are updating an advertiser-level audience, you must specify the audience accountId in the body to the application/json payload.

Parameters

The resource supports the following parameters:

Table 51 Update Audiences Parameters
Parameter Parameter 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 body Specifies the advertiser/account ID associated with the segment. string N
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

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

Example Payload

This is an example of a seat-level payload:

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

An advertiser-level mail domain audience requires an accountId. This is an example of an advertiser-level response:

{
  "retentionDays": 7,
  "domains": [
    "google.com"
  ],
  "accountId": 1356341,
  "categoryIds": [
     7,
     8,
     9
  ]
}

Example Response

This is an example of a seat-level response:

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

This is an example of an advertiser-level response:

{
  "response": {
    "id": 50305018,
    "name": "mail_mrt33035",
    "accountId": 1356341,
    "domains": [
      "google.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "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.

The mail domain audience may be either an advertiser-level audience or a seat-level audience and defined by an array of domains, excludeDomains, or categoryIds.

POST /traffic/audiences/mrt

Note

Mail domain audiences take about 48 hours to populate.

Parameters

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

Table 52 Create Audieinces Parameters
Parameter Parameter 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.

  • To create a seat-level audience, set this field to null.
  • To create an advertiser-level audience, specify an advertiser account ID. To learn more, see Advertisers.
string Y
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

An example application/json for a seat-level mail domain audience.

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

An example application/json for a advertiser-level mail domain audience.

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

Example Response

An example response seat-level mail domain audience.

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

An example response advertiser-level mail domain audience.

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