> For the complete documentation index, see [llms.txt](https://kevins-organization-58.gitbook.io/smtp-ghost-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kevins-organization-58.gitbook.io/smtp-ghost-api/domain-search.md).

# Domain Search

Retrieves all stored mailbox addresses for a domain along with detailed validation info, paginated.

### Endpoint

**POST** `/api/v1/domain_search`

### Base URL

```
https://smtpghost.com/api/v1/domain_search
```

### Headers

| Header         | Value                         | Required |
| -------------- | ----------------------------- | -------- |
| `Content-Type` | `application/json`            | Yes      |
| `X-KEY`        | `<your-organization-api-key>` | Yes      |

### Request Body

```json
{
  "domain": "voymedia.com",
  "page": 1,
  "items": 20
}
```

### Success Response (200 OK)

#### Domain Found & Emails Returned

```json
{
  "status": "success",
  "domain": "voymedia.com",
  "domain_found_in_db": true,
  "email_count": 2,
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_items": 2,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  },
  "emails": [
    {
      "email": "kevin@voymedia.com",
      "validation": {
        "status": "VALID",
        "account_type": "professional",
        "is_role_account": false,
        "is_disposable": false,
        "is_catch_all": false,
        "last_verified_at": "2025-05-16T11:00:00-04:00",
        "mx_records": ["mx1.voymedia.com", "mx2.voymedia.com"]
      }
    },
    {
      "email": "support@voymedia.com",
      "validation": {
        "status": "VALID",
        "account_type": "professional",
        "is_role_account": false,
        "is_disposable": false,
        "is_catch_all": false,
        "last_verified_at": "2025-05-16T10:30:00-04:00",
        "mx_records": ["mx1.voymedia.com", "mx2.voymedia.com"]
      }
    }
  ]
}
```

#### No Emails Found

```json
{
  "status": "not_found",
  "domain": "voymedia.com",
  "domain_found_in_db": true,
  "message": "No valid or risky emails found for the given domain in our database.",
  "email_count": 0,
  "emails": []
}
```

#### Domain Not in Database

```json
{
  "status": "domain_not_in_db",
  "domain": "unknown.com",
  "domain_found_in_db": false,
  "message": "Domain not found in our database.",
  "email_count": 0,
  "emails": []
}
```

You will never receive a 404 for a missing endpoint—only structured JSON responses with the above statuses.

### Error Responses

#### 400 Bad Request

```json
{
  "error": "Please provide a domain."
}
```

#### 402 Payment Required

```json
{
  "error": "Insufficient credits. You need 1 credit to perform domain email lookup."
}
```

#### 500 Internal Server Error

```json
{
  "status": "error",
  "error": "An internal error occurred during domain search: <details>"
}
```

On any unexpected exception, your credits are refunded and a 500 is returned with `status: "error"`.