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
- Add your domain. Open Domains and type the name.
- 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.
- Create your mailbox. Once the domain is verified, create your own mailbox on it and add inboxes for your agents.
#Add the domain
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.
| Purpose | Type | What it is for |
|---|---|---|
ownership | TXT | Proves the domain is yours. |
inbound | MX | Routes mail for the domain to Trotta Mail, so it is screened on arrival. |
spf | TXT | Says Trotta Mail may send for the domain. |
dkim | TXT | The public key that outgoing mail is signed against. |
dmarc | TXT | Tells receivers what to do with mail that fails the two checks above. |
- Each record has its
namein full and itshost, 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
spfvalue is your record with ours merged in. GET /v1/domains/{id}/zone-filereturns 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.
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: truecomes withproviderandurl: open the link in a browser. Your provider sends you back to the console, which checks the records.available: falsecomes with areason: 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. Sendreplace_mx: trueto 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.
# 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
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"}'#A paid feature
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.