---
title: "Mail Domain"
slug: "mail-domain"
updated: 2026-03-24T16:49:34Z
published: 2026-03-24T16:49:34Z
canonical: "help.yahooinc.com/mail-domain"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail Domain Audiences

*This article describes resources and services you can use to view, create, and update mail domain audiences.*

## Overview

A mail domain audience includes Yahoo Mail customers associated with one or more email domains. The customer may have received email from certain domains, not received email from certain domains, or both.

All mail domain audiences are defined by one or more mail `domains` identified by `categoryIds`.

## Hierarchy

You can define a `Mail Domain` audience at the seat level or the advertiser level.

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

## Endpoint

```plaintext
/traffic/audiences/mrt
```

Use the following HTTP methods:

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

```plaintext
/traffic/audience/domainlookups
```

The Read Mail Domain Category resource returns domain category data:

```plaintext
/traffic/audience/mrt/categories
```

## Resources

The `Mail Domain `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. If you specify an advertiser ID, you can only use the audience for that advertiser’s campaigns. To learn more, refer to [Advertisers](https://developer.yahooinc.com/dsp/api/docs/traffic/advertisers.html). | `integer` | Required for advertiser-level audiences; do not use for seat-level audiences. | Required for advertiser-level audiences; do not use for seat-level audiences. |
| `retentionDays` | Specifies the date by which a user must have received an email to be included in the audience (in days, counting back from the current date). Allowed values: 3, 4, 5, 7, 10, 14, 15, 21, 30, 45, 60, 90. Defaults to `30` if you don’t specify a value. | `integer` | Optional | Optional |
| `domains` | Specifies an array of domains. The audience includes consumers who have received email from any of the specified domains. You can search for available domains or provide other values. You can use the Mail Domains resource to retrieve available domains. To learn more, refer to [Search Mail Domains](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mrt-audience.html#search-mail-domains). To remove existing values, specify an empty array. | `array` | Optional | Optional |
| `excludeDomains` | Specifies an array of domains. A consumer is excluded from the audience if they receive mail from any of the specified domains. You can use the Mail Domains resource to retrieve available domains. To learn more, refer to [Search Mail Domains](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mrt-audience.html#search-mail-domains). To remove existing values, specify an empty array. | `array` | Optional | Optional |
| `categoryIds` | Specifies an array of categories. The audience includes consumers who have received mail from a domain belonging to the specified categories. You can use the Mail Domains Audience Categories resource to retrieve mail domain audience categories. To learn more, refer to [Read Mail Domain Categories](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mrt-audience.html#read-mail-categories). To remove existing values, specify an empty array. | `array` | Required if you do not specify `domains` or `excludeDomains`. | Required if you do not specify `domains` or `excludeDomains`. |
| `createdAt` | A read-only field that specifies when the audience was created. | `string` | N/A | N/A |
| `countryCodes` | Specifies an array of International Standards Organization ISO3, 3 letter alphabetic country codes representing the target country/region for the audience. Specify single or multiple country codes. Must be selected from the supported country list. | `string` | Required | N/A |

## Read Audience

Read a specific mail domain audience.

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

### Parameters

| **Parameter** | **Parameter Type** | **Description** | **Data Type** | **Required/Optional** |
| --- | --- | --- | --- | --- |
| `id` | path | Specifies the audience ID. | `integer` | Required |
| `accountId` | query | Specifies the advertiser ID. | `integer` | Required for advertiser-level audiences. Do not use for seat-level audiences. |

### Example Request URL (Seat-Level)

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

### Example Response (Seat-Level)

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

### Example Request URL (Advertiser-Level)

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

### Example Response (Advertiser-Level)

```plaintext
{
  "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,
    "countryCodes": ["USA", "CAN"]
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:40:44Z"
}
```

## Create Audience

Create a new mail domain audience.

```plaintext
POST /traffic/audiences/mrt
```

> [!NOTE]
> Note
> 
> Mail domain audiences take about 48 hours to populate.

### Parameters

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

### Example Request URL

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

### Example Request Body (Seat-Level)

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

### Example Response (Seat-Level)

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

### Example Request Body (Advertiser-Level)

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

### Example Response (Advertiser-Level)

```plaintext
{
  "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,
    "countryCodes": ["USA", "CAN"]
  },
  "errors": null,
  "timeStamp": "2017-08-21T21:39:10Z"
}
```

## Update Audience

Update an existing mail domain audience.

```plaintext
PUT /traffic/audiences/mrt/{id}
```

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

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

### Example Request Body (Seat-Level)

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

### Example Response (Seat-Level)

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

### Example Request URL (Advertiser-Level)

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

### Example Request Body (Advertiser-Level)

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

### Example Response (Advertiser-Level)

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

## Delete Audience

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

## Search Mail Domains

Search for available mail domains.

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

### Parameters

The following query parameters are all optional.

| **Parameter** | **Description** | **Data Type** |
| --- | --- | --- |
| `query` | Specifies the search term. Use URL encoding conventions (i.e. replace spaces with a `+` or `%20`). | `string` |
| `page` | Specifies the page number. | `integer` |
| `limit` | Specifies the total number of items to return. Maximum allowed value is `100`. | `integer` |
| `sort` | Specifies the column to sort by. | `string` |
| `dir` | Specifies the sort direction. Allowed values: - `ASC`: data is sorted in ascending order. - `DESC`: data is sorted in descending order. | `string` |

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

### Example Request URL

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

### Example Response

```plaintext
{
  "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

Create audiences and target them using mail domain categories and subcategories like Automotive domains, Animal and Pet-related domains, etc.

Use the Read Mail Domain Categories resource to retrieve a list of MRT (mail retargeting) categories that you can use to create mail domain audiences.

```plaintext
GET /traffic/audiences/mrt/categories
```

### Example Request URL

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

The resource takes no parameters.

### Example Response

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

## Read Supported Countries

Get a list of supported countries.

```plaintext
 GET /traffic/audiences/countries
```

### Sample Response

```plaintext
{
  "countries": [
    {
      "isoCode3": "USA",
      "name": "USA"
    },
    {
      "isoCode3": "CAN",
      "name": "Canada"
    },
    {
      "isoCode3": "JPN",
      "name": "Japan"
    },
    {
      "isoCode3": "IND",
      "name": "India"
    },
    …
    {
      "isoCode3": "ECU",
      "name": "Ecuador"
    },
    {
      "isoCode3": "ARG",
      "name": "Argentina"
    },
    {
      "isoCode3": "COL",
      "name": "Colombia"
    }
  ]
}
```