Status codes
Control how browsers and other clients handle the redirect.
Append a keyword or numeric code after the target URL in your TXT record, separated by a space:
# Default (temporary)
_redirect.www.your-domain.com. IN TXT "https://www.new-domain.com"
# Permanent redirect
_redirect.www.your-domain.com. IN TXT "https://www.new-domain.com permanent"
# Browser-only redirect
_redirect.www.your-domain.com. IN TXT "https://www.new-domain.com html"
# Specific numeric code
_redirect.www.your-domain.com. IN TXT "https://www.new-domain.com 301"Keywords
It is recommended to use redirect type keywords. Unlike numeric codes, temporary and permanent automatically select the correct code based on the request type — preserving the request method and body for form submissions and API calls without any extra configuration.
| Keyword | Behaviour |
|---|---|
temporary |
The default. Tells browsers and clients that the redirect may change in the future. Uses 302 for standard requests and 307 for form submissions and API calls, preserving the request method. |
permanent |
Tells browsers that the old address will never come back. Uses 301 for standard requests and 308 for form submissions and API calls. Use with caution — browsers cache permanent redirects indefinitely and visitors may not receive updates without clearing their cache. |
html |
Redirects web browsers only, using a 200 OK response containing an HTML page with a redirect. Other clients (apps, crawlers, API tools) receive the HTML page without being redirected. Useful when you want to avoid automatic redirect-following by non-browser clients. |
Numeric codes
You can also specify a numeric code directly. The code is sent as-is, regardless of request type.
| Code | Meaning |
|---|---|
301 | Moved Permanently |
302 | Found (temporary) |
303 | See Other |
307 | Temporary Redirect (method-preserving) |
308 | Permanent Redirect (method-preserving) |
Placeholders
Include dynamic values from the incoming request in the target URL.
Placeholders are substituted with values from the request at redirect time. Place them anywhere in the target URL within your TXT record:
# Preserve path and query string
_redirect.www.your-domain.com. IN TXT "https://www.new-domain.com{path}{?query}"
# Preserve full URI
_redirect.www.your-domain.com. IN TXT "https://www.new-domain.com{uri}"
# Keep original scheme
_redirect.www.your-domain.com. IN TXT "{scheme}://www.new-domain.com{uri}"| Placeholder | Description |
|---|---|
{scheme} | Request scheme: http or https |
{host} | Hostname of the incoming request |
{labels.*} | Individual subdomain labels by position from the right, zero-indexed. {labels.0} is the TLD, {labels.1} is the second-level domain, {labels.2} is the first subdomain, and so on. |
{hostport} | Hostname and port (e.g. your-domain.com:8080) |
{port} | Port number of the request |
{uri} | Full URI including path and query string |
{%uri} | Full URI, percent-encoded |
{path} | Request path only |
{%path} | Request path, percent-encoded |
{query} | Query string without the leading ? |
{%query} | Query string, percent-encoded, without ? |
{?query} | Query string with leading ? (omitted entirely if empty) |
{file} | Filename component of the path |
{dir} | Directory component of the path |
See placeholder usage in practice in the examples section below.
Caching
The service caches DNS lookups — changes to your TXT record take effect after the TTL expires.
When a redirect is served, the destination URL is looked up from your _redirect TXT record and cached
in memory. Subsequent requests use the cached value until it expires. The cache duration is determined by
whichever is longer: the TTL of your DNS record or a service-side minimum of 30 seconds.
To make changes propagate faster, lower the TTL on your _redirect TXT record before making changes.
A TTL of 60 seconds means most visitors will see the updated destination within a minute.
Higher TTL values improve performance by reducing DNS lookups.
Redirect responses also include a Cache-Control header reflecting the remaining DNS cache TTL.
Browsers may cache the redirect for that duration, so a visitor who has already been redirected may not
follow an updated destination until their browser cache expires.
URL encoding
Target URLs must contain only standard ASCII characters.
If your target URL contains non-English characters, they must be encoded before being placed in the TXT record:
| Character type | Encoding required | Example |
|---|---|---|
| Non-ASCII domain names | Punycode | münchen.de → xn--mnchen-3ya.de |
| Non-ASCII path or query characters | Percent-encoding | café → caf%C3%A9 |
If you use placeholders such as {path} and the path may contain non-ASCII characters, use the percent-encoded variant {%path} instead to ensure the redirect target is always valid.
Examples
Common scenarios
your-domain.com. IN A 5.161.17.225
your-domain.com. IN AAAA 2a01:4ff:f2:f9c1::1
_redirect.your-domain.com. IN TXT "https://new-domain.com{uri} permanent"blog.your-domain.com. IN CNAME http-redirect.com.
_redirect.blog.your-domain.com. IN TXT "https://medium.com/@yourname"www.old-domain.com. IN CNAME http-redirect.com.
_redirect.www.old-domain.com. IN TXT "https://www.new-domain.com{uri} permanent"app.your-domain.com. IN CNAME http-redirect.com.
_redirect.app.your-domain.com. IN TXT "https://new-app.your-domain.com{uri} html"Advanced
docs.your-domain.com. IN CNAME http-redirect.com.
_redirect.docs.your-domain.com. IN TXT "https://your-domain.com/docs{uri}"# *.old-domain.com → *.new-domain.com
*.old-domain.com. IN CNAME r.old-domain.com. ; Wildcard
r.old-domain.com. IN A 5.161.17.225
r.old-domain.com. IN AAAA 2a01:4ff:f2:f9c1::1
r.old-domain.com. IN TXT "{scheme}://{labels.2}.new-domain.com{uri}"
_acme-challenge.old-domain.com. IN CNAME _acme-challenge.d.http-redirect.com.AAAA records (IPv6) are optional but recommended to ensure the service is reachable for visitors on IPv6-only networks.