lupin.Open console
Email

Set up a custom email domain and diagnose DNS verification

Publish the returned records, distinguish verification failures and avoid confusing ownership with deliverability.

Lupin editorialAI-assisted3 min read

Choose a domain with clear ownership

Use a dedicated subdomain such as mail.example.com when you want agent email to have a separate operational boundary from a company’s existing mailbox setup. Confirm who controls DNS and which mail services already use that name before changing records. Custom domains are unavailable to an autonomous bootstrap key, and its initial workspace domain allowance is zero. A human owner must first grant appropriate access and ensure the workspace policy allows the resource. Domain registration in the API is not the same as buying a domain name from a registrar.

Publish the API’s exact record set

Create the domain with POST /v0/domains and the domain name in the request body. The returned setup includes ownership TXT, MX, SPF, DKIM and DMARC records; subdomain support adds wildcard MX requirements. Use those returned values rather than copying records from another workspace or guessing a provider selector. GET /v0/domains/:id/zone-file can render the setup as BIND text, and the setup-link route provides a console URL. Keep a change record of the DNS names, values and existing records so an operator can diagnose collisions without exposing private credentials.

Requires an authorized domain-capable workspace; creates configuration rather than sending email.
curl --fail-with-body -X POST https://api.lupin.sh/v0/domains \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com","tracking_enabled":false}'

Verify and classify the result

POST /v0/domains/:id/verify checks ownership through live DNS-over-HTTPS. Missing required records leave the domain PENDING with dns_records_missing; incorrect values produce dns_records_invalid. Transient provider or DNS failures can return retryable ses_* reasons. Compare the actual record name and value, including whether the DNS editor automatically appends the zone name, before repeatedly retrying. A successful verification transitions the domain to VERIFIED and emits domain.verified. That proves the configured ownership check passed; it is not a promise that every future recipient server will accept each outgoing message.

Treat authentication as an ongoing setup

SPF, DKIM and DMARC serve different email-authentication roles, so preserve each required record instead of assuming the ownership TXT replaces them. Coordinate any SPF changes with existing senders and avoid blindly publishing competing SPF policies at the same name. If you later enable subdomains_enabled, expect the domain to return to PENDING until the wildcard MX exists. Set feedback_enabled when the intended workflow needs bounce and complaint feedback, and tracking_enabled when open tracking is required. Neither option should be described as proof that a human read the email.

Prove routing before scaling traffic

After verification, create or select an authorized inbox using the verified domain and inspect its returned address. Make any eventual delivery check a separately authorized action with a controlled recipient and preserved send identity. Do not send production campaigns merely to test DNS propagation. Keep an operational checklist for record removal, domain deletion and inbox dependencies before retiring the domain. Your next step is to compare every returned record with the authoritative DNS zone and run verification once the records are visible, then record the resulting status and specific failure reason if it remains pending.

Keep DNS changes reversible

Save the prior DNS zone state before adding mail records. If a provider migration is involved, coordinate MX changes with the team that owns existing inbound delivery; replacing MX records can redirect mail beyond this one agent. An API verification result cannot tell you whether that separate organization-wide routing change was intended or approved.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore email Register an agent