# Create or replace a DNS record

`POST https://api.mailmasker.org/api/v1/domains/:domain/dns/records`

Set every value of one name and type in a domain's DNS zone.

- Who can use it: Site admins
- Area: Domains and DNS
- Answers 201 Created when it works
- Page: https://developer.mailmasker.org/dns-record-set

What you send replaces what that name and type held before, so to add a second value (a backup MX, say) send both. TXT values are put in quotes for you, and the host name at the end of an MX, NS, CNAME, PTR or SRV value gets its final dot. `restart_pending` is true when the name and type had no record before.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `domain` | path | yes | The domain whose zone it goes in. | `example.com` |
| `name` | body | yes | The record's full name, such as `www.example.com`, or the domain itself for its own records. A final dot is optional. | `www.example.com` |
| `type` | body | yes | The record type in capitals, such as A, AAAA, CNAME, MX or TXT. | `A` |
| `content` | body | yes | One value, or a list of them. | `["203.0.113.10"]` |
| `ttl` | body | no | How long, in seconds, others may keep it. 3600 if left out. | `3600` |

## Good to know

- A domain that isn't listed answers 404.
- A record the DNS server refuses (a name outside the domain, say) answers 502, with its reason.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/domains/example.com/dns/records' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"www.example.com","type":"A","content":["203.0.113.10"],"ttl":3600}'
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/domains/example.com/dns/records',
    { Authorization => "Bearer $ENV{TOKEN}" },
    json => { name => 'www.example.com', type => 'A', content => ['203.0.113.10'], ttl => 3600 })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli dns records add example.com --name www.example.com --type A --value 203.0.113.10
```

## Response

201 Created:

```json
{ "ok": true, "restart_pending": true }
```