Skip to content

API: Masking

← API overview

GET /v1/masking · scope: read · MCP tool: get_masking

Masking status of every domain, and the DNS provider keys on file.

state is one of: off, applying, needs_input (we need DNS access: see needs), pending_ns (nameservers are switching), active, drift (DNS changed underneath us), failed, self_service_pending / _partial / _verified. dns_keys lists the DNS provider keys connected for masking (never the key itself).

Terminal window
curl -X GET "https://api.maildeck.co/v1/masking" \
-H "Authorization: Bearer $MAILDECK_API_KEY"

POST /v1/masking · scope: write · MCP tool: enable_masking

Turn masking on for domains: they will show the destination website.

Changes DNS for each domain (and may switch its nameservers), so confirm with the person first. Answers at once with state “applying”; follow progress with get_masking. state is one of: off, applying, needs_input (we need DNS access: see needs), pending_ns (nameservers are switching), active, drift (DNS changed underneath us), failed, self_service_pending / _partial / _verified. Per-domain errors: domain_not_found, not_live (inboxes not delivered yet), managed_elsewhere.

Body fieldTypeRequiredNotes
domainsarray of stringyesDomains from list_domains
destinationstringyesThe real website to show, e.g. “https://acme.com”. Not one of the sending domains. up to 500 chars
moderedirect / mirror / self_servicenoredirect (default) sends visitors to the site; mirror shows it under the sending domain; self_service means the person sets DNS themselves
keep_in_own_cloudflarebooleannoKeep moved domains in the customer’s own Cloudflare account (needs a connected Cloudflare key)
manual_nameserver_changebooleannoThe person will switch nameservers by hand instead of us doing it
idempotency_keystringyesAny unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars
confirmbooleanyesMust be true. Confirms the person has agreed to this action
Terminal window
curl -X POST "https://api.maildeck.co/v1/masking" \
-H "Authorization: Bearer $MAILDECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":[],"destination":"…","idempotency_key":"a-unique-string","confirm":true}'

DELETE /v1/masking · scope: write · MCP tool: disable_masking

Turn masking off for domains and remove the DNS records it added.

Body fieldTypeRequiredNotes
domainsarray of stringyes
idempotency_keystringyesAny unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars
confirmbooleanyesMust be true. Confirms the person has agreed to this action
Terminal window
curl -X DELETE "https://api.maildeck.co/v1/masking" \
-H "Authorization: Bearer $MAILDECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":[],"idempotency_key":"a-unique-string","confirm":true}'

GET /v1/masking/guide · scope: read · MCP tool: get_masking_guide

Which DNS providers masking supports, and exactly which key each one needs.

Per provider: the fields add_masking_credential expects and the steps to create a key with the right permissions. Account passwords and Cloudflare Global API Keys are refused; only scoped API keys are taken.

Terminal window
curl -X GET "https://api.maildeck.co/v1/masking/guide" \
-H "Authorization: Bearer $MAILDECK_API_KEY"

POST /v1/masking/credentials · scope: write · MCP tool: add_masking_credential

Connect a DNS provider API key so masking can set DNS records.

For Cloudflare send the scoped API token as token. For Porkbun, Namecheap or GoDaddy send secret with the fields named in get_masking_guide. To reuse a registrar key already given during order setup, send saved_id from get_masking. The key is checked at once and never returned.

Body fieldTypeRequiredNotes
providerstringnocloudflare, porkbun, namecheap or godaddy. up to 40 chars, default "cloudflare"
tokenstringnoCloudflare scoped API token. up to 2000 chars
secretobjectnoProvider key fields, as named in get_masking_guide
saved_idstringnoReuse a registrar key saved during setup (saved_registrar_keys in get_masking). up to 80 chars
domainstringnoA domain this key is for, so a waiting mask picks it up at once. up to 253 chars
idempotency_keystringyesAny unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars
Terminal window
curl -X POST "https://api.maildeck.co/v1/masking/credentials" \
-H "Authorization: Bearer $MAILDECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"idempotency_key":"a-unique-string"}'

POST /v1/masking/verify · scope: write · MCP tool: verify_masking

Ask for masked domains to be re-checked now (after a DNS or nameserver change).

Body fieldTypeRequiredNotes
domainsarray of stringyes
idempotency_keystringyesAny unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars
Terminal window
curl -X POST "https://api.maildeck.co/v1/masking/verify" \
-H "Authorization: Bearer $MAILDECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":[],"idempotency_key":"a-unique-string"}'