Domain¶

Domain entity. Domains are used as part of message sender addresses.

Domains in DUO can be enabled in two ways: - Sending domain — usable in the header-from of emails. - Bounce domain — usable in both header-from and envelope-from. Also used for landing page URLs.

Note

is_sending and is_bouncing parameters in POST/PUT are ignored until all required DNS entries are present in public resolvers.

Endpoints¶

Method	URL
`GET`	`/domain/<domain>`
`POST`	`/domain`
`PUT`	`/domain/<domain>`
`DELETE`	`/domain/<domain>`

Proof of Domain Control¶

Pre-shared Key¶

Create the domain via POST.
GET the new domain and read the proof_of_control field.
Publish a DNS TXT record on the domain with the exact content of proof_of_control.

RSA Key¶

Generate a 1024-bit RSA key pair:

openssl genrsa -out duo-private.pem 1024
openssl rsa -in duo-private.pem -pubout -out duo-public.pem

Publish a DNS TXT record: DUO-DOMAIN-VERIFICATION=rsa:<content of duo-public.pem>
Set proof_of_control to DUO-DOMAIN-VERIFICATION=rsa:<content of duo-private.pem> on POST or PUT.

The public key can be published on a parent domain (e.g. example.com covers all subdomains).

DNS Records¶

Sending domains: - Publish a DKIM TXT record: <dkim_selector>._domainkey.<domain> with value v=DKIM1; k=rsa; s=email; p=<dkim_public_key> - If you have an SPF record, prepend include:_spf.duo.pt as the first mechanism.

Bounce domains: - Publish a CNAME record for the domain pointing to go.duo.pt.

Warning

Bounce domains are fully delegated to DUO and cannot host other services.

Activation¶

Domains activate automatically when DNS records are present. You can force a DNS check via PUT by setting is_sending and/or is_bouncing to true.

GET `/domain/<domain>`¶

Payload: No payload.

Returns: The domain.

POST `/domain`¶

Parameter	Type	Description
`name`	string	Domain name
`proof_of_control`	string	Optional. Used only for RSA proof of control.
`is_sending`	boolean	Enable as sending domain (requires DNS validation)
`is_bouncing`	boolean	Enable as bounce domain (requires DNS validation)

Returns: The new domain.

PUT `/domain/<domain>`¶

Same payload as POST.

Returns: The edited domain.

DELETE `/domain/<domain>`¶

Payload: No payload.

Returns: The deleted domain.