1. Core Concepts
  • Welcome to the Cold Mail Reseller API
  • Get Started
    • Overview
    • Authentication
    • Quick Start
  • Core Concepts
    • Users
    • Domains
    • DNS Management
    • Mailboxes
    • Subscriptions
    • Pre-Warmup
    • Domain Renewal
    • 1+ Year Subscriptions
    • Mailbox Warmup
    • Platform Exports
    • OAuth Exports
    • Sandbox API
  • API Reference
    • Users
      • List Users
      • Get User
      • Create User
      • Update User
      • Delete User
    • Geo
      • List Countries
      • List States
    • Domains
      • Domain Renewal
        • Get Domain Renewal Prices
        • Renew Domains
        • Toggle Domain Auto-Renew
      • Get Domains by User
      • Check Domain Availability
      • Check Single Domain Availability
      • Check Workspace Existence
      • Set Domain Forwarding
      • Set Email Forwarding
      • Delete Domains
    • DNS
      • Get DNS Records
      • Add DNS Records
      • Update DNS Record
      • Update Nameservers
      • Delete DNS Record
    • Mailboxes
      • List Mailboxes
      • Get Mailboxes by User
      • Get Mailbox
      • Get Admin Mailbox Details
      • Update Mailbox Details
      • Delete Mailbox
    • Mailbox Warmup
      • Add Warmup to Mailbox
      • Toggle Warmup
      • Update Warmup Settings
      • Set Warmup Status
      • Disable Warmup
    • Orders
      • Get Order Status
      • Get Order Details
      • Create Order
      • Create Order (JSON)
      • Create Mailbox Order (JSON)
      • Process Order
    • Subscriptions
      • 1+ Year Subscription
        • Recreate Subscription
      • Get Subscriptions
      • Renew Subscriptions
      • Cancel Subscription
      • Toggle Auto-Renewal
    • Exports
      • Platform Exports
        • Get Platform Credentials
        • Add Platform Credential
        • Export Mailboxes to Platform
        • Remove Platform Credential
      • OAuth Exports
        • Perform OAuth
        • Add Client ID to Domains
    • Pre-Warmup
      • Sandbox
        • Get Sandbox Pre-warmup Domains
        • Order Sandbox Pre-warmup
        • Reset Sandbox Pre-warmup
      • Get Pre-warmup Domains
      • Order Pre-warmup
    • Placement Test
      • Create Placement Order
      • Get Placement Reports
  • Resources
    • Errors
    • Rate Limits
    • Pagination
    • Sandbox
    • MCP
  • Webhooks
    • Overview
    • Events
      • Domain Events
      • Mailbox Events
      • Subscription Events
      • Prewarmup Events
      • Mailbox Warmup Events
  • Schemas
    • Error
    • Success
    • MessageResponse
    • User
    • Domain
    • ErrorResponse
    • Mailbox
    • Subscription
    • DnsRecord
    • Error Response
    • Pagination Meta
    • Action Error Response
    • PrewarmupOrderResult
    • OrderCreationResult
  1. Core Concepts

DNS Management

The DNS API lets you manage DNS records and nameservers for domains registered under your partner account.
Use it to add email authentication records (SPF, DKIM, DMARC), set MX records, or update nameservers.

Quick Reference#

AspectInformation
Route prefix/dns
AuthAPI key + userId query param on all endpoints
ScopeDomain must be owned by the specified user

Available Endpoints#

MethodEndpointDescription
GET/dnsList all DNS records for a domain
POST/dnsAdd one or more DNS records
PUT/dnsUpdate an existing DNS record
DELETE/dnsDelete a DNS record
PUT/dns/nameserversUpdate nameservers for a domain

DNS Record Fields#

FieldTypeRequiredDescription
hoststringYesRecord host/name (e.g. @, mail, _dmarc)
valuestringYesRecord value
recordTypestringYesA, CNAME, MX, TXT, NS, etc.
prioritystringNoUsed for MX records
excludedDMARCtagsstring[]NoDMARC TXT records only — tags to omit from the generated DMARC value
INFO
excludedDMARCtags is only valid on TXT records where host is _dmarc or starts with _dmarc.. Passing it on any other record type returns a 400.

Key Concepts#

Listing DNS records
Adding records
Updating a record
Deleting a record
Updating nameservers
DMARC and excludedDMARCtags

Common Record Types for Cold Email#

RecordTypePurpose
@MXRoutes inbound email to the mail server
@TXTSPF record — authorizes sending servers
mail._domainkeyTXTDKIM public key — signs outbound messages
_dmarcTXTDMARC policy — instructs receivers what to do with failures

Scenarios#

Add Email Authentication Records#

1
Add SPF record
POST /dns?userId= — add a TXT record at @ with your SPF value, e.g. v=spf1 include:sendgrid.net ~all.
2
Add DKIM record
POST /dns?userId= — add a TXT record at mail._domainkey with the public key value provided by your mail provider.
3
Add DMARC record
POST /dns?userId= — add a TXT record at _dmarc. Use excludedDMARCtags if you want to omit specific DMARC tags from the generated value.
4
Verify records
GET /dns?userId=&domain= — confirm all records are present and correct before sending.

Update Nameservers#

1
Update nameservers
PUT /dns/nameservers — pass the domain and the new nameservers array.
2
Wait for propagation
Nameserver changes can take up to 48 hours to propagate globally. Verify using an external DNS lookup tool.

Update an Existing Record#

1
List records
GET /dns?userId=&domain= — find the recordId of the record you want to update.
2
Update
PUT /dns?userId= — pass recordId, domain, and the updated field values.

Avoid These Common Issues#

Missing recordId for updates and deletes — recordId is returned when a record is created. Store it or retrieve it from GET /dns before calling PUT or DELETE.
excludedDMARCtags on non-DMARC records — this field is only valid on TXT records with host = "_dmarc". Using it on any other record type returns a 400.
Nameserver propagation delay — PUT /dns/nameservers returns immediately but changes take time to propagate. Do not assume records are live immediately after the API call.
Incorrect userId — the domain must be owned by the specified user. A mismatch returns a 403 or 404.

Next Steps#

Domains
Full domain management guide — search, forwarding, removal.
Domain Renewal
Renewal windows, grace periods, and eligibility rules.
Domain Events
Webhooks for registration and renewal outcomes.
Modified at 2026-08-05 16:12:50
Previous
Domains
Next
Mailboxes
Built with