DNS tools
Preview
Connected applications are currently available to selected accounts only.
Four tools manage the records of your domains on ITSH's nameservers, the same records as in the DNS Records section of the domain page in the portal. The application names the domain, in Unicode or ASCII form. For record types and what each field means, see DNS records.
A change is live for the whole internet
A record change is served to everyone within the record's TTL. MX, CNAME, NS, CAA, _acme-challenge and _itsh-mail records decide where your mail and traffic go, who may issue certificates for the domain and who may host its mail. The tools tell the application to confirm each change with you; read what it proposes before you agree.
The tools
| Tool | What it does | Needs |
|---|---|---|
dns_record_list | Lists the records, optionally of one name or type. Records a DynDNS token manages are left out | domain:read, dns:read |
dns_record_create | Adds a record. If the same record exists already nothing is added, so a retry is safe | domain:read, dns:write |
dns_record_update | Changes the fields given, by the record's id. The result carries the record before and after | domain:read, dns:write |
dns_record_delete | Deletes a record by its id, name and type, which must all still match. The result carries the deleted record, the only way to put it back | domain:read, dns:write |
The name is @ for the domain itself, a name relative to it such as www, or the full name. An MX, CNAME or NS target without a dot is completed with the domain, as the portal does.
Accepted values
| Field | Accepted | Default |
|---|---|---|
| TTL | 300 to 86,400 seconds | 3,600 |
| Priority | 0 to 65,535, only on MX, SRV, URI, HTTPS, SVCB and NAPTR | 10 |
| Content | Up to 4,096 characters, no control characters | None |
| Type | Up to 12 letters and digits | None |
What is refused, and why
NS and SOA records
While a domain uses ITSH's nameservers, its NS and SOA records are the zone's own and cannot be changed or deleted. A delete is refused with, for example:
NS records cannot be deleted while example.com uses ITSH's nameservers.
Nameservers are changed under Nameservers on the domain's page in the portal, not with these tools.
Invisible characters
A domain, name or type is refused if it contains a character that displays as nothing or reorders its neighbours, such as U+202E or U+3164, or if it starts or ends with a space character outside ASCII:
name contains an invisible character.
name starts or ends with a space character outside ASCII.
The reason: such a name converts to a valid label that reads reordered or blank wherever it is shown, so the name you are asked to approve is not the name that gets written. Nobody types these characters on purpose. Content is refused only for control characters: content contains a control character.
Domains on other nameservers
A domain whose nameservers point elsewhere is refused with external_nameservers, because its records at ITSH are not what the internet sees. The reply tells the application to change the record at the DNS provider the nameservers point to, and links to the domain's page in the portal, which shows its nameservers. See Using your own nameservers.
Other refusals
| Code | Cause |
|---|---|
dyndns_managed | "A DynDNS token manages this name, so its A and AAAA records change only through DynDNS." |
record_mismatch | The id passed to a delete now belongs to a different record. Nothing is deleted |
Limits
| Limit | Value |
|---|---|
| Record requests | 10 a minute per account, across all its connections. Listing counts 1, adding 1 (2 if the record exists already), changing and deleting 2 |
| Registrar calls | 6 a minute per account, across all its connections |
| Registrar calls per tool call, at most | Listing 1, adding 5 (6 if the record exists already), changing 5, deleting 4, plus 1 to check the domain's nameservers, at most once every 5 minutes per domain |
| Time per call | 45 seconds |
Each call reserves its registrar calls up front, so in practice an account's applications add about one record a minute. A call that cannot be covered is refused before it starts with registrar_budget_exhausted and the seconds to wait:
the applications connected to this account have used its registrar calls for now, retry in 42 seconds
The same code with "the registrar is busy with other work right now" means the registrar's capacity for all connected applications is in use; it is not specific to your account. A change that runs into the 45-second limit may or may not have been made, so the application should list the records before trying again.
What's next
- Email tools for writing the mail records in one step
- Managing connections for what each change recorded