Name.com DNS Sync & CLI Uploader

A Python CLI for managing DNS at Name.com:

• Clone records from one domain to another
• Import from a CSV (Name.com export format)
• Manually add a single record from the command line
• Safe, correct upserts (no accidental duplicates)
• MX failsafe that checks deliverability before creating the record

---

Features

• Auth: HTTP Basic with USERNAME:APITOKEN

• Clone: --from old.com --to new.com

• CSV import: reads Type,Host,Answer,TTL,Priority

• Map suffix: --map-suffix old.com=new.com (find/replace on FQDN suffixes)

• Upsert: updates existing records instead of duplicating

  • MX/SRV match on (host, type, priority)
  • All matches use relative host normalized to the target zone

• Apex handling: sends empty host "" to API for root records (avoids @.domain errors)

• Manual add: --add --type TYPE --host HOST --answer ANSWER [--ttl N] [--pri N]

  • MX auto-forced to @ and short answers like email expand to email.<zone>
  • MX failsafe prompts to create A/AAAA/CNAME if the target doesn’t resolve; CNAME must resolve (or you’ll be re-prompted)

• Dry run: --dry-run shows actions without changing DNS

• Skips SOA/NS in bulk flows

---

Requirements

• Python 3.9+
• pip install requests

---

Quick Start

1. Create an API token in your Name.com account.

   If you have MFA enabled, you have to go and enable the API.  The API does not use MFA and is off by default.
   

2. Test auth:

   curl -u USERNAME:APITOKEN https://api.name.com/core/v1/hello
   

3. Clone one zone into another (upsert):

   python main.py \
     --token 'USERNAME:APITOKEN' \
     --from old.com \
     --to new.com \
     --upsert
   

---

Usage

Clone from a source zone

python main.py --token 'user:apitoken' --from old.com --to new.com --upsert

• Keeps the same labels (www, api, etc.) in the new zone.
• Use --dry-run to preview.

Import from CSV

python main.py --token 'user:apitoken' --csv dns.csv --to example.com --upsert

CSV format (header required):

Type,Host,Answer,TTL,Priority
A,www.example.com,203.0.113.10,300,
MX,example.com,mail.example.net.,300,10
TXT,@,"v=spf1 include:_spf.example.net ~all",300,

Notes:

• Host may be FQDN or relative (@, www).
• Priority applies to MX (and SRV); TTL defaults to 300 if blank.
• CSV import supports SRV if present in API source; SRV extras (port/weight) aren’t in the CSV format here.

Combine clone + CSV (CSV overrides)

python main.py \
  --token 'user:apitoken' \
  --from old.com \
  --csv extras.csv \
  --to new.com \
  --upsert

Map suffix (find & replace on FQDNs)

python main.py \
  --token 'user:apitoken' \
  --csv exported.csv \
  --to new.com \
  --map-suffix old.com=new.com \
  --upsert

Use this if your CSV or source contains fully qualified names that still end with the old zone. It just finds and replaces the suffix.

Manually add a record

# A/AAAA/TXT/CNAME, etc.
python main.py \
  --token 'user:apitoken' \
  --to example.com \
  --add \
  --type A \
  --host www \
  --answer 203.0.113.10 \
  --ttl 300 \
  --upsert

Manually add an MX (with failsafe)

python main.py \
  --token 'user:apitoken' \
  --to example.com \
  --add \
  --type MX \
  --answer email \
  --pri 25 \
  --ttl 300 \
  --upsert

• Host is forced to @ (apex) automatically.

• Short answers like email expand to email.example.com.

• The script resolves the MX target and:

  • If it resolves: proceeds.

  • If it doesn’t resolve: prompts to create A/AAAA/CNAME for that host.

    • If you pick CNAME, its target must resolve (or you’re re-prompted).
    • You’ll be asked for TTL (default 300) when creating the host record.

---

Behavior Details

• Apex records: Internally you’ll see @, but the API payload uses empty host "" to avoid Invalid Host: @.domain.

• Upsert matching:

  • Normalizes both “existing” and “desired” to relative names for the target zone.
  • MX/SRV match key: (host, type, priority)
  • Others match key: (host, type)

• Suffix mapping: --map-suffix old.zone=new.zone simply replaces the trailing .old.zone with .new.zone on FQDNs before normalizing to the target zone.

---

Examples

Dry run preview:

python main.py --token 'user:apitoken' --from old.com --to new.com --upsert --dry-run

Add a root A record:

python main.py --token 'user:apitoken' --to example.com --add --type A --host @ --answer 198.51.100.7 --ttl 300 --upsert

Add a CNAME:

python main.py --token 'user:apitoken' --to example.com --add --type CNAME --host www --answer root.example.net. --ttl 600 --upsert

---

Troubleshooting

• 401 Unauthorized

  • Confirm you’re using USERNAME:APITOKEN (not your account password).
  • Test with: curl -u user:token https://api.name.com/core/v1/hello

• 400 Invalid Host: @.domain

  • Handled by the script (apex sent as "" to the API). If you edited the code, ensure the API payload converts @ → "".

• Unexpected duplicates on upsert

  • Ensure you’re running the version that matches MX/SRV on (host, type, priority).
  • Use --dry-run to see exactly what the script plans to do.

• MX failsafe loop

  • If you choose CNAME and its target doesn’t resolve, creation is blocked to avoid mail disruption. Choose A/AAAA or provide a resolvable CNAME target.

---

Safety Tips

• Always start with --dry-run on production zones.
• When cloning, run on a non-critical domain first to validate.
• After MX changes, verify the target host has A/AAAA (or a CNAME that ultimately resolves to A/AAAA).

---

License

MIT. No warranty; use at your own risk.