Address

Guides

Companies and domains

Authorise a company by its domain, give out its addresses, and run its admins and holders.

Markdown

A company proves it controls its domain once. It receives a company subdomain of seleya.email, such as acme.seleya.email. It can also set up its own mail subdomain, agents.acme.com, by publishing the mail records we provide. Mail from the company’s proven domains counts as from colleagues.

The proven company domain (acme.com) identifies the company. It is distinct from the domains on which new agent addresses are issued (acme.seleya.email and, once verified, agents.acme.com). This does not move the company’s existing email.

Authorise a company

POST /v1/companies starts it, at address.seleya.ai or by an agent acting for the person who runs it:

curl
curl -X POST https://address.seleya.ai/api/v1/companies \
  -H "Authorization: Bearer $SELEYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Robotics Ltd", "domain": "acme.com", "country": "ZA", "method": "dns"}'

  • name is the legal name and country where it is registered. Both are screened against sanctions lists.
  • domain is the domain the company’s people’s email is on, not a subdomain.
  • method is how it proves the domain: dns, one text record we give you; or mail, the mail records that let agents.<domain> send and receive here, which prove the domain too.

The answer lists the records. Publish them at the domain’s DNS host, then call POST /v1/companies/authorisations/{id}/check. DNS changes can take a few minutes to be seen. Once proven, the company is set up (its subdomain, its sending and its records), which takes a few minutes more; the authorisation’s status then reads done, with the company.

Give out addresses

An admin gives out an address with POST /v1/addresses:

FieldWhat it is
localThe name before the @
display_nameThe name people see; it must say it is an agent
domainOptional: the company’s seleya.email subdomain (the default), or its own verified mail subdomain
holder_emailThe person accountable for it, who is told by email
labelNames the address’s first key

The answer carries the address’s first key, shown once. For example, pass "domain": "agents.acme.com" to issue desk@agents.acme.com after that mail domain is verified. Someone whose email is at the company’s proven domain can also claim an address on its seleya.email subdomain with POST /v1/addresses/self.

Keys

An address key acts for one address. An owner key (POST /v1/keys with owner) acts for every address the company owns, for the company’s own automation. To rotate a key, make a second, move the agent to it, then revoke the first.

Admins and holders

  • Admins run the company: its addresses, keys, billing and admins. A company keeps at least one.
  • A holder is the person accountable for one address. Moving it to someone else keeps the address and its history.
  • Retiring an address stops it receiving and sending and ends its keys. Its name is never given out again.

From a key or app, adding or removing an admin, changing a holder and retiring wait for the company’s admins (What only a person may do).

Docs