python-dna: DomainNameAPI client for Python
Python client for the DomainNameAPI reseller REST API: search, register, transfer and renew domains, manage contacts, nameservers, child nameservers, DNS zones and URL forwarding. It is a faithful port of php-dna: same methods, same requests, same return values, verified against php-dna's conformance fixtures.
📦 Download — always use Releases!
⬇️ Get the latest tested version here: https://github.com/domainreseller/python-dna/releases/latest
⚠️ Do not use the green Code → Download ZIP button — that downloads the raw development branch. Release packages are versioned, tested and production-ready.
Installation and Integration Guide
Minimum Requirements
- Python 3.8 or higher (3.12 recommended)
- No third-party packages: the library only uses the Python standard library (
urllib,json,ssl).
A) Install with pip
pip install domainnameapi
B) Install a release package
Download the wheel (domainnameapi-1.0.0-py3-none-any.whl) or the source archive from the
latest release and install it:
pip install domainnameapi-1.0.0-py3-none-any.whl
C) Use the source directly
Copy the src/domainnameapi folder next to your code (or add src to PYTHONPATH) and import it.
The examples folder has one runnable script per method.
🔑 API Credentials — Reseller ID & API Key
The library talks to the DomainNameAPI REST API and needs exactly two credentials, passed to the constructor:
| Parameter | Value |
|---|---|
| First | Reseller ID — UUID like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Second | API Key |
💡 Find your Reseller ID and API Key in your DomainNameAPI panel under API Settings. ⚠️ These are API credentials — your panel login details will not work here.
from domainnameapi import DomainNameAPI
reseller_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
api_key = "your-api-key"
# Live environment
dna = DomainNameAPI(reseller_id, api_key)
# Test (OTE) environment
dna = DomainNameAPI(reseller_id, api_key, True)
Leading and trailing whitespace around the credentials is removed automatically.
Quick Start
from domainnameapi import DomainNameAPI
dna = DomainNameAPI("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "your-api-key")
details = dna.get_details("example.com")
if details["result"] == "OK":
print(details["data"]["Dates"]["Expiration"])
else:
print(details["error"]["Code"], details["error"]["Message"])
Method names are snake_case (get_details, register_with_contact_info). The php-dna names also work as
aliases, so code ported from PHP can keep dna.GetDetails(...) or dna.getDetails(...).
Return Values and Error Handling
Methods return plain dict/list values with exactly the keys php-dna returns. They do not raise
exceptions for gateway or network problems; check result instead:
# Success
{"result": "OK", "data": {...}}
# Failure
{"result": "ERROR", "error": {"Code": "API_404", "Message": "...", "Details": "...",
"GatewayCode": "Dna.DomainService:Domain:10007"}}
CodeisAPI_<HTTP status>for gateway errors (API_400,API_404,API_429,API_500, ...). A redirect answer (wrong credentials) givesAPI_302with the messageInvalid API credentials.GatewayCodeis added toAPI_<status>errors when the gateway sent its own error code (for exampleDna.DomainService:Domain:10007), so you can tell "domain not found" from "TLD not supported".Messageis the gateway's message. Empty error bodies becomeHTTP <status> - <reason>(for exampleHTTP 429 - Too Many Requests).Detailsholds the gateway's details (or the raw response body when there are none); validation errors are flattened into a readable list of fields, for exampleAdmin PostalCode, Tech PostalCode - 'PostalCode' is required.- Network failures are errors too, never an empty success: a timeout returns
CURL_28withCould not reach the DomainNameAPI service: the connection timed out. (...); DNS, connection and TLS failures returnCURL_6,CURL_7,CURL_35/CURL_60withCurl error during request: ...(curl error numbers, the same codes php-dna reports).API_codes are only used for HTTP statuses. - A refusal is an error even when the gateway answers HTTP 200: if registration, transfer or renewal comes
back with
success: false, the method returnsREGISTER_DOMAIN,TRANSFER_DOMAINorRENEW_DOMAINwith the gateway's message. - Flags keep php-dna's types:
LockStatusis the string"true"/"false", prices are formatted strings ("11.9900").
A few methods use their own envelope, exactly as in php-dna:
| Method | On success | On failure |
|---|---|---|
check_availability |
a plain list of results |
the ERROR envelope |
get_current_balance |
OperationResult: "SUCCESS" |
OperationResult: "FAILED" with ErrorCode (API_<status>, CURL_<errno>, or BALANCE for a currency the account does not report) |
check_transfer |
result: "OK" only when the domain is transferable |
result: "ERROR" with data and error |
is_tr_tld, validate_contact |
plain values (no network) | — |
Only programming errors (for example passing a string where set_resource_record_set expects a list)
raise a Python exception.
The timeouts are 30 seconds per call and 10 seconds to connect. Redirects are not followed.
Test Mode (OTE)
Pass True as the third argument to use the test environment https://ote.domainresellerapi.com/api/v1.
String values from configuration files are understood: "true", "1", "on", "yes" enable test mode,
anything else ("false", "0", "off", "") keeps the live environment.
dna = DomainNameAPI(reseller_id, api_key, True)
dna = DomainNameAPI(reseller_id, api_key, os.environ.get("DNA_TEST_MODE", "false"))
Error Reporting (Telemetry)
When an API call fails, the library can send an error report to DomainNameAPI's own error tracker (Sentry). A small random share of successful calls (4%, plus every call slower than 1 second) is sent as a performance record. This helps DomainNameAPI find and fix problems. Error reporting is on by default.
ℹ️ In version 1.0.0 the built-in Sentry address is still empty, because the Sentry project for python-dna has not been created yet: nothing is sent until a library update fills it in, or until you pass your own address with
DomainNameAPI(..., sentry_dsn="https://key@sentry.example.com/1").
Reports are sent from a background thread: they never slow down or break your call. Expected, high-volume errors (domain not found, insufficient balance, invalid credentials, no forwarding configured, ...) are never reported.
What is sent:
- error code and message
- called endpoint path and HTTP method
- call duration
- library name (
DomainNameAPI-Python), library version and Python version - reseller ID and domain name
- the server's public IP address (looked up via
api.ipify.org) and the operating-system user name - the API request and response, including the domain's contact details; only credentials are masked — EPP/auth codes, API keys, passwords and tokens are replaced with
***
What is never sent: EPP/auth codes, API keys, passwords or tokens in readable form; function call arguments in stack traces.
Why and how long: the data is used only for usage measurement and early diagnosis of problems, and is kept for 30 days on DomainNameAPI's own Sentry server, after which it is deleted automatically.
How to turn it off: call set_error_reporting_enabled(False) after constructing the client:
dna = DomainNameAPI(reseller_id, api_key)
dna.set_error_reporting_enabled(False)
Minimal mode: set_telemetry_minimal(True) sends only the error code and message, endpoint, timing,
versions and reseller ID — no request/response data, domain, IP address or user name.
dna.set_telemetry_minimal(True)
🔒 Security: TLS certificate verification is on. On a host with an outdated CA bundle it can be switched off with
dna.set_ssl_verification(False)— this is not recommended; updating the CA bundle is the better fix.
Usage
All examples below assume:
from domainnameapi import DomainNameAPI
dna = DomainNameAPI("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "your-api-key")
The sample outputs are real return values of the library.
Account
Get Reseller Details
Reseller account details: ID, name and balances (USD and TL).
result = dna.get_reseller_details()
Sample output
{'result': 'OK',
'id': '00000000-0000-4000-8000-000000000001',
'active': True,
'name': 'example-reseller',
'balance': '601.64',
'currency': 'USD',
'symbol': '$',
'balances': [{'balance': '601.64', 'currency': 'USD', 'symbol': '$'},
{'balance': '1250.50', 'currency': 'TL', 'symbol': 'TL'}]}
Get Current Balance
Current balance in one currency: USD (default) or TRY. A currency the account does not report (EUR, GBP, ...) returns OperationResult FAILED with ErrorCode BALANCE.
result = dna.get_current_balance("USD")
Sample output
{'ErrorCode': 0,
'OperationMessage': 'Command completed succesfully.',
'OperationResult': 'SUCCESS',
'Balance': '601.64',
'CurrencyId': 2,
'CurrencyInfo': None,
'CurrencyName': 'USD',
'CurrencySymbol': '$'}
Search and Lists
Domain Availability Check
Availability and price of every domain + extension combination. Returns a plain list on success, an error envelope on failure.
result = dna.check_availability(
["dnaprobexyz123", "google", "premium"], # names without extension
["com", "net"], # extensions
1, # period (years)
"create", # command: create / renew / transfer
)
Sample output
[{'TLD': 'com',
'DomainName': 'dnaprobexyz123',
'Status': 'available',
'Command': 'create',
'Period': 1,
'IsFee': False,
'Price': '11.9900',
'Currency': 'USD',
'Reason': None},
{'TLD': 'net',
'DomainName': 'dnaprobexyz123',
'Status': 'available',
'Command': 'create',
'Period': 1,
'IsFee': False,
'Price': '13.9900',
'Currency': 'USD',
'Reason': None},
{'TLD': 'com',
'DomainName': 'google',
'Status': 'notavailable',
'Command': 'create',
'Period': 1,
'IsFee': False,
'Price': '11.9900',
'Currency': 'USD',
'Reason': 'Domain exists'},
{'TLD': 'net',
'DomainName': 'premium',
'Status': 'available',
'Command': 'create',
'Period': 1,
'IsFee': True,
'Price': '2500.0000',
'Currency': 'USD',
'Reason': None}]
Domain List
Domains in the reseller account. Filters: PageNumber (0-based), PageSize, OrderColumn, OrderDirection, DomainName ...
result = dna.get_list({
"PageNumber": 0,
"PageSize": 50,
"OrderColumn": "ExpirationDate",
"OrderDirection": "DESC",
})
Sample output
{'data': {'Domains': [{'ID': 11,
'Status': 'ok',
'DomainName': 'example.com',
'AuthCode': '',
'LockStatus': 'true',
'PrivacyProtectionStatus': 'true',
'IsChildNameServer': 'false',
'Contacts': {'Billing': {'ID': ''},
'Technical': {'ID': ''},
'Administrative': {'ID': ''},
'Registrant': {'ID': ''}},
'Dates': {'Start': '2024-03-15T10:20:30',
'Expiration': '2027-03-15T10:20:30',
'RemainingDays': 126},
'NameServers': ['ns1.example.net', 'ns2.example.net'],
'Additional': [],
'ChildNameServers': []},
{'ID': 12,
'Status': 'Deleted',
'DomainName': 'example.net',
'AuthCode': '',
'LockStatus': 'false',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'false',
'Contacts': {'Billing': {'ID': ''},
'Technical': {'ID': ''},
'Administrative': {'ID': ''},
'Registrant': {'ID': ''}},
'Dates': {'Start': '2023-01-01T00:00:00',
'Expiration': '2026-01-01T00:00:00',
'RemainingDays': 0},
'NameServers': [],
'Additional': [],
'ChildNameServers': []},
{'ID': 13,
'Status': 'WaitingForRegistration',
'DomainName': 'example.org',
'AuthCode': '',
'LockStatus': 'false',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'false',
'Contacts': {'Billing': {'ID': ''},
'Technical': {'ID': ''},
'Administrative': {'ID': ''},
'Registrant': {'ID': ''}},
'Dates': {'Start': '', 'Expiration': '', 'RemainingDays': 0},
'NameServers': [],
'Additional': [],
'ChildNameServers': []}]},
'result': 'OK',
'TotalCount': 3}
TLD List
TLD list with prices per period (registration, renew, transfer, restore ...).
result = dna.get_tld_list(100)
Sample output
{'data': [{'id': 1,
'status': 'Active',
'maxchar': 63,
'maxperiod': 10,
'minchar': 1,
'minperiod': 1,
'tld': 'aero',
'pricing': {'registration': {'1': '44.9900',
'2': '94.9100',
'3': '144.8300'},
'renew': {'1': '49.9200', '2': '99.8400'},
'transfer': {'1': '44.9900'}},
'currencies': {'registration': 'USD', 'renew': 'USD', 'transfer': 'USD'}},
{'id': 2,
'status': 'Passive',
'maxchar': 50,
'maxperiod': 10,
'minchar': 2,
'minperiod': 1,
'tld': 'com.tr',
'pricing': {'registration': {'1': '15.5000', '2': '30.0000'},
'renew': {'1': '15.5000'},
'transfer': {'1': '0.0000'}},
'currencies': {'registration': 'TRY', 'renew': 'TRY', 'transfer': 'USD'}},
{'id': 3,
'status': 'Active',
'maxchar': 63,
'maxperiod': 10,
'minchar': 1,
'minperiod': 1,
'tld': 'xyz',
'pricing': {},
'currencies': {}}],
'result': 'OK'}
Domains
Domain Registration
Register a new domain. Contacts can be given flat (AddressLine1, Phone, ...) or nested (Address.Line1, Phone.Phone.Number, ...). Missing fields are completed and phone numbers are normalised (see validate_contact). An empty nameserver list falls back to ns1.domainnameapi.com / ns2.domainnameapi.com.
contact = {
"FirstName": "Ahmet",
"LastName": "Yilmaz",
"Company": "",
"EMail": "ahmet.yilmaz@example.com",
"AddressLine1": "Ornek Sokak No: 123",
"AddressLine2": "Daire 4",
"AddressLine3": "",
"City": "Istanbul",
"Country": "TR",
"Fax": "2121234567",
"FaxCountryCode": "90",
"Phone": "5551234567",
"PhoneCountryCode": 90,
"Type": "Contact",
"ZipCode": "34000",
"State": "Istanbul",
}
contacts = {
"Administrative": contact,
"Billing": contact,
"Technical": contact,
"Registrant": contact,
}
result = dna.register_with_contact_info(
"example.com",
1, # period (years)
contacts,
["ns1.example.com", "ns2.example.com"], # empty list -> default nameservers
True, # theft protection lock
False, # privacy protection
)
Sample output
{'data': {'ID': 0,
'Status': 'Active',
'DomainName': '',
'AuthCode': '',
'LockStatus': 'false',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'false',
'Contacts': {'Billing': {'ID': 0},
'Technical': {'ID': 0},
'Administrative': {'ID': 0},
'Registrant': {'ID': 0}},
'Dates': {'Start': '',
'Expiration': '2027-11-09T12:00:00',
'RemainingDays': 366},
'NameServers': [],
'Additional': [],
'ChildNameServers': []},
'result': 'OK'}
Domain Registration (.tr)
.tr domains need TRABIS attributes as the 7th argument. Individual owner: TRABISDOMAINCATEGORY = 1 and TRABISCITIZENID (identity number). Company owner: TRABISDOMAINCATEGORY = 0, TRABISTAXOFFICE and TRABISTAXNUMBER. Legacy keys (TRABISCITIZIENID, TRABISNAMESURNAME, TRABISCOUNTRYID, ...) are accepted: they are converted to the REST schema, unsupported ones are dropped.
individual = {
"TRABISDOMAINCATEGORY": 1,
"TRABISCITIZIENID": "11111111111",
}
commercial = {
"TRABISDOMAINCATEGORY": 0,
"TRABISTAXOFFICE": "Istanbul VD",
"TRABISTAXNUMBER": "1234567890",
}
result = dna.register_with_contact_info(
"example.com.tr",
1,
contacts,
["ns1.example.com", "ns2.example.com"],
True,
False,
individual, # or commercial
)
Sample output
{'data': {'ID': 0,
'Status': 'Active',
'DomainName': '',
'AuthCode': '',
'LockStatus': 'false',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'false',
'Contacts': {'Billing': {'ID': 0},
'Technical': {'ID': 0},
'Administrative': {'ID': 0},
'Registrant': {'ID': 0}},
'Dates': {'Start': '',
'Expiration': '2027-11-09T12:00:00',
'RemainingDays': 366},
'NameServers': [],
'Additional': [],
'ChildNameServers': []},
'result': 'OK'}
Domain Renewal
Renew a domain for the given number of years.
result = dna.renew("example.com", 1)
Sample output
{'result': 'OK', 'data': {'ExpirationDate': '2027-11-09T12:00:00'}}
Domain Details
Full details of one domain: status, dates, nameservers, lock/privacy flags, child nameservers.
result = dna.get_details("example.com")
Sample output
{'data': {'ID': 4321,
'Status': 'Active',
'DomainName': 'example.com',
'AuthCode': 'Ab1!xyZ9',
'LockStatus': 'true',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'true',
'Contacts': {'Billing': {'ID': 'DNA-B-4'},
'Technical': {'ID': 'DNA-T-3'},
'Administrative': {'ID': 'DNA-A-2'},
'Registrant': {'ID': 'DNA-R-1'}},
'Dates': {'Start': '2024-03-15T10:20:30',
'Expiration': '2027-03-15T10:20:30',
'RemainingDays': 126},
'NameServers': ['ns1.example.net', 'ns2.example.net'],
'Additional': {'TRABISDOMAINCATEGORY': '1'},
'ChildNameServers': [{'ns': 'ns1.example.com', 'ip': '192.0.2.11'},
{'ns': 'ns2.example.com', 'ip': ''}]},
'result': 'OK'}
Sync From Registry
Refresh a domain from the registry (same envelope as get_details).
result = dna.sync_from_registry("example.com")
Sample output
{'data': {'ID': 4321,
'Status': 'Active',
'DomainName': 'example.com',
'AuthCode': 'Ab1!xyZ9',
'LockStatus': 'true',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'true',
'Contacts': {'Billing': {'ID': 'DNA-B-4'},
'Technical': {'ID': 'DNA-T-3'},
'Administrative': {'ID': 'DNA-A-2'},
'Registrant': {'ID': 'DNA-R-1'}},
'Dates': {'Start': '2024-03-15T10:20:30',
'Expiration': '2027-03-15T10:20:30',
'RemainingDays': 126},
'NameServers': ['ns1.example.net', 'ns2.example.net'],
'Additional': {'TRABISDOMAINCATEGORY': '1'},
'ChildNameServers': [{'ns': 'ns1.example.com', 'ip': '192.0.2.11'},
{'ns': 'ns2.example.com', 'ip': ''}]},
'result': 'OK'}
Nameserver Modification
Replace the nameservers of a domain (entries are trimmed, lower-cased, de-duplicated).
result = dna.modify_name_server("example.com", ["ns1.example.net", "ns2.example.net"])
Sample output
{'result': 'OK', 'data': {'NameServers': ['ns1.example.net', 'ns2.example.net']}}
Enable Domain Lock
Turn the registrar (theft protection) lock on.
result = dna.enable_theft_protection_lock("example.com")
Sample output
{'result': 'OK', 'data': {'LockStatus': True}}
Disable Domain Lock
Turn the registrar (theft protection) lock off.
result = dna.disable_theft_protection_lock("example.com")
Sample output
{'result': 'OK', 'data': {'LockStatus': False}}
Modify Domain Privacy
Turn WHOIS privacy protection on (True) or off (False). 1, "1", "on", "true" and "yes" also mean on; anything else means off. The reason argument is not sent to the gateway.
result = dna.modify_privacy_protection_status("example.com", True, "Owner request")
Sample output
{'data': {'PrivacyProtectionStatus': True}, 'result': 'OK'}
Contacts
Get Domain Contacts
Administrative, Billing, Registrant and Technical contacts of a domain.
result = dna.get_contacts("example.com")
Sample output
{'data': {'contacts': {'Administrative': {'ID': 'DNA-A-2',
'Status': 'Active',
'AuthCode': '',
'FirstName': 'Grace',
'LastName': 'Hopper',
'Company': '',
'EMail': 'grace@example.com',
'Type': 'Administrative',
'Address': {'Line1': 'Example Street 2',
'Line2': '',
'Line3': '',
'State': 'DC',
'City': 'Washington',
'Country': 'US',
'ZipCode': '20001'},
'Phone': {'Phone': {'Number': '2025550100',
'CountryCode': '1'},
'Fax': {'Number': '2025550101',
'CountryCode': '1'}},
'Additional': []},
'Billing': {'ID': 'DNA-B-4',
'Status': 'Active',
'AuthCode': '',
'FirstName': 'Ada',
'LastName': 'Lovelace',
'Company': 'Example Ltd',
'EMail': 'billing@example.com',
'Type': 'Billing',
'Address': {'Line1': 'Example Street 1',
'Line2': '',
'Line3': '',
'State': 'Istanbul',
'City': 'Istanbul',
'Country': 'TR',
'ZipCode': '34000'},
'Phone': {'Phone': {'Number': '5551234567',
'CountryCode': '90'},
'Fax': {'Number': '', 'CountryCode': ''}},
'Additional': []},
'Registrant': {'ID': 'DNA-R-1',
'Status': 'Active',
'AuthCode': '',
'FirstName': 'Ada',
'LastName': 'Lovelace',
'Company': 'Example Ltd',
'EMail': 'ada@example.com',
'Type': 'Registrant',
'Address': {'Line1': 'Example Street 1',
'Line2': '',
'Line3': '',
'State': 'Istanbul',
'City': 'Istanbul',
'Country': 'TR',
'ZipCode': '34000'},
'Phone': {'Phone': {'Number': '5551234567',
'CountryCode': '90'},
'Fax': {'Number': '',
'CountryCode': ''}},
'Additional': []},
'Technical': {'ID': 'DNA-T-3',
'Status': 'Active',
'AuthCode': '',
'FirstName': 'Alan',
'LastName': 'Turing',
'Company': '',
'EMail': 'alan@example.com',
'Type': 'Technical',
'Address': {'Line1': 'Example Street 3',
'Line2': '',
'Line3': '',
'State': '',
'City': 'London',
'Country': 'GB',
'ZipCode': 'SW1A 1AA'},
'Phone': {'Phone': {'Number': '2071234567',
'CountryCode': '44'},
'Fax': {'Number': '',
'CountryCode': ''}},
'Additional': []}}},
'result': 'OK'}
Save Domain Contacts
Replace the four contacts of a domain. contacts is the same dictionary as in the registration example.
result = dna.save_contacts("example.com", contacts)
Sample output
{'result': 'OK', 'data': {'contacts': {}}}
Child Nameservers
Add Child Nameserver
Create a child nameserver (glue record) under a domain.
result = dna.add_child_name_server("example.com", "ns1.example.com", "192.0.2.10")
Sample output
{'result': 'OK',
'data': {'NameServer': 'ns1.example.com', 'IPAdresses': ['192.0.2.10']}}
Delete Child Nameserver
Delete a child nameserver.
result = dna.delete_child_name_server("example.com", "ns1.example.com")
Sample output
{'result': 'OK', 'data': {'NameServer': 'ns1.example.com'}}
Update Child Nameserver
Change the IP address of a child nameserver.
result = dna.modify_child_name_server("example.com", "ns1.example.com", "192.0.2.20")
Sample output
{'result': 'OK',
'data': {'NameServer': 'ns1.example.com', 'IPAdresses': ['192.0.2.20']}}
Transfers
Domain Transfer
Start an incoming transfer with the domain's EPP/auth code. Contacts are never sent with a transfer (the request always carries "contacts": []): the registrar takes them over from the losing registrar, so transfer has no contacts parameter. A refusal (success: false) returns a TRANSFER_DOMAIN error.
result = dna.transfer("example.com", "Ab1!xyZ9", 1)
Sample output
{'data': {'ID': 0,
'Status': 'Active',
'DomainName': '',
'AuthCode': '',
'LockStatus': 'false',
'PrivacyProtectionStatus': 'false',
'IsChildNameServer': 'false',
'Contacts': {'Billing': {'ID': 0},
'Technical': {'ID': 0},
'Administrative': {'ID': 0},
'Registrant': {'ID': 0}},
'Dates': {'Start': '',
'Expiration': '2027-11-09T12:00:00',
'RemainingDays': 366},
'NameServers': [],
'Additional': [],
'ChildNameServers': []},
'result': 'OK'}
Check Transfer
Can the domain be transferred with this auth code? result is OK only when it can.
result = dna.check_transfer("example.com", "Ab1!xyZ9")
Sample output
{'result': 'OK',
'data': {'TransferAvailabilityStatus': True,
'AuthCodeIsRequired': True,
'AuthCodeIsValid': True,
'UserTransferRequired': False,
'TransferLock': False,
'Message': 'Domain can be transferred',
'MessageKey': 'TransferAvailable',
'Additional': []}}
Cancel Transfer
Cancel a pending incoming transfer.
result = dna.cancel_transfer("example.com")
Sample output
{'result': 'OK', 'data': {'DomainName': 'example.com', 'Status': 'Cancelled'}}
Approve Outgoing Transfer
Approve a pending outgoing transfer.
result = dna.approve_transfer("example.com")
Sample output
{'result': 'OK', 'data': {'DomainName': 'example.com', 'Status': 'Approved'}}
Reject Outgoing Transfer
Reject a pending outgoing transfer.
result = dna.reject_transfer("example.com")
Sample output
{'result': 'OK', 'data': {'DomainName': 'example.com', 'Status': 'Rejected'}}
DNS Zone
The gateway stores DNS records as sets: one name + type holds a list of values. Writing a name + type
replaces the whole set, and deleting by one value removes the whole set. The *_record_set and
*_record_value methods handle this for you; prefer them over the low-level add/edit/delete_resource_record.
- Names may be given as
"@","","www","www.example.com"or"www.example.com."; they are sent as the relative label the gateway expects.get_resource_recordsreturns fully qualified names ("www.example.com."). - Supported types:
A,AAAA,ALIAS,CAA,CNAME,DS,MX,NAPTR,PTR,SRV,TLSA,TXT(others are rejected before any call is made). TTL is 1 to 86400 seconds. - Writes are applied immediately; pass
apply=Falseto stage several changes and callapply_resource_recordsonce. If the automatic apply fails, the method returns the apply error (the change stays staged but is not live). - The gateway rate-limits zone calls, so the library keeps zone calls at least one second apart
(
dna.zone_min_interval, in seconds).
List Records
DNS zone of a domain, one row per record value. Names come back fully qualified.
result = dna.get_resource_records("example.com")
Sample output
{'result': 'OK',
'data': {'records': [{'Name': 'example.com.',
'Type': 'A',
'TTL': 3600,
'Content': '192.0.2.1',
'Disabled': False},
{'Name': 'www.example.com.',
'Type': 'CNAME',
'TTL': 300,
'Content': 'example.com.',
'Disabled': False},
{'Name': 'example.com.',
'Type': 'MX',
'TTL': 3600,
'Content': '10 mx1.example.com.',
'Disabled': False},
{'Name': 'example.com.',
'Type': 'MX',
'TTL': 3600,
'Content': '20 mx2.example.com.',
'Disabled': True},
{'Name': 'example.com.',
'Type': 'TXT',
'TTL': 3600,
'Content': '"v=spf1 include:_spf.example.net ~all"',
'Disabled': False},
{'Name': 'empty.example.com.',
'Type': 'AAAA',
'TTL': 60,
'Content': '',
'Disabled': False}]}}
Set a Record Set
Make a whole name + type look exactly like the given list (the gateway's own model). An empty list removes the set. Changes are applied immediately unless apply=False.
result = dna.set_resource_record_set(
"example.com",
"@", # apex; "www", "www.example.com" also work
"MX",
["10 mx1.example.com", "20 mx2.example.com"],
3600, # TTL (1..86400)
)
Sample output
{'result': 'OK',
'data': {'Name': '',
'Type': 'MX',
'TTL': 3600,
'Contents': ['10 mx1.example.com', '20 mx2.example.com']}}
Add One Value
Add ONE value to a record set and keep the values already there (read-merge-write). Adding a value that is already present is a no-op.
result = dna.add_resource_record_value("example.com", "@", "MX", "30 mx3.example.com")
Sample output
{'result': 'OK',
'data': {'Name': '',
'Type': 'MX',
'TTL': 3600,
'Contents': ['10 mx1.example.com.',
'20 mx2.example.com.',
'30 mx3.example.com']}}
Remove One Value
Remove ONE value from a record set, leaving the others in place.
result = dna.remove_resource_record_value("example.com", "@", "MX", "20 mx2.example.com.")
Sample output
{'result': 'OK',
'data': {'Name': '', 'Type': 'MX', 'TTL': 3600, 'Contents': ['10 mx1.example.com.']}}
Replace One Value
Swap ONE value of a record set for another (the 'edit row' of a DNS panel).
result = dna.replace_resource_record_value("example.com", "@", "A", "192.0.2.1", "192.0.2.2")
Sample output
{'result': 'OK',
'data': {'Name': '', 'Type': 'A', 'TTL': 3600, 'Contents': ['192.0.2.2']}}
Delete a Record Set
Remove every value under a name + type. Removing a set that does not exist is OK.
result = dna.delete_resource_record_set("example.com", "@", "MX")
Sample output
{'result': 'OK',
'data': {'Name': 'example.com.', 'Type': 'MX', 'Content': '10 mx1.example.com.'}}
Add Record (low-level)
Low-level: write a record set (POST). The gateway replaces an existing name + type, so prefer add_resource_record_value() to append a value.
result = dna.add_resource_record("example.com", "www", "A", "192.0.2.5", 300)
Sample output
{'result': 'OK',
'data': {'Name': 'www', 'Type': 'A', 'TTL': 300, 'Content': '192.0.2.5'}}
Edit Record (low-level)
Low-level: rewrite an existing record set (PUT), identified by its current name.
result = dna.edit_resource_record("example.com", "www", "www", "A", "192.0.2.6", 600)
Sample output
{'result': 'OK',
'data': {'Name': 'www', 'Type': 'A', 'TTL': 600, 'Content': '192.0.2.6'}}
Delete Record (low-level)
Low-level: DELETE by name + value + type. The gateway removes the WHOLE set, so prefer remove_resource_record_value() to drop a single value.
result = dna.delete_resource_record("example.com", "www", "192.0.2.5", "A")
Sample output
{'result': 'OK', 'data': {'Name': 'www', 'Type': 'A', 'Content': '192.0.2.5'}}
Apply Staged Changes
Commit staged zone changes (only needed after calls made with apply=False).
dna.add_resource_record("example.com", "www", "A", "192.0.2.5", 300, False)
dna.add_resource_record("example.com", "api", "A", "192.0.2.6", 300, False)
result = dna.apply_resource_records("example.com")
Sample output
{'result': 'OK', 'data': {'DomainName': 'example.com'}}
URL Forwarding
Get Forwarding
URL forwarding of a domain. Enabled is False when nothing is configured.
result = dna.get_forwarding("example.com")
Sample output
{'result': 'OK',
'data': {'Enabled': True,
'RedirectAddress': 'https://www.example.org/landing',
'ForwardType': 'Frame'}}
Set Forwarding
Forward the domain to a URL: 'Standard' (plain redirect) or 'Frame' (masked).
result = dna.set_forwarding("example.com", "https://www.example.org", "Standard")
Sample output
{'result': 'OK',
'data': {'RedirectAddress': 'https://www.example.org', 'ForwardType': 'Standard'}}
Delete Forwarding
Remove URL forwarding. Removed is False (and result OK) when nothing was configured.
result = dna.delete_forwarding("example.com")
Sample output
{'result': 'OK', 'data': {'DomainName': 'example.com', 'Removed': True}}
Utilities
Is .tr Domain
Is this a .tr domain? Local check, no network call.
result = dna.is_tr_tld("example.com.tr")
Sample output
True
Validate Contact
Complete and normalise a contact the way the gateway expects it (local, no network): missing fields get placeholders, names lose digits/punctuation, phone numbers are split into number + country code, State falls back to City.
result = dna.validate_contact({
"FirstName": " Jo ",
"Phone": "+1 (202) 555-0100",
"Country": "Turkey",
"City": "",
"Fax": "0090 212 123 45 67",
})
Sample output
{'FirstName': 'Jo',
'Phone': '2025550100',
'Country': 'TR',
'City': 'ISTANBUL',
'Fax': '2121234567',
'LastName': 'Isimyok',
'AddressLine1': 'Addres yok',
'ZipCode': '34000',
'PhoneCountryCode': '1',
'State': 'ISTANBUL',
'FaxCountryCode': '90'}
Diagnostics and Settings
dna.get_details("example.com")
dna.get_request_data() # {'url': ..., 'method': 'GET', 'payload': {...}} of the last call
dna.get_response_data() # decoded response body of the last call ({'raw_response': ...} if not JSON)
dna.get_parsed_response_data() # body on success, {'Code', 'Message', 'Details'} on failure
dna.get_response_headers() # {'url', 'http_code', 'content_type', 'total_time', 'headers'}
dna.get_last_function() # 'request:GET domains/info'
dna.get_service_url() # 'https://api.domainresellerapi.com/api/v1'
dna.set_service_url("https://ote.domainresellerapi.com/api/v1")
dna.set_error_reporting_enabled(False)
dna.set_telemetry_minimal(True)
dna.set_ssl_verification(True)
dna.zone_min_interval = 1.0
A custom HTTP transport (proxy handling, logging, tests) can be passed to the constructor: any object with a
send(request) method that returns a domainnameapi.HttpResponse:
from domainnameapi import DomainNameAPI, HttpResponse, UrllibTransport
class LoggingTransport(UrllibTransport):
def send(self, request):
print(request.method, request.url)
return super().send(request)
dna = DomainNameAPI(reseller_id, api_key, transport=LoggingTransport())
Testing
The test suite needs no credentials and makes no external network calls:
python -m unittest discover -s tests -v
| Test file | Description |
|---|---|
tests/test_conformance.py |
Runs all 134 php-dna conformance fixtures: same requests on the wire, same return values |
tests/test_edge_cases.py |
Extra edge cases recorded from php-dna (unusual gateway responses and inputs) |
tests/test_http.py |
HTTP layer: headers, query strings, JSON bodies, timeouts, redirects |
tests/test_errors.py |
Error mapping of gateway responses |
tests/test_telemetry.py |
Telemetry payloads, credential masking, opt-out |
tests/test_utils.py |
Utilities and PHP-compatible value handling |
Return and Error Codes with Descriptions
| Code | Description | Detail |
|---|---|---|
| 1000 | Command completed successfully | Operation successful. |
| 1001 | Command completed successfully; action pending | Operation successful. However, the operation is currently queued for completion. |
| 2003 | Required parameter missing | Parameter missing error. For example, no phone entry in contact information. |
| 2105 | Object is not eligible for renewal | Domain status is not suitable for renewal, locked for update operations. Status should not be "clientupdateprohibited". May be due to other status conditions. |
| 2200 | Authentication error | Authorization error, security code is incorrect or domain is registered with another registrar. |
| 2302 | Object exists | Domain name or nameserver information already exists in database. Cannot be registered. |
| 2303 | Object does not exist | Domain name or nameserver information does not exist in database. New registration required. |
| 2304 | Object status prohibits operation | Domain status is not suitable for updates, locked for update operations. Status should not be "clientupdateprohibited". May be due to other status conditions. |
| CODE | DETAIL |
|---|---|
| 101 | System Error Detailed For ({0})! |
| 102 | Multiple Errors Detailed For ({0})! |
| 103 | Unknown Errors Detailed For ({0})! |
| 200 | API command not found ({0})! |
| 210 | API service not found ({0})! |
| 211 | API service provider not set! |
| 300 | Reseller not found! |
| 301 | Your current IP address is not authorized to access. Please make sure you are connecting from an authorized IP address and try again |
| 310 | TLD is not supported! |
| 320 | API not found! |
| 321 | Currency is not supported! |
| 330 | Required parameter(s) not set ({0}). |
| – | Make sure you send all contact objects full |
| 340 | Price definition not found ({0}[{1}]-{2}{3}). |
| 350 | Insufficient reseller balance. (Reseller Id : {0} - Current Balance : {1} {2}). |
| 350 | Accounting currency does not match or the balance is not sufficient. |
| 360 | Invalid API request for field ({0}). |
| 360 | API quota exceeded! |
| 361 | Throttled error! |
| 362 | Premium domain is not available to register right now. |
| 363 | Operation cancelled because domain in auto-renewal period |
| 364 | This domain is currently unavailable for transaction due to a problem with the registry |
| CODE | DETAIL |
|---|---|
| 400 | Invalid contact ({0}). |
| 401 | Contact info can not sync. |
| 402 | No access to contact information from registry. |
| 403 | THE SYSTEM HAS MISSING INFORMATION. ENTER YOUR DEFAULT INFORMATION OR CONTACT SUPPORT TEAM. |
| 404 | DOMAIN CONTACT CANNOT UPDATE. PERMISSION FROM THE REGISTRY. |
| 410 | Contact not found. |
| 410 | Contact not found ({0}). |
| 420 | Invalid Api command for contact {0}. |
| 430 | Contact api not found. |
| 440 | Contact is not synced. |
| 450 | Too many domain contacts! |
| 451 | Failed to proceed with contact update. |
| CODE | DETAIL |
|---|---|
| 500 | Invalid domain id. |
| 500 | Invalid domain id ({0}). |
| 501 | Domain could not synchronized({0}) |
| 502 | Internal transfer failed |
| 503 | Domain registration is not available. |
| 504 | Domain information does not match. Before :{0} |
| 505 | Enter the Ip Address. |
| 506 | Domain Transfer Has Been Started But Contact Info Not Read. |
| 507 | Authorization error. |
| 510 | Domain not found. |
| 511 | Expired domains cannot be found. |
| 512 | Domain is not renewable. |
| 513 | Domain is not in updateable status. It must be active for to be updated |
| 514 | Redemption Period Expected. |
| 520 | Invalid Api command for domain "{0}". |
| 530 | Invalid domain period. Period must be {0} to {1} years. Requested period is {2} years. |
| 540 | Domain cannot be extended beyond {0} years from current date. |
| 550 | Invalid domain name. Domain must be {0} to {1} characters length. Requested domain name is {2} characters. |
| 560 | Invalid name server count. Domain must have {0} to {1} name servers. Requested name server count is {2}. |
| 561 | No name server information found in the incoming request |
| 570 | Idn not supported for tld "{0}". |
| 571 | Period invalid. |
| 572 | Command invalid. |
| 573 | Domain names not found. |
| 574 | TLD names not found. |
| 575 | Domain is not in updateable status. It must be active for name servers to be updated |
| 576 | Domain can be renewed in the last 1 month before the expire date |
| 580 | Transfer not supported for tld "{0}". |
| 581 | Child name server not found |
| 582 | Transfer started by other reseller. |
| 583 | Transfer not initialized. Please contact the support team. |
| 584 | Object status prohibits operation |
| 590 | Auth code is required for this transfer. |
| 591 | Auth code is not valid. |
| 592 | Transfer lock exists on domain. |
| 593 | Domain cannot be transferred, Status Information and Transfer Lock must comply with the required criteria. (Status Information: #ok) |
| 594 | Domain name server address could not resolved ({0}) |
| 595 | Contact information can not be read (whois.registrar.tld) Please make sure that privacy protection status open |
| 596 | Contact information could not verified |
| 597 | Tld Not Found |
| 598 | Unknown error occurred |
| 599 | Domain Forward Not Found |
License
Apache License 2.0 — see LICENSE.
Metadata
Release files for domainnameapi 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| domainnameapi-1.0.0.tar.gz | 222.0 kB | Without provenance | Details for domainnameapi-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| domainnameapi-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for domainnameapi-1.0.0-py3-none-any.whl |
Total release size: 276.3 kB
Release files / domainnameapi-1.0.0.tar.gz
| Download URL | domainnameapi-1.0.0.tar.gz |
|---|---|
| Size | 222.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8753ffc24e65c17dd60941d1071c523106105ac6e86e301c29e57d4b09cc1cc2
|
|
BLAKE2b-256 checksum How to use checksums |
222848a348111b40e22e429b9cf11cb608769f0324df1b4d8b1004e62640e710
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.0
|
Release files / domainnameapi-1.0.0-py3-none-any.whl
| Download URL | domainnameapi-1.0.0-py3-none-any.whl |
|---|---|
| Size | 54.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
855d27ba1065a84dfd23d94a823b9efe69883d4fefc100c01014f6700005cb26
|
|
BLAKE2b-256 checksum How to use checksums |
7da0b69b781e6aef763fca2b303a40bdaca7a95a92ee9479544af53be133c80a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.0
|
Security for domainnameapi 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.