Getting Started With the DNSimple Sandbox API

Table of Contents

• Video walk-through
• 1. Prerequisites
• 2. Setting up your environment
• 3. Batch-creating DNS records
• 4. Automating DNS updates in CI/CD
• 5. Checking domain availability
• 6. Moving to production
• Have more questions?

This tutorial walks you through setting up the DNSimple Sandbox API and making your first API calls. By the end, you will have a working development environment and hands-on experience with common API operations. The examples below use Python, but the Sandbox API works with any language or HTTP client.

You can follow along with the video below, or use it as a reference as you go through the numbered steps.

Video walk-through

1. Prerequisites

Before you begin, ensure you have:

• A DNSimple Sandbox account. Sign up at sandbox.dnsimple.com.
• A Sandbox API access token. See API Access Token for instructions on generating a token.

2. Setting up your environment

The examples in this tutorial use the DNSimple Python client. Install it with:

pip install dnsimple

Create a .env file in your project directory with your Sandbox API token:

DNSIMPLE_TOKEN=your_sandbox_token_here

Verify your setup by connecting to the Sandbox:

import os
from dotenv import load_dotenv
from dnsimple import Client

load_dotenv()

client = Client(sandbox=True, access_token=os.getenv("DNSIMPLE_TOKEN"))
response = client.identity.whoami()
account = response.data.account

print(f"Connected to account {account.id} ({account.email})")

If the script prints your account details, you are ready to start making API calls.

3. Batch-creating DNS records

A common use case is onboarding a new domain with a standard set of DNS records. The batch records endpoint lets you create multiple records in a single API call:

from dnsimple.struct import BatchChangeZoneRecordsInput, BatchChangeZoneRecordsCreateInput

records = [
    {'type': 'A', 'name': '', 'content': '192.0.2.1', 'ttl': 3600},
    {'type': 'A', 'name': 'www', 'content': '192.0.2.1', 'ttl': 3600},
    {'type': 'MX', 'name': '', 'content': 'mail.clientwebsite.com', 'priority': 10, 'ttl': 3600},
    {'type': 'TXT', 'name': '', 'content': 'v=spf1 mx ~all', 'ttl': 3600},
]

creates = [
    BatchChangeZoneRecordsCreateInput(
        name=r['name'],
        type=r['type'],
        content=r['content'],
        ttl=r['ttl'],
        priority=r.get('priority'),
    )
    for r in records
]

batch = BatchChangeZoneRecordsInput(creates=creates)
response = client.zones.batch_change_records(account_id, "my-domain-here.com", batch)

This creates A records for the apex and www subdomain, an MX record for email routing, and an SPF TXT record — all in one request.

4. Automating DNS updates in CI/CD

You can integrate DNS updates into your deployment pipeline. This example updates an A record to point to a new server IP after deployment:

from dnsimple import Client
from dnsimple.struct import ZoneRecordUpdateInput, ZoneRecordInput

def update_dns(domain, new_ip):
    client = Client(sandbox=True, access_token=os.getenv('DNSIMPLE_TOKEN'))
    account_id = client.identity.whoami().data.account.id

    records = client.zones.list_records(
        account_id, domain, filter={"name": "", "type": "A"}
    ).data

    if records:
        record_id = records[0].id
        client.zones.update_record(
            account_id, domain, record_id, ZoneRecordUpdateInput(content=new_ip)
        )
        print(f"Updated DNS for {domain} to point to {new_ip}")
    else:
        client.zones.create_record(
            account_id,
            domain,
            ZoneRecordInput(name="", type="A", content=new_ip, ttl=600),
        )
        print(f"Created DNS record for {domain} pointing to {new_ip}")

5. Checking domain availability

The registrar API lets you check whether a domain is available for registration:

def check_domain_availability(domain_name, client=None, account_id=None):
    if client is None or account_id is None:
        client = Client(sandbox=True, access_token=os.getenv('DNSIMPLE_TOKEN'))
        account_id = client.identity.whoami().data.account.id

    try:
        response = client.registrar.check_domain(account_id, domain_name)
        domain_check = response.data

        if domain_check.available:
            return {
                'available': True,
                'price': getattr(domain_check, 'premium_price', None) or 'standard pricing'
            }
        else:
            return {'available': False}
    except Exception as e:
        return {'error': str(e)}

6. Moving to production

When your integration is working in the Sandbox, switching to production requires two changes:

1. Update the client configuration: Remove sandbox=True or set it to False.
2. Update your API token: Replace your Sandbox token with a production API access token.

# Sandbox
client = Client(sandbox=True, access_token=os.getenv("DNSIMPLE_SANDBOX_TOKEN"))

# Production
client = Client(access_token=os.getenv("DNSIMPLE_TOKEN"))

For more details on the DNSimple API, visit the Developer Documentation. To learn more about the Sandbox environment, see What Is the DNSimple Sandbox API?. For tips on avoiding common mistakes, see Sandbox API Common Pitfalls.

Have more questions?

If you have additional questions or need any assistance with the DNSimple Sandbox API, just contact support, and we’ll be happy to help.