Connect a domain

Every inbox starts on trotta.email. Put yours on your own name instead, for humans and for agents: five records at any DNS provider, or one click where your provider supports it. Your own domain is part of the paid plans.

#Three steps in the console

  1. Add your domain. Open Domains and type the name.
  2. Publish its records. Copy the five records into your DNS provider, or import the zone file, then check them. Where your provider supports one click, a button above them does it for you.
  3. Create your mailbox. Once the domain is verified, create your own mailbox on it and add inboxes for your agents.

#Add the domain

shell
curl -X POST https://api.trotta.email/v1/domains \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents.example.com"}'

The response lists the five records and the zone the domain lives in. Use a subdomain such as agents.example.com to leave mail for the name above it where it is.

#The records, by hand

This works at every DNS provider.

PurposeTypeWhat it is for
ownershipTXTProves the domain is yours.
inboundMXRoutes mail for the domain to Trotta Mail, so it is screened on arrival.
spfTXTSays Trotta Mail may send for the domain.
dkimTXTThe public key that outgoing mail is signed against.
dmarcTXTTells receivers what to do with mail that fails the two checks above.
  • Each record has its name in full and its host, the part before the zone (@ for the zone itself). Most providers ask for the host; some want the full name.
  • Already have an SPF record? Keep one: after a check, the spf value is your record with ours merged in.
  • GET /v1/domains/{id}/zone-file returns the same records as a BIND zone file to import. Use the values from your own response, not from an example.

#One click, where your provider supports it

Domain Connect lets you approve the records at your DNS provider. You sign in there, see the changes and approve. We never see your password or a token. It works once your provider has switched on Trotta Mail.

shell
curl -X POST https://api.trotta.email/v1/domains/dom_2Yq5hLf6/connect \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
  • available: true comes with provider and url: open the link in a browser. Your provider sends you back to the console, which checks the records.
  • available: false comes with a reason: add the records by hand.
  • Your provider merges our SPF include into yours. An existing DMARC policy is never replaced.
  • If mail for the name goes elsewhere today, the call answers 409 mx_conflict. Send replace_mx: true to move it here.

#Verify

POST /v1/domains/{id}/verify checks again, asking the zone's own name servers first, so a record published a moment ago is seen. Each record comes back ok, missing or wrong (something else is there, listed in found). The domain is verified once the ownership and inbound records are in place, and a domain.verified event is sent. Publish the other three before you send from it.

#Your own mailbox on it

Signed in, create a mailbox for yourself with kind: "human". It is yours alone. You can sign in with it or with your trotta.email address, and make it your main address, the one the app shows and writes from by default.

shell
# as the signed-in human, or with a key that human made
curl -X POST https://api.trotta.email/v1/inboxes \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "jordan", "kind": "human", "domain": "example.com"}'

POST /v1/auth/main-address with that inbox's id makes it the main address. Mailboxes for teammates on the same domain come from Team and seats.

#Agent inboxes on it

shell
curl -X POST https://api.trotta.email/v1/inboxes \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "riley", "domain": "agents.example.com"}'

Your own domain needs a paid plan: 3 on Developer, 25 on Startup. See plans and limits. On Free, adding one answers 403 domain_limit_reached.

If a plan stops covering a domain that is already connected, the domain is paused, not deleted. Mail for it still arrives and stays in the inbox. Sending from it answers 403 custom_domain_paused until the plan covers it again. Nothing has to be set up twice.