Overview

Full control over DNS records via API. Add, update, and delete records of all types. Changes propagate globally within minutes.

Record Types

Type	Description	Example Use
`A`	IPv4 address	Point domain to server
`AAAA`	IPv6 address	IPv6 server
`CNAME`	Canonical name	Alias to another domain
`MX`	Mail exchange	Email routing
`TXT`	Text record	SPF, DKIM, verification
`NS`	Nameserver	Custom nameservers
`SRV`	Service	Application protocols
`CAA`	Certificate Authority	SSL certificate control

Creating Records

A Record (IPv4)

TypeScript:

await client.domains.dns.create('example.com', {
  type: 'A',
  name: '@', // Root domain
  value: '203.0.113.1',
  ttl: 3600, // 1 hour
});
 
// Subdomain
await client.domains.dns.create('example.com', {
  type: 'A',
  name: 'app', // app.example.com
  value: '203.0.113.2',
  ttl: 3600,
});

Python:

client.domains.dns.create(
    "example.com",
    type="A",
    name="@",
    value="203.0.113.1",
    ttl=3600,
)
 
# Subdomain
client.domains.dns.create(
    "example.com",
    type="A",
    name="app",
    value="203.0.113.2",
    ttl=3600,
)

AAAA Record (IPv6)

await client.domains.dns.create('example.com', {
  type: 'AAAA',
  name: '@',
  value: '2001:db8::1',
  ttl: 3600,
});

CNAME Record

// www points to root
await client.domains.dns.create('example.com', {
  type: 'CNAME',
  name: 'www',
  value: 'example.com',
  ttl: 3600,
});
 
// Subdomain to external service
await client.domains.dns.create('example.com', {
  type: 'CNAME',
  name: 'blog',
  value: 'mysite.ghost.io',
  ttl: 3600,
});

MX Records

// Primary mail server
await client.domains.dns.create('example.com', {
  type: 'MX',
  name: '@',
  value: 'mail1.example.com',
  priority: 10,
  ttl: 3600,
});
 
// Backup mail server
await client.domains.dns.create('example.com', {
  type: 'MX',
  name: '@',
  value: 'mail2.example.com',
  priority: 20,
  ttl: 3600,
});

TXT Records

// SPF record
await client.domains.dns.create('example.com', {
  type: 'TXT',
  name: '@',
  value: 'v=spf1 include:usetransactional.com ~all',
  ttl: 3600,
});
 
// Domain verification
await client.domains.dns.create('example.com', {
  type: 'TXT',
  name: '@',
  value: 'google-site-verification=abc123',
  ttl: 3600,
});
 
// DKIM record
await client.domains.dns.create('example.com', {
  type: 'TXT',
  name: 'dkim1._domainkey',
  value: 'k=rsa; p=MIGfMA0GCSqGSIb3...',
  ttl: 3600,
});

SRV Records

// SIP service
await client.domains.dns.create('example.com', {
  type: 'SRV',
  name: '_sip._tcp',
  value: 'sipserver.example.com',
  priority: 10,
  weight: 5,
  port: 5060,
  ttl: 3600,
});
 
// XMPP (chat)
await client.domains.dns.create('example.com', {
  type: 'SRV',
  name: '_xmpp-client._tcp',
  value: 'chat.example.com',
  priority: 0,
  weight: 0,
  port: 5222,
  ttl: 3600,
});

CAA Records

Control which CAs can issue certificates:

// Allow Let's Encrypt
await client.domains.dns.create('example.com', {
  type: 'CAA',
  name: '@',
  value: '0 issue "letsencrypt.org"',
  ttl: 3600,
});
 
// Allow DigiCert for wildcard
await client.domains.dns.create('example.com', {
  type: 'CAA',
  name: '@',
  value: '0 issuewild "digicert.com"',
  ttl: 3600,
});
 
// Report violations
await client.domains.dns.create('example.com', {
  type: 'CAA',
  name: '@',
  value: '0 iodef "mailto:security@example.com"',
  ttl: 3600,
});

Listing Records

Get All Records

const records = await client.domains.dns.list('example.com');
 
for (const record of records) {
  console.log(`${record.type} ${record.name}: ${record.value}`);
  console.log(`  TTL: ${record.ttl}`);
  console.log(`  ID: ${record.id}`);
}

Filter by Type

const mxRecords = await client.domains.dns.list('example.com', {
  type: 'MX',
});
 
const txtRecords = await client.domains.dns.list('example.com', {
  type: 'TXT',
});

Updating Records

Update by ID

await client.domains.dns.update('example.com', record.id, {
  value: '203.0.113.2',
  ttl: 7200,
});

Upsert (Create or Update)

// Creates if doesn't exist, updates if it does
await client.domains.dns.upsert('example.com', {
  type: 'A',
  name: '@',
  value: '203.0.113.1',
  ttl: 3600,
});

Deleting Records

Delete by ID

await client.domains.dns.delete('example.com', record.id);

Delete by Match

// Delete all MX records
await client.domains.dns.deleteByType('example.com', 'MX');
 
// Delete specific name
await client.domains.dns.deleteByName('example.com', {
  type: 'A',
  name: 'old-subdomain',
});

Bulk Operations

Create Multiple Records

await client.domains.dns.createBulk('example.com', [
  { type: 'A', name: '@', value: '203.0.113.1', ttl: 3600 },
  { type: 'A', name: 'www', value: '203.0.113.1', ttl: 3600 },
  { type: 'CNAME', name: 'blog', value: 'blog.example.com', ttl: 3600 },
  { type: 'MX', name: '@', value: 'mail.example.com', priority: 10, ttl: 3600 },
]);

Replace All Records

// Replace all records with new set
await client.domains.dns.replaceAll('example.com', [
  { type: 'A', name: '@', value: '203.0.113.1', ttl: 3600 },
  { type: 'CNAME', name: 'www', value: 'example.com', ttl: 3600 },
]);

TTL (Time to Live)

TTL determines how long DNS resolvers cache the record:

Value	Duration	Use Case
300	5 minutes	Frequent changes
3600	1 hour	Standard
86400	24 hours	Stable records

// Low TTL for upcoming changes
await client.domains.dns.update('example.com', record.id, {
  ttl: 300, // Reduce before migration
});
 
// Perform migration...
 
// Return to normal TTL
await client.domains.dns.update('example.com', record.id, {
  ttl: 3600,
});

Name Formats

Name	Resolves To
`@`	example.com (root)
`www`	www.example.com
`app`	app.example.com
`api.v1`	api.v1.example.com
`*`	wildcard (any subdomain)

Common Configurations

Website

// Basic website
const websiteRecords = [
  { type: 'A', name: '@', value: '203.0.113.1' },
  { type: 'CNAME', name: 'www', value: 'example.com' },
];
 
await client.domains.dns.createBulk('example.com', websiteRecords);

Email (Google Workspace)

const googleWorkspaceRecords = [
  { type: 'MX', name: '@', value: 'aspmx.l.google.com', priority: 1 },
  { type: 'MX', name: '@', value: 'alt1.aspmx.l.google.com', priority: 5 },
  { type: 'MX', name: '@', value: 'alt2.aspmx.l.google.com', priority: 5 },
  { type: 'TXT', name: '@', value: 'v=spf1 include:_spf.google.com ~all' },
];
 
await client.domains.dns.createBulk('example.com', googleWorkspaceRecords);

Email (Microsoft 365)

const microsoft365Records = [
  { type: 'MX', name: '@', value: 'example-com.mail.protection.outlook.com', priority: 0 },
  { type: 'TXT', name: '@', value: 'v=spf1 include:spf.protection.outlook.com -all' },
  { type: 'CNAME', name: 'autodiscover', value: 'autodiscover.outlook.com' },
];
 
await client.domains.dns.createBulk('example.com', microsoft365Records);

Wildcard Records

Match any subdomain:

// All subdomains point to same IP
await client.domains.dns.create('example.com', {
  type: 'A',
  name: '*',
  value: '203.0.113.1',
  ttl: 3600,
});
 
// Wildcard doesn't override explicit records
await client.domains.dns.create('example.com', {
  type: 'A',
  name: 'api', // api.example.com uses this specific record
  value: '203.0.113.2',
  ttl: 3600,
});

Record Validation

Records are validated before creation:

try {
  await client.domains.dns.create('example.com', {
    type: 'A',
    name: '@',
    value: 'not-an-ip', // Invalid
  });
} catch (error) {
  console.log(error.code); // 'INVALID_RECORD_VALUE'
  console.log(error.message); // 'Invalid IPv4 address'
}

Next Steps

DNS Presets - Quick configurations
Email Integration - Set up for email
DNSSEC - Enable DNS security

DNS Management