Mail Domain Audiences (MRT)

Overview

A mail domain audience is based on people who received Yahoo Mail from specific domains. You can include people if they received mail from certain domains, did not receive mail from other domains, or both.

You can build mail domain audiences to share across your seat, or for individual advertisers.

Endpoint

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

Fields

The MRT object contains the following fields:

Name Description Type Add Update
id ID of the audience segment. integer N/A Required
name Name of the segment. text Required Optional
retention_days

Number of days to count back from today in determining if the mail the user receives qualifies the user to be included in the audience.

  • 3
  • 4
  • 5
  • 7
  • 10
  • 14
  • 15
  • 21
  • 30 - Default Value
  • 45
  • 60
  • 90
integer Optional Optional
status

Current status of the segment.

  • ACTIVE - (Default Value) Active.
  • INACTIVE - Inactive
text Optional Optional
isGlobal

Indicate whether the segment is at Seat or Advertiser level.

  • true - Seat-level audience can be used for all the advertisers across your seat. Ensure that accountId is null to create a seat-level audience.
  • false - Advertiser-level audience is available for a single adversier. You must provide an accountId for this option.
text Required Required
accountId Advertiser/account ID to associate this segment with when creating or updating an advertiser-level audience. (1) Required when isGlobal is false. (2) Required when updating an existing advertiser-level audience. Refer to Advertisers. integer Required (1) Required (2)
domains Array containing domains. The user is included in the audience if they receive mail from any of the selected domains. You can search for available domains or alternatively provide other values. array Required Required
excludeDomains Array containing domains. The user is included in the audience if they do not receive mail from any of the selected domains. You can search for available domains or alternatively provide other values. Note Existing values will be removed if null or empty array is supplied during an Update. array Optional Optional
createdAt (Read-Only) Creation timestamp. datetime N/A N/A

Read Seat-Level Audience (Single)

To retrieve data for a specific Seat-Level Mail Domain Audience (MRT), make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/{id}
Name Description Type Required?
id Audience / Segment 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/50305006

Example Response

{
  "response": {
    "id": 50305006,
    "name": "mail_mrt3303",
    "domains": [
      "yahoo.com"
    ],
    "excludeDomains": [
      "supportnetflixupt.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "isGlobal": true,
    "retention_days": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:30:08Z"
}

Read Advertiser-Level Audience (Single)

To retrieve data for a specific Advertiser-Level Mail Domain Audience (MRT), make a GET call with the parameters specified below.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/{id}?accountId={accountId}
Name Description Type Required?
id Audience / Segment ID integer Y
accountId Account or 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",
    "isGlobal": false,
    "retention_days": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:40:44Z"
}

Update Audience

To update an existing Mail Domain Audience (MRT), make a PUT call with a payload body and id parameter. The response will be the updated Audience.

Partial update is supported (for all fields except excludeDomains); fields that are either not passed or passed as null will be ignored during update.

Note When updating an Advertiser-Level audience, isGlobal and accountId fields are required.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mrt/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

Example Request

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

Example Payload (Seat-Level)

{
  "domains": [
    "yahoo.com",
    "gmail.com"
  ],
  "isGlobal": true
}

Example Response (Seat-Level)

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

Example Payload (Advertiser-Level)

{
  "retention_days": 7,
  "domains": [
    "google.com"
  ],
  "isGlobal": false,
  "accountId": 1356341
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50305018,
    "name": "mail_mrt33035",
    "accountId": 1356341,
    "domains": [
      "google.com"
    ],
    "createdAt": "2017-08-21",
    "status": "ACTIVE",
    "isGlobal": false,
    "retention_days": 7
  },
  "errors": null,
  "timeStamp": "2017-08-21T22:29:22Z"
}

Create Audience

To create a new Mail Domain Audience (MRT), make a POST call with a payload body. The response will be the newly created Audience.

Example Request

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

Example Payload (Seat-Level)

{
  "retention_days": 30,
  "name": "mail_mrt330322",
  "isGlobal": true,
  "domains": [
    "yahoo.com"
  ],
  "excludeDomains": [
    "supportnetflixupt.com"
  ],
  "status": "ACTIVE"
}

Example Response (Seat-Level)

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

Example Payload (Advertiser-Level)

{
  "retention_days": 30,
  "name": "mail_mrt33035",
  "domains": [
    "yahoo.com"
  ],
  "excludeDomains": [
    "supportnetflixupt.com"
  ],
  "status": "ACTIVE",
  "isGlobal": false,
  "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",
    "isGlobal": false,
    "retention_days": 30
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:39:10Z"
}

Delete Audience

Audience deletion is not supported by the API.

Read Available Domains

To search for available domains, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/domainlookups?page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}
Name Description Type Required?
page Page number integer N
limit Total number of items to return. Maximum allowed value is 100. integer N
sort Column to sort by text N
dir Sort direction. Valid values: asc, desc text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text 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"
}