DNS Management

This guide covers how to programmatically manage DNS records for domains purchased through PocketDNS.

Overview

Once a domain is purchased through the embedded interface, you can manage its DNS records using the PocketDNS API. This allows you to automatically configure domains for your users.

DNS Templates

Creating DNS Templates

DNS templates allow you to pre-configure common DNS setups:

const createDNSTemplate = async (templateName, records) => {
  const response = await fetch('https://api.pocketdns.com/api/v1/dns-templates', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: templateName,
      records: records
    })
  });

  if (!response.ok) {
    throw new Error(`Failed to create DNS template: ${response.statusText}`);
  }

  return await response.json();
};

// Example: Website template
const websiteTemplate = await createDNSTemplate('Website', [
  { type: 'A', name: '@', content: '192.0.2.1', ttl: 300 },
  { type: 'A', name: 'www', content: '192.0.2.1', ttl: 300 },
  { type: 'MX', name: '@', content: '10 mail.example.com', ttl: 3600 }
]);

Applying Templates

const applyDNSTemplate = async (domainId, templateId) => {
  const response = await fetch(`https://api.pocketdns.com/api/v1/domains/${domainId}/dns/template`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ template_id: templateId })
  });

  if (!response.ok) {
    throw new Error(`Failed to apply DNS template: ${response.statusText}`);
  }

  return await response.json();
};

Supported DNS Record Types

A Records

Points a domain to an IPv4 address.

{
  type: 'A',
  name: '@',        // or subdomain name
  content: '192.0.2.1',
  ttl: 300
}

AAAA Records

Points a domain to an IPv6 address.

{
  type: 'AAAA',
  name: '@',
  content: '2001:db8::1',
  ttl: 300
}

CNAME Records

Creates an alias for another domain.

{
  type: 'CNAME',
  name: 'www',
  content: 'example.com',
  ttl: 300
}

MX Records

Specifies mail exchange servers.

{
  type: 'MX',
  name: '@',
  content: '10 mail.example.com',  // priority + mail server
  ttl: 3600
}

TXT Records

Stores text information, often used for verification.

{
  type: 'TXT',
  name: '@',
  content: 'v=spf1 include:_spf.google.com ~all',
  ttl: 300
}

SRV Records

Specifies service locations.

{
  type: 'SRV',
  name: '_sip._tcp',
  content: '10 60 5060 sip.example.com',  // priority weight port target
  ttl: 300
}

Managing DNS Records

Create DNS Record

const createDNSRecord = async (domainId, record) => {
  const response = await fetch(`https://api.pocketdns.com/api/v1/domains/${domainId}/dns`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(record)
  });

  if (!response.ok) {
    throw new Error(`Failed to create DNS record: ${response.statusText}`);
  }

  return await response.json();
};

Update DNS Record

const updateDNSRecord = async (domainId, recordId, updates) => {
  const response = await fetch(`https://api.pocketdns.com/api/v1/domains/${domainId}/dns/${recordId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(updates)
  });

  if (!response.ok) {
    throw new Error(`Failed to update DNS record: ${response.statusText}`);
  }

  return await response.json();
};

Delete DNS Record

const deleteDNSRecord = async (domainId, recordId) => {
  const response = await fetch(`https://api.pocketdns.com/api/v1/domains/${domainId}/dns/${recordId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (!response.ok) {
    throw new Error(`Failed to delete DNS record: ${response.statusText}`);
  }

  return response.status === 204;
};

Get All DNS Records

const getDNSRecords = async (domainId) => {
  const response = await fetch(`https://api.pocketdns.com/api/v1/domains/${domainId}/dns`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch DNS records: ${response.statusText}`);
  }

  const { records } = await response.json();
  return records;
};

Common DNS Configurations

Basic Website Setup

const setupBasicWebsite = async (domainId, serverIP) => {
  const records = [
    { type: 'A', name: '@', content: serverIP, ttl: 300 },
    { type: 'A', name: 'www', content: serverIP, ttl: 300 }
  ];

  const promises = records.map(record => createDNSRecord(domainId, record));
  return await Promise.all(promises);
};

Email Configuration (Google Workspace)

const setupGoogleWorkspace = async (domainId) => {
  const records = [
    { type: 'MX', name: '@', content: '1 smtp.google.com', ttl: 3600 },
    { type: 'TXT', name: '@', content: 'v=spf1 include:_spf.google.com ~all', ttl: 300 },
    { type: 'CNAME', name: 'mail', content: 'ghs.googlehosted.com', ttl: 300 }
  ];

  const promises = records.map(record => createDNSRecord(domainId, record));
  return await Promise.all(promises);
};

CDN Configuration (Cloudflare)

const setupCloudflare = async (domainId) => {
  const records = [
    { type: 'A', name: '@', content: '192.0.2.1', ttl: 1 },    // Cloudflare proxy
    { type: 'A', name: 'www', content: '192.0.2.1', ttl: 1 }
  ];

  const promises = records.map(record => createDNSRecord(domainId, record));
  return await Promise.all(promises);
};

Automated DNS Management

Domain Purchase Webhook Handler

// Express.js webhook handler
app.post('/webhook/domain-purchased', async (req, res) => {
  const { domain_id, user_identifier } = req.body;
  
  try {
    // Get user's preferred DNS configuration
    const userConfig = await getUserDNSConfig(user_identifier);
    
    if (userConfig.template_id) {
      // Apply DNS template
      await applyDNSTemplate(domain_id, userConfig.template_id);
    } else if (userConfig.custom_records) {
      // Apply custom DNS records
      const promises = userConfig.custom_records.map(record => 
        createDNSRecord(domain_id, record)
      );
      await Promise.all(promises);
    }
    
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('DNS setup failed:', error);
    res.status(500).json({ error: error.message });
  }
});

DNS Validation

Validate DNS Record

const validateDNSRecord = (record) => {
  const errors = [];
  
  // Validate required fields
  if (!record.type) errors.push('Record type is required');
  if (!record.name) errors.push('Record name is required');
  if (!record.content) errors.push('Record content is required');
  
  // Type-specific validation
  switch (record.type) {
    case 'A':
      if (!/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(record.content)) {
        errors.push('Invalid IPv4 address');
      }
      break;
    case 'AAAA':
      if (!/^[0-9a-fA-F:]+$/.test(record.content)) {
        errors.push('Invalid IPv6 address');
      }
      break;
    case 'MX':
      if (!/^\d+ .+/.test(record.content)) {
        errors.push('MX record must include priority and mail server');
      }
      break;
  }
  
  return errors;
};

Best Practices

1. TTL Values: Use appropriate TTL values (300 for A/AAAA, 3600 for MX)
2. DNS Templates: Create templates for common configurations
3. Validation: Always validate DNS records before creation
4. Error Handling: Handle API failures gracefully
5. Automation: Automate DNS setup for new domains
6. Testing: Test DNS propagation after changes