references/namecheap-api.md
Namecheap API Reference
Base URL
https://api.namecheap.com/xml.response
Authentication
All requests require these common parameters:
| Parameter | Description |
|-----------|-------------|
| ApiUser | Namecheap username |
| ApiKey | API key from https://ap.www.namecheap.com/settings/tools/apiaccess/ |
| UserName | Same as ApiUser |
| ClientIp | The whitelisted public IP address of the client |
| Command | The API command prefixed with namecheap. |
Setup Requirements
- Log in to Namecheap
- Go to https://ap.www.namecheap.com/settings/tools/apiaccess/
- Enable API Access (toggle to ON)
- Add the client's public IP address to the whitelist
- Copy the generated API key
Commands
namecheap.domains.getList
Lists all domains in the account.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| ListType | No | ALL (default), EXPIRING, or EXPIRED |
| SearchTerm | No | Keyword to filter domains |
| Page | No | Page number (default: 1) |
| PageSize | No | Results per page, 10-100 (default: 20) |
| SortBy | No | NAME, NAME_DESC, EXPIREDATE, EXPIREDATE_DESC, CREATEDATE, CREATEDATE_DESC |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.getList">
<DomainGetListResult>
<Domain ID="123" Name="example.com" User="user" Created="01/01/2020"
Expires="01/01/2025" IsExpired="false" IsLocked="true" AutoRenew="true"
WhoisGuard="ENABLED" />
</DomainGetListResult>
<Paging><TotalItems>5</TotalItems><CurrentPage>1</CurrentPage><PageSize>20</PageSize></Paging>
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.getList
Gets the list of DNS servers associated with a domain (shows whether it uses Namecheap DNS or custom nameservers).
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain (e.g., example for example.com) |
| TLD | Yes | Top-level domain (e.g., com for example.com) |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.getList">
<DomainDNSGetListResult Domain="example.com" IsUsingOurDNS="true">
<Nameserver>dns1.registrar-servers.com</Nameserver>
<Nameserver>dns2.registrar-servers.com</Nameserver>
</DomainDNSGetListResult>
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.getHosts
Gets DNS host records for a domain.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain (e.g., example for example.com) |
| TLD | Yes | Top-level domain (e.g., com for example.com) |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.getHosts">
<DomainDNSGetHostsResult Domain="example.com" IsUsingOurDNS="true">
<host HostId="1" Name="@" Type="A" Address="1.2.3.4" MXPref="0" TTL="1800" />
<host HostId="2" Name="www" Type="CNAME" Address="example.com." MXPref="0" TTL="1800" />
<host HostId="3" Name="@" Type="MX" Address="mail.example.com." MXPref="10" TTL="1800" />
<host HostId="4" Name="@" Type="TXT" Address="v=spf1 include:_spf.google.com ~all" MXPref="0" TTL="1800" />
</DomainDNSGetHostsResult>
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.setHosts
Sets (replaces) all DNS host records for a domain.
IMPORTANT: This command replaces ALL existing records. Always fetch existing records first.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
| HostNameN | Yes | Host name for record N (e.g., @, www, mail) |
| RecordTypeN | Yes | Record type for record N (A, AAAA, CNAME, MX, TXT, etc.) |
| AddressN | Yes | Value for record N (IP address or target hostname) |
| MXPrefN | No | MX priority for record N (required for MX records) |
| TTLN | No | TTL in seconds for record N (default: 1800) |
Records are numbered starting from 1: HostName1, RecordType1, Address1, HostName2, RecordType2, Address2, etc.
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.setHosts">
<DomainDNSSetHostsResult Domain="example.com" IsSuccess="true" />
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.setDefault
Sets a domain to use Namecheap's default DNS servers.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.setDefault">
<DomainDNSSetDefaultResult Domain="example.com" Updated="true" />
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.setCustom
Sets a domain to use custom nameservers (e.g., Cloudflare, Route53).
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
| Nameservers | Yes | Comma-separated list of nameservers (max 12, no spaces) |
Example: Nameservers=ns1.cloudflare.com,ns2.cloudflare.com
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.setCustom">
<DomainDNSSetCustomResult Domain="example.com" Updated="true" />
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.getEmailForwarding
Gets email forwarding settings for a domain.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| DomainName | Yes | Full domain name (e.g., example.com) |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.getEmailForwarding">
<DomainDNSGetEmailForwardingResult Domain="example.com">
<Forward mailboxid="1" mailbox="info" ForwardTo="[email protected]" />
<Forward mailboxid="2" mailbox="support" ForwardTo="[email protected]" />
</DomainDNSGetEmailForwardingResult>
</CommandResponse>
</ApiResponse>
namecheap.domains.dns.setEmailForwarding
Sets email forwarding for a domain. Replaces all existing forwarding rules.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| DomainName | Yes | Full domain name (e.g., example.com) |
| MailBoxN | Yes | Mailbox name for rule N (e.g., info, support) |
| ForwardToN | Yes | Destination email for rule N |
Rules are numbered starting from 1: MailBox1, ForwardTo1, MailBox2, ForwardTo2, etc.
Omitting all MailBox/ForwardTo parameters deletes all forwarding rules.
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.dns.setEmailForwarding">
<DomainDNSSetEmailForwardingResult Domain="example.com" IsSuccess="true" />
</CommandResponse>
</ApiResponse>
namecheap.domains.ns.create
Creates a child nameserver (glue record) for a domain.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
| Nameserver | Yes | Nameserver hostname to create (e.g., ns1.example.com) |
| IP | Yes | IP address for the nameserver |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.ns.create">
<DomainNSCreateResult Domain="example.com" Nameserver="ns1.example.com" IP="1.2.3.4" IsSuccess="true" />
</CommandResponse>
</ApiResponse>
namecheap.domains.ns.delete
Deletes a child nameserver.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
| Nameserver | Yes | Nameserver hostname to delete |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.ns.delete">
<DomainNSDeleteResult Domain="example.com" Nameserver="ns1.example.com" IsSuccess="true" />
</CommandResponse>
</ApiResponse>
namecheap.domains.ns.getInfo
Gets information about a child nameserver.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
| Nameserver | Yes | Nameserver hostname to query |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.ns.getInfo">
<DomainNSInfoResult Domain="example.com" Nameserver="ns1.example.com" IP="1.2.3.4">
<NameserverStatuses>
<Status>OK</Status>
</NameserverStatuses>
</DomainNSInfoResult>
</CommandResponse>
</ApiResponse>
namecheap.domains.ns.update
Updates the IP address of a child nameserver.
Additional Parameters:
| Parameter | Required | Description |
|-----------|----------|-------------|
| SLD | Yes | Second-level domain |
| TLD | Yes | Top-level domain |
| Nameserver | Yes | Nameserver hostname to update |
| OldIP | Yes | Current IP address of the nameserver |
| IP | Yes | New IP address for the nameserver |
Response XML:
<ApiResponse Status="OK">
<CommandResponse Type="namecheap.domains.ns.update">
<DomainNSUpdateResult Domain="example.com" Nameserver="ns1.example.com" IsSuccess="true" />
</CommandResponse>
</ApiResponse>
Error Responses
<ApiResponse Status="ERROR">
<Errors>
<Err Code="2019166">Domain not found</Err>
</Errors>
</ApiResponse>
Common error codes:
1011102— Invalid API key1011148— IP not whitelisted2019166— Domain not found2016166— Domain not using Namecheap DNS
Record Types
| Type | Description | Address Format |
|------|-------------|---------------|
| A | IPv4 address | 1.2.3.4 |
| AAAA | IPv6 address | 2001:db8::1 |
| CNAME | Canonical name | target.example.com. |
| MX | Mail exchange | mail.example.com. (requires MXPref) |
| MXE | MX equivalent (IP) | 1.2.3.4 |
| TXT | Text record | Any text value |
| URL | URL redirect (unmasked) | http://example.com |
| URL301 | Permanent redirect | http://example.com |
| FRAME | URL redirect (masked) | http://example.com |
TTL Values
| Seconds | Human Readable | |---------|---------------| | 60 | 1 minute | | 300 | 5 minutes | | 1800 | 30 minutes (default) | | 3600 | 1 hour | | 14400 | 4 hours | | 43200 | 12 hours | | 86400 | 1 day |