Connect your own domain
Use an address on a domain you control.
Customer-domain inboxes let you send and receive as an address such as research-agent@agents.example.com. They do not consume the managed starter allowance, but verified-domain policy and traffic limits still apply.
You need control of the domain's DNS, domain:manage to configure it, and mailbox:manage to create an inbox. Use an organization enabled for customer-domain inboxes; if your trial is restricted, contact the team.
1. Register a dedicated subdomain
We recommend a dedicated subdomain such as agents.example.com, especially if your root domain already uses Google Workspace or Microsoft 365.
curl --fail-with-body --silent --show-error \
"$MAILACTOR_API_URL/v1/domains" \
-H "x-api-key: $MAILACTOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"agents.example.com"}'Save the returned domain id as DOMAIN_ID. After a lost response, list domains and match the normalized domain name before registering again.
2. Publish the returned DNS records
The domain response includes dnsRecords. Publish each record exactly as returned. TXT records use name and value; MX records also include priority. The instructions cover ownership, DKIM, and inbound mail routing. Follow any additional onboarding instructions for SPF and DMARC.
Your DNS provider may append your zone name automatically, so check whether it expects a relative or fully qualified record name.
Keep existing company mail working
Changing a domain's MX changes where incoming mail for that domain goes. Ordinary MX records cannot send only selected root-domain addresses to Mailactor while leaving others at another provider. Use a dedicated subdomain unless you have deliberately configured split delivery with your existing provider.
3. Verify both capabilities
curl --fail-with-body --silent --show-error -X POST \
"$MAILACTOR_API_URL/v1/domains/$DOMAIN_ID/verify" \
-H "x-api-key: $MAILACTOR_API_KEY"An HTTP 200 is not enough: inspect the verification result. Wait for both capabilities.outbound and capabilities.inbound to be true before creating a two-way inbox. DNS propagation and caching may delay verification. Poll with bounded backoff and a deadline; if records are still pending, check DNS and resume later.
Keep the original registered domain resource. The verification response describes checks and capabilities; it is not a replacement domain object and does not supply the domain ID.
4. Create the inbox
PAYLOAD=$(jq -n --arg domainId "$DOMAIN_ID" \
'{localPart:"research-agent",displayName:"Research Agent",domainId:$domainId}')
curl --fail-with-body --silent --show-error \
"$MAILACTOR_API_URL/v1/inboxes" \
-H "x-api-key: $MAILACTOR_API_KEY" \
-H "Content-Type: application/json" \
-d "$PAYLOAD"Check domainKind: "customer" and that the returned domainId matches your registered domain. Save the returned inbox ID and exact address, then send and receive with that inbox.
Keep DNS in place
Mailactor rechecks verified domain capabilities when they become stale and the domain is used. After the bounded grace period, missing verification records can block sending, new inbox creation, or inbound acceptance. Preserve the required DNS records while using the domain.
Domain removal and changes to traffic policy currently go through the team. There is no public domain-delete or policy-update endpoint.