# Claiming a domain

> Take over a domain that another account has already verified by proving DNS control through the claim flow.

When you try to add a domain that **another account** has already verified, MailBlastr blocks the creation and tells you the domain can be **claimed**. Claiming lets you prove control of the domain over DNS and transfer it to your account — entirely over the API.

## How it works

1. **Start a claim** — Call [Claim domain](https://www.mailblastr.com/docs/domains/claim) with the domain name. MailBlastr creates a placeholder domain on your account and returns a `domain_claim` containing a TXT `record` to add to your DNS.
2. **Add the TXT record** — Publish the returned TXT record at your DNS provider. It proves you control the domain.
3. **Verify the claim** — Call [Verify domain claim](https://www.mailblastr.com/docs/domains/claim). MailBlastr checks the TXT record and, once it resolves, transfers the domain to your account.
4. **Track the status** — Poll [Get domain claim](https://www.mailblastr.com/docs/domains/claim) until the claim reaches `completed`.

## Claim statuses

| Status | Meaning |
| --- | --- |
| `pending` | Waiting for DNS verification. |
| `verified` | DNS proof accepted; the transfer is in progress. |
| `completed` | The domain now belongs to your account. |
| `failed` | The claim could not be completed. |
| `expired` | The claim window passed before it completed. |

## Start a claim

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.domains.claim({ "name": "example.com" });
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Domains.claim({
  "name": "example.com"
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->domains->claim([
  'name' => "example.com"
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Domains.claim({
  "name": "example.com"
})
```

**Go**

```go
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, _ := http.NewRequest("POST", "https://api.mailblastr.com/domains/claim", strings.NewReader(`{ "name": "example.com" }`))
    req.Header.Set("Authorization", "Bearer mb_xxxxxxxxx")
    req.Header.Set("Content-Type", "application/json")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}
```

**Rust**

```rust
use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let res = Client::new()
        .post("https://api.mailblastr.com/domains/claim")
        .header("Authorization", "Bearer mb_xxxxxxxxx")
        .header("Content-Type", "application/json")
        .body(r#"{ "name": "example.com" }"#)
        .send()
        .await?;
    println!("{}", res.text().await?);
    Ok(())
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mailblastr.com/domains/claim"))
    .header("Authorization", "Bearer mb_xxxxxxxxx")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{ "name": "example.com" }
"""))
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

**.NET**

```csharp
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.mailblastr.com/domains/claim");
request.Headers.Add("Authorization", "Bearer mb_xxxxxxxxx");
request.Content = new StringContent(@"{ ""name"": ""example.com"" }", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/domains/claim' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "example.com" }'
```

**CLI**

```bash
mailblastr domains claim start example.com
```

## Canceling a claim

Cancel a pending claim by deleting its placeholder domain with [Delete domain](https://www.mailblastr.com/docs/api/domains-delete), using the `domain_id` from the `domain_claim` object.

> **Note:** The claim flow only ever transfers a domain after DNS ownership has been proven by the TXT record, so a domain can only be claimed by someone who controls its DNS.