# Create a domain

> POST /domains — add a sending domain and get its SPF, DKIM, and DMARC records.

`POST /domains`

Adds a domain, provisions its sending identity (DKIM + custom MAIL FROM), and returns the domain object — including the `records` array of DNS entries to publish. The new domain starts with status `not_started`. Requires a key with full access.

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The bare domain to add, e.g. `yourdomain.com`. Lower-cased and validated as a domain. |
| `region` | string | No | Optional, for compatibility. The region where emails will be sent from. Possible values: `us-east-1` | `eu-west-1` | `sa-east-1` | `ap-northeast-1` (default `us-east-1`). The domain is always pinned to MailBlastr’s configured region regardless of this value. See [Choosing a region](https://www.mailblastr.com/docs/domains/region). |
| `custom_return_path` | string | No | Optional. The subdomain used for the Return-Path (`MAIL FROM`) address, which carries SPF authentication, DMARC alignment, and bounce handling. Defaults to `send` (i.e. `send.yourdomain.com`). Avoid values that could undermine credibility (e.g. `testing`), as they may be exposed to recipients. See [Custom return path](https://www.mailblastr.com/docs/domains/managing). |
| `open_tracking` | boolean | No | Optional. Track the open rate of each email. Applied whenever this flag is on; if a `tracking_subdomain` is configured and verified the open pixel is served from it, otherwise from a shared MailBlastr-hosted host. Defaults to false. See [Open and click tracking](https://www.mailblastr.com/docs/domains/tracking). |
| `click_tracking` | boolean | No | Optional. Track clicks within the body of each HTML email. Applied whenever this flag is on; if a `tracking_subdomain` is configured and verified the rewritten links are served from it, otherwise from a shared MailBlastr-hosted host. Defaults to false. |
| `tracking_subdomain` | string | No | Optional. A custom subdomain for click and open tracking. For example, setting `links` on `example.com` produces a CNAME record for `links.example.com`. Avoid values with a negative connotation (e.g. `tracking`). |
| `tls` | string | No | Optional. The domain’s TLS preference. `opportunistic` (default) encrypts the connection when the receiving server supports TLS and otherwise sends unencrypted; `enforced` records a preference that delivery should require TLS. Defaults to `opportunistic`. See [Enforced TLS](https://www.mailblastr.com/docs/domains/managing). |
| `capabilities` | object | No | Optional. Configure the domain capabilities. `sending` is always `enabled`. Contains `receiving` (`enabled` | `disabled`, default `disabled`) to also receive mail for the domain. |

**Node.js**

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

const mb = new MailBlastr('mb_xxxxxxxxx');

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

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Domains.create({
  "name": "yourdomain.com"
})
```

**PHP**

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

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

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Domains.create({
  "name": "yourdomain.com"
})
```

**Go**

```go
client := mailblastr.NewClient("mb_xxxxxxxxx")
domain, err := client.Domains.Create(&mailblastr.CreateDomainRequest{Name: "yourdomain.com"})
```

**Rust**

```rust
let mb = Mailblastr::new("mb_xxxxxxxxx");
let _domain = mb.domains.create(CreateDomainOptions::new("yourdomain.com")).await?;
```

**Java**

```java
Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");

CreateDomainRequest request = CreateDomainRequest.builder()
    .name("yourdomain.com")
    .build();
mailblastr.domains().create(request);
```

**.NET**

```csharp
IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");
var resp = await mailblastr.DomainCreateAsync(new DomainCreateOptions { Name = "yourdomain.com" });
```

**cURL**

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

**CLI**

```bash
mailblastr domains add yourdomain.com
```

Response — the domain object. The `records` array lists every DNS entry to publish (the DKIM TXT, the SPF MX and TXT on the `send.` subdomain, the DMARC TXT, and — when a `tracking_subdomain` is configured — a Tracking CNAME):

```json
{
  "object": "domain",
  "id": "d91a7c4e-1f2b-4a8c-9e3d-7b5f0a2c1d6e",
  "name": "yourdomain.com",
  "status": "not_started",
  "region": "us-east-1",
  "created_at": "2026-06-23T12:00:00.000Z",
  "custom_return_path": "send",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": null,
  "tls": "opportunistic",
  "capabilities": {
    "sending": "enabled",
    "receiving": "disabled"
  },
  "tracking_domain": null,
  "tracking_verified": false,
  "records": [
    {
      "record": "DKIM",
      "name": "mailblastr._domainkey.yourdomain.com",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."
    },
    {
      "record": "SPF",
      "name": "send.yourdomain.com",
      "type": "MX",
      "ttl": "Auto",
      "status": "not_started",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10
    },
    {
      "record": "SPF",
      "name": "send.yourdomain.com",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=spf1 include:amazonses.com ~all"
    },
    {
      "record": "DMARC",
      "name": "_dmarc.yourdomain.com",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=DMARC1; p=none;"
    }
  ]
}
```

> **Note:** The `Tracking` CNAME is only returned when a `tracking_subdomain` is set. The DKIM, SPF, and DMARC records are always returned.

Errors: `missing_required_field` if `name` is absent, `validation_error` if `name` is not a valid domain or the domain already exists, and `invalid_access` if the key lacks full access. See [Errors](https://www.mailblastr.com/docs/api/errors).