--- title: "openemail domains" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/domains" area: "CLI" category: "Reference" --- # openemail domains Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail domains list` List the workspace's domains and their receiving state ```bash openemail domains list [flags] ``` Returns one page of the domains added to the workspace, alphabetically by domain. `receiving` reports the inbound checks: `verified` is true once `verifiedAt` is set, `catchAll` is the domain's catch all setting, `lastCheckedAt` is the most recent check and `error` is the last verification failure. `receiving` and `sending` are independent. A verified domain can receive mail, and that says nothing about whether outbound mail from it is signed. `sending.status` is the signing state as the last check saw it, one of `verified`, `pending`, `failed`, `no_identity` or `unknown`, `sending.canSend` says whether a send from the domain would be accepted right now, `sending.checkedAt` dates that verdict, and `sending.error` carries the last failure. A negative verdict older than a day is treated as unknown rather than as a refusal, so `canSend` can be true while `status` is `pending`. `tracking` reports the domain's custom tracking domain, set with `update`, and only a `tracking.status` of `active` means tracked links and the open pixel in new mail from the domain use its `host` instead of the default OpenEmail host. `storage` reports the domain's custom files domain the same way, and only a `storage.status` of `active` means the download links for files sent from the domain use its `host`. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `domains:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail domains list ``` Walk every page and stop after 100 items ```bash openemail domains list --all --max 100 ``` One JSON object per line when piped ```bash openemail domains list --all > domains.ndjson ``` Also available in: API [`GET /domains`](https://openemail.uk/docs/api/reference/domains#get-domains); SDK [`domains.list()`](https://openemail.uk/docs/sdk/reference/domains#list). ### `openemail domains get` Read one domain with its addresses, DNS records and DMARC reading ```bash openemail domains get [flags] ``` Returns the same `receiving` and `sending` blocks as `list`, plus `addresses`: every address on the domain as a full lower cased address with its `enabled` flag. Disabled addresses are listed too. `listAddresses` returns the same addresses with their ids and labels. It also carries the `tracking` and `storage` blocks described on `list`, whose `record` is the CNAME record to add at your DNS provider for the tracking domain and for the files domain. `records` is every DNS record the domain uses, each with `type`, `name`, `value`, `priority` on an MX record, a `purpose` written to be shown to a person, and `status`: `found` when the last check saw it in public DNS, `missing` when it did not, and null when it has not been checked yet. Publish each one exactly as given, since the values are specific to this domain. `dmarc` is the domain's DMARC record as public DNS has it, with its `stage`, any `issues`, and whether a policy stricter than `p=none` is safe yet. It is null until the domain is verified. Reading an unverified domain checks its DNS again when the last check is more than 20 seconds old, so polling `get` is one way to wait for verification. `verify` checks straight away. The id must belong to the calling workspace. Another workspace's domain id is a 404, the same as an id that does not exist, and the domain name is not accepted in its place. - Scopes: `domains:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Domain id from `list`, a UUID. **Examples** ```bash openemail domains get b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Print the raw JSON ```bash openemail domains get b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --json ``` Also available in: API [`GET /domains/{id}`](https://openemail.uk/docs/api/reference/domains#get-domains-id); SDK [`domains.get()`](https://openemail.uk/docs/sdk/reference/domains#get). ### `openemail domains create` Add a domain to the workspace ```bash openemail domains create --domain [flags] openemail domains create --data [flags] ``` Adds a domain and returns it with every DNS record to publish, in the same shape as `get`. The first DNS check runs during the call, so `records[].status` already says what public DNS answers with. The domain receives mail once public DNS answers with its MX records and its `_openemail-challenge` TXT record, and it can send once its signing records are in place. Publish every entry in `records` exactly as given, since the values are specific to this domain, then call `verify` or poll `get` until `receiving.verified` is true. A new domain starts with its catch-all on and no addresses. Create addresses with `createAddress`, or turn the catch-all off with `update`. - Scopes: `domains:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--domain `: A bare domain such as `example.com`. It is trimmed, lower cased and converted to its ASCII form, so an internationalised name is stored as punycode. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains create --domain example.com ``` Read the whole body from a JSON file ```bash openemail domains create --data @domain.json ``` Also available in: API [`POST /domains`](https://openemail.uk/docs/api/reference/domains#post-domains); SDK [`domains.create()`](https://openemail.uk/docs/sdk/reference/domains#create). ### `openemail domains verify` Check a domain's DNS now ```bash openemail domains verify [flags] ``` Checks the DNS of the domain straight away and returns it in the same shape as `get`. On an unverified domain it looks for the records that verify it, and `receiving.verified` comes back true when they are found. On a verified domain it checks the signing and return path records again and asks whether mail from the domain can be sent, so `sending` is fresh. When the last check ran less than 10 seconds ago, nothing new is checked and the domain comes back as it stands, so calling it faster than that gains nothing. A record published a moment ago can take a few minutes to show up in public DNS. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Examples** ```bash openemail domains verify b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Print the raw JSON ```bash openemail domains verify b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --json ``` Also available in: API [`POST /domains/{id}/verify`](https://openemail.uk/docs/api/reference/domains#post-domains-id-verify); SDK [`domains.verify()`](https://openemail.uk/docs/sdk/reference/domains#verify). ### `openemail domains update` Turn the catch-all on or off, set or remove the tracking and files domains, and set the DMARC policy ```bash openemail domains update [flags] ``` `--catch-all` true accepts mail to any address on the domain that nobody created, and the address shows up in `listAddresses` from its first message on. False refuses mail to every address that was not created by hand, including the ones the catch-all picked up before. It applies to the whole domain, so only a key that holds the whole domain may change it. `--tracking-host` and `--storage-host` set the two custom names a domain can carry once it is verified or its `_openemail-challenge` TXT record is published, each of them a subdomain of it. `--tracking-host`, such as `links.example.com`, is the name tracked links and the open pixel use. `--storage-host`, such as `files.example.com`, is the name the download links for files sent from the domain use. All four fields are optional and independent: a field left out is left alone, and for either host `null` removes that name and a string sets it. A patch carrying none of them changes nothing and answers with the domain as it stands. Each value is trimmed and lower cased, and a leading `https://` or `http://`, any path, query or fragment and any trailing dots are stripped. A new host is validated, saved and checked in the same call, so the response already carries the result of that first check. `--tracking-host` reports into the `tracking` block and `--storage-host` into `storage`, and the two blocks carry the same fields. The check asks the host over HTTPS for an answer signed by OpenEmail, on `/t/v/` for a tracking domain and `/f/v/` for a files domain, so the host needs a CNAME record named `record.name` with the value `record.value`, with any proxying turned off. That value, also reported as `target`, is an address prepared for this host alone. When it could not be prepared during the call, `record` is null, `target` is an empty string and `error` says so, and it is finished within a few minutes without another call. Until a check passes, `status` is `pending` and new mail keeps using the default OpenEmail host. Once one passes, `status` is `active` and new mail from the domain uses the host. Sending a host the domain already has runs the check again, unless the last check was less than 30 seconds ago, in which case the stored state comes back unchanged. A different host replaces the current one at once, so new mail uses the default host until the new one passes a check. `null` removes that name, and its block then reports `status` as `none` with `host` and `record` null. `--dmarc-policy` is what the domain's DMARC record tells receivers to do with mail that fails its checks: `none` only monitors, `quarantine` sends it to spam and `reject` refuses it. Inboxes show the domain logo only at `quarantine` or `reject`, and where OpenEmail writes the DNS for the domain the record is updated during the call, keeping its other tags such as `rua`, while elsewhere you publish the DMARC record `records` lists. - Scopes: `domains:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Domain id from `list`, a UUID. **Flags** - `--catch-all`: True accepts mail to any address on the domain that nobody created, false refuses it. Leaving the field out leaves the catch-all alone. - `--tracking-host `: A subdomain of the domain of at most 512 characters, such as `links.example.com`. Null removes the tracking domain, and leaving the field out leaves it alone. - `--storage-host `: A subdomain of the domain of at most 512 characters, such as `files.example.com`. Null removes the files domain, and leaving the field out leaves it alone. - `--dmarc-policy `: `none`, `quarantine` or `reject`. A policy stricter than `none` needs mail from the domain to be signed first. Leaving the field out leaves the policy alone. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail domains update b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --tracking-host links.example.com --storage-host files.example.com ``` Print the raw JSON ```bash openemail domains update b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --tracking-host links.example.com --storage-host files.example.com --json ``` Also available in: API [`PATCH /domains/{id}`](https://openemail.uk/docs/api/reference/domains#patch-domains-id); SDK [`domains.update()`](https://openemail.uk/docs/sdk/reference/domains#update). ### `openemail domains delete` Remove a domain from the workspace ```bash openemail domains delete [flags] ``` Removes the domain. Mail to it stops being accepted and nothing can be sent from it. Every address on it goes with it, their password sign-ins are revoked, its signing key is released, its tracking and files domains are retired, and the `domain.deleted` webhook fires. Mail already received stays in the mailbox. Where OpenEmail wrote the DNS for this domain itself, it takes those records back, and any it could not take back are listed in `leftBehind` for you to remove at your DNS provider. Records you published yourself are never touched, so remove them too once the domain is gone. There is no undo. Adding the domain again starts it from scratch. - Scopes: `domains:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Examples** ```bash openemail domains delete b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Skip the confirmation, for scripts ```bash openemail domains delete b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --yes ``` Also available in: API [`DELETE /domains/{id}`](https://openemail.uk/docs/api/reference/domains#delete-domains-id); SDK [`domains.delete()`](https://openemail.uk/docs/sdk/reference/domains#delete). ### `openemail domains get-logo` Read the brand logo of a domain and what public DNS publishes for it ```bash openemail domains get-logo [flags] ``` Returns the logo inboxes show next to mail from the domain through BIMI, with its mark certificate and DMARC policy, and asks public DNS what `default._bimi.` holds right now: `published.ours` turns true once the record pointing at the logo is live. For a subdomain, `parentDmarc` reports the DMARC record of the domain it belongs to, because inboxes show the logo only when its `p=` and `sp=` both quarantine or reject at 100 percent. - Scopes: `domains:read`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Examples** ```bash openemail domains get-logo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Print the raw JSON ```bash openemail domains get-logo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --json ``` Also available in: API [`GET /domains/{id}/logo`](https://openemail.uk/docs/api/reference/domains#get-domains-id-logo); SDK [`domains.getLogo()`](https://openemail.uk/docs/sdk/reference/domains#getLogo). ### `openemail domains set-logo` Upload the brand logo inboxes show for a domain ```bash openemail domains set-logo --svg [flags] openemail domains set-logo --data [flags] ``` Converts the SVG to the SVG Tiny PS format inboxes require, replaces any logo the domain had, and publishes the BIMI record where OpenEmail writes the DNS for the domain. Inboxes show the logo once `dmarcPolicy` is `quarantine` or `reject`, which `update` sets, and Gmail also needs a mark certificate from `setLogoCertificate`. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--svg `: The logo as SVG markup, up to 1 MB. A file that is SVG Tiny PS already is kept byte for byte, so it stays the same as the copy inside a mark certificate. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains set-logo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --svg example ``` Read the whole body from a JSON file ```bash openemail domains set-logo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --data @domain.json ``` Also available in: API [`PUT /domains/{id}/logo`](https://openemail.uk/docs/api/reference/domains#put-domains-id-logo); SDK [`domains.setLogo()`](https://openemail.uk/docs/sdk/reference/domains#setLogo). ### `openemail domains remove-logo` Remove the brand logo of a domain ```bash openemail domains remove-logo [flags] ``` Removes the logo and deletes the stored file, and takes the BIMI record down where OpenEmail writes the DNS for the domain. Elsewhere remove the record yourself. Any mark certificate stays, ready for the next logo. - Scopes: `domains:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Examples** ```bash openemail domains remove-logo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Skip the confirmation, for scripts ```bash openemail domains remove-logo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --yes ``` Also available in: API [`DELETE /domains/{id}/logo`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-logo); SDK [`domains.removeLogo()`](https://openemail.uk/docs/sdk/reference/domains#removeLogo). ### `openemail domains set-logo-certificate` Upload the mark certificate for a domain logo ```bash openemail domains set-logo-certificate --certificate [flags] openemail domains set-logo-certificate --data [flags] ``` Stores the Verified Mark Certificate (VMC) or Common Mark Certificate (CMC) a certificate authority issued for the domain, replacing any there was, and points the BIMI record at it. Gmail shows the logo only with one and Apple Mail only with a VMC, and when the logo inside the certificate differs from the published one, it becomes the published one and `logoFromCertificate` is true. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--certificate `: The file the certificate authority sent, up to 128 KB: PEM text as it came, which can hold the whole chain, or a DER or PKCS #7 file encoded as base64. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains set-logo-certificate b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --certificate example ``` Read the whole body from a JSON file ```bash openemail domains set-logo-certificate b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --data @domain.json ``` Also available in: API [`PUT /domains/{id}/logo/certificate`](https://openemail.uk/docs/api/reference/domains#put-domains-id-logo-certificate); SDK [`domains.setLogoCertificate()`](https://openemail.uk/docs/sdk/reference/domains#setLogoCertificate). ### `openemail domains remove-logo-certificate` Remove the mark certificate of a domain logo ```bash openemail domains remove-logo-certificate [flags] ``` Removes the mark certificate and deletes the stored file, while the logo stays. The BIMI record no longer points at a certificate, so Gmail and Apple Mail stop showing the logo. - Scopes: `domains:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Examples** ```bash openemail domains remove-logo-certificate b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Skip the confirmation, for scripts ```bash openemail domains remove-logo-certificate b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --yes ``` Also available in: API [`DELETE /domains/{id}/logo/certificate`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-logo-certificate); SDK [`domains.removeLogoCertificate()`](https://openemail.uk/docs/sdk/reference/domains#removeLogoCertificate). ### `openemail domains list-addresses` List one page of the addresses on a domain ```bash openemail domains list-addresses [flags] ``` Returns one page of the addresses on the domain, alphabetically by address, with each one's `id`, `label`, `enabled` and `lastReceivedAt`. That covers the addresses created by hand or through the API and the ones the catch-all picked up when mail first arrived for them. Disabled addresses are listed. Removed addresses and the catch-all itself are not: the catch-all is `receiving.catchAll` on the domain. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `domains:read`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail domains list-addresses b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` With optional flags ```bash openemail domains list-addresses b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --limit 100 ``` Walk every page and stop after 100 items ```bash openemail domains list-addresses b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --all --max 100 ``` One JSON object per line when piped ```bash openemail domains list-addresses b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --all > domains.ndjson ``` Also available in: API [`GET /domains/{id}/addresses`](https://openemail.uk/docs/api/reference/domains#get-domains-id-addresses); SDK [`domains.listAddresses()`](https://openemail.uk/docs/sdk/reference/domains#listAddresses). ### `openemail domains create-address` Create an address on a domain ```bash openemail domains create-address --local-part [flags] openemail domains create-address --data [flags] ``` Creates an address on the domain, enabled, and returns it. The domain does not have to be verified yet, but the address receives nothing until it is. When the domain has its catch-all on, the new address starts with the per-address settings of the catch-all, such as its signature and tracking, apart from the privacy settings. They are copied once, not kept in step. Creating an address that already exists, or one that was removed, is not an error: it comes back enabled, with the `label` you sent or none, and keeps its id. An address the catch-all picked up becomes one created by hand, so it keeps receiving when the catch-all is turned off. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--local-part `: The part in front of the @, 1 to 64 characters once trimmed, lower cased. Letters, digits, the backtick and ! # $ % & ' * + / = ? ^ _ { | } ~ - are allowed, and so are dots between them. `*` on its own is how the catch-all is written and is refused. Required, here or in `--data`. - `--label `: A name for the address shown in the app, trimmed, up to 120 characters. Leave it out, or send null, for none. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail domains create-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --local-part support ``` With optional flags ```bash openemail domains create-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --local-part support --label Support ``` Read the whole body from a JSON file ```bash openemail domains create-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --data @domain.json ``` Also available in: API [`POST /domains/{id}/addresses`](https://openemail.uk/docs/api/reference/domains#post-domains-id-addresses); SDK [`domains.createAddress()`](https://openemail.uk/docs/sdk/reference/domains#createAddress). ### `openemail domains get-address` Read one address on a domain ```bash openemail domains get-address [flags] ``` Returns one address on the domain with its `label`, `enabled`, `lastReceivedAt` and timestamps. - Scopes: `domains:read`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains get-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Print the raw JSON ```bash openemail domains get-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --json ``` Also available in: API [`GET /domains/{id}/addresses/{addressId}`](https://openemail.uk/docs/api/reference/domains#get-domains-id-addresses-addressid); SDK [`domains.getAddress()`](https://openemail.uk/docs/sdk/reference/domains#getAddress). ### `openemail domains update-address` Rename an address, turn it off and on, or choose where its mail goes ```bash openemail domains update-address [flags] ``` Changes the fields you send and leaves the rest alone. `label` renames the address, and null removes the name. `enabled` false stops the address taking mail: mail to it is refused while the sending server is still connected, so the sender gets a bounce, and nothing can be sent from it. It keeps its mail, its settings and the people who can reach it, so `enabled` true picks up where it left off. That is the difference from `deleteAddress`. `destination` chooses where the mail of the address goes: `mailbox` keeps a copy here, as an address does by default, and `forward` only sends it on to the destinations from `addAddressForwards`, keeping nothing here. `forward` needs at least one destination that is switched on. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Flags** - `--label `: A new name, trimmed, up to 120 characters. Null removes it. - `--enabled`: False stops the address taking mail, true takes mail again. - `--destination `: `mailbox` keeps a copy of the mail here, `forward` only forwards it. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail domains update-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --no-enabled ``` Print the raw JSON ```bash openemail domains update-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --no-enabled --json ``` Also available in: API [`PATCH /domains/{id}/addresses/{addressId}`](https://openemail.uk/docs/api/reference/domains#patch-domains-id-addresses-addressid); SDK [`domains.updateAddress()`](https://openemail.uk/docs/sdk/reference/domains#updateAddress). ### `openemail domains set-address-photo` Upload the photo shown for an address ```bash openemail domains set-address-photo [flags] ``` Sends the image bytes as the request body, replacing any photo the address had: PNG, JPEG, WebP or GIF up to 5 MB, cropped to a 512 pixel square, stored as JPEG or PNG and shown for the address in OpenEmail in place of the domain logo. The type is read from `--content-type`, or from a `Blob`'s own type when that is left out, and without either the server refuses the bytes with 422 `invalid_image`. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. - `` (required): The image: a `Blob`, `ArrayBuffer` or `Uint8Array`. **Flags** - `--content-type `: `image/png`, `image/jpeg`, `image/webp` or `image/gif`. Required unless `data` is a `Blob` with a type. **Examples** The required values only ```bash openemail domains set-address-photo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ./photo.jpg ``` With optional flags ```bash openemail domains set-address-photo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ./photo.jpg --content-type image/jpeg ``` Also available in: API [`PUT /domains/{id}/addresses/{addressId}/photo`](https://openemail.uk/docs/api/reference/domains#put-domains-id-addresses-addressid-photo); SDK [`domains.setAddressPhoto()`](https://openemail.uk/docs/sdk/reference/domains#setAddressPhoto). ### `openemail domains remove-address-photo` Remove the photo of an address ```bash openemail domains remove-address-photo [flags] ``` Removes the photo of the address and deletes the stored image, so the domain logo is shown for it again. - Scopes: `domains:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains remove-address-photo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Skip the confirmation, for scripts ```bash openemail domains remove-address-photo b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --yes ``` Also available in: API [`DELETE /domains/{id}/addresses/{addressId}/photo`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-addresses-addressid-photo); SDK [`domains.removeAddressPhoto()`](https://openemail.uk/docs/sdk/reference/domains#removeAddressPhoto). ### `openemail domains delete-address` Remove an address from a domain ```bash openemail domains delete-address [flags] ``` Removes the address. Mail to it is refused from then on, even when the catch-all on the domain is on. Its forwarding stops, its settings are deleted, the people who were given access to it lose that access, and its password sign-in is revoked. Mail it already received stays in the mailbox. Creating the same address again with `createAddress` brings it back with the same id, enabled, but without its old settings or access. - Scopes: `domains:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains delete-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Skip the confirmation, for scripts ```bash openemail domains delete-address b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --yes ``` Also available in: API [`DELETE /domains/{id}/addresses/{addressId}`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-addresses-addressid); SDK [`domains.deleteAddress()`](https://openemail.uk/docs/sdk/reference/domains#deleteAddress). ### `openemail domains list-address-forwards` List where the mail of an address is forwarded ```bash openemail domains list-address-forwards [flags] ``` Returns every place the mail of the address is forwarded to, oldest first, as the Forwarding section of the address in the app lists them. Each destination says whether it is switched on (`enabled`) and where it stands (`status`): only a `live` destination, one that confirmed by email that it wants this mail, receives anything. `destination` on the list says whether the address also keeps a copy of its mail here (`mailbox`) or only forwards it (`forward`), and `max` is how many destinations one address may have. - Scopes: `domains:read`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains list-address-forwards b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Print the raw JSON ```bash openemail domains list-address-forwards b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --json ``` Also available in: API [`GET /domains/{id}/addresses/{addressId}/forwards`](https://openemail.uk/docs/api/reference/domains#get-domains-id-addresses-addressid-forwards); SDK [`domains.listAddressForwards()`](https://openemail.uk/docs/sdk/reference/domains#listAddressForwards). ### `openemail domains add-address-forwards` Forward the mail of an address to more places ```bash openemail domains add-address-forwards --emails [flags] openemail domains add-address-forwards --data [flags] ``` Adds places the mail of the address goes to, as adding a destination in the app does. Each new destination is sent an email asking it to confirm, and receives nothing until it does, so it comes back `pending` and turns `live` once its owner confirms. An address hosted here, one already on the list, one that would make a loop, one past the limit of 10 and one that refused mail from this workspace before are not added. Each is named in `skipped` with the reason, and the rest are still added. The address keeps a copy of its mail here as before. To stop keeping one, set `destination` to `forward` with `updateAddress` once a destination is switched on. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Flags** - `--emails ` (repeatable): The addresses to forward to, 1 to 10 of them. Each is trimmed and lowercased. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains add-address-forwards b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --emails ops@partner.example ``` Read the whole body from a JSON file ```bash openemail domains add-address-forwards b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --data @domain.json ``` Also available in: API [`POST /domains/{id}/addresses/{addressId}/forwards`](https://openemail.uk/docs/api/reference/domains#post-domains-id-addresses-addressid-forwards); SDK [`domains.addAddressForwards()`](https://openemail.uk/docs/sdk/reference/domains#addAddressForwards). ### `openemail domains update-address-forward` Pause a forwarding destination or switch it back on ```bash openemail domains update-address-forward --enabled [flags] openemail domains update-address-forward --data [flags] ``` `enabled` false pauses the destination: nothing is forwarded to it until it is switched on again. It keeps its confirmation, so switching it back on needs no new one, and switching it on clears the failures recorded against it. When the last destination that is on is paused, the address goes back to keeping its mail here. `destination` in the result says where the mail of the address goes now. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. - `` (required): A destination id from `listAddressForwards` or `addAddressForwards`. It has to be a destination of the address named by `addressId`. **Flags** - `--enabled`: False pauses the destination, true switches it back on. Required, here or in `--data`. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains update-address-forward b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b --no-enabled ``` Read the whole body from a JSON file ```bash openemail domains update-address-forward b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b --data @domain.json ``` Also available in: API [`PATCH /domains/{id}/addresses/{addressId}/forwards/{forwardId}`](https://openemail.uk/docs/api/reference/domains#patch-domains-id-addresses-addressid-forwards-forwardid); SDK [`domains.updateAddressForward()`](https://openemail.uk/docs/sdk/reference/domains#updateAddressForward). ### `openemail domains delete-address-forward` Stop forwarding to a destination ```bash openemail domains delete-address-forward [flags] ``` Removes the destination, so nothing more is forwarded to it. When it was the last destination that was on, the address goes back to keeping its mail here, and `destination` in the result says where the mail of the address goes now. To stop forwarding for a while instead, pause the destination with `updateAddressForward`, which keeps its confirmation. - Scopes: `domains:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. - `` (required): A destination id from `listAddressForwards` or `addAddressForwards`. It has to be a destination of the address named by `addressId`. **Examples** ```bash openemail domains delete-address-forward b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b ``` Skip the confirmation, for scripts ```bash openemail domains delete-address-forward b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b --yes ``` Also available in: API [`DELETE /domains/{id}/addresses/{addressId}/forwards/{forwardId}`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-addresses-addressid-forwards-forwardid); SDK [`domains.deleteAddressForward()`](https://openemail.uk/docs/sdk/reference/domains#deleteAddressForward). ### `openemail domains resend-address-forward-consent` Ask a forwarding destination to confirm again ```bash openemail domains resend-address-forward-consent [flags] ``` Sends the confirmation email to the destination once more, for when the first one was lost or ignored. `status` says what became of the request: `sent`, `already-confirmed` when the destination has confirmed and needs nothing, `too-soon` when the last email went out moments ago, `revoked` when the destination refused mail from this workspace, and `send-failed` when the email could not be sent. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. - `` (required): A destination id from `listAddressForwards` or `addAddressForwards`. It has to be a destination of the address named by `addressId`. **Examples** ```bash openemail domains resend-address-forward-consent b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b ``` Print the raw JSON ```bash openemail domains resend-address-forward-consent b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b --json ``` Also available in: API [`POST /domains/{id}/addresses/{addressId}/forwards/{forwardId}/resend`](https://openemail.uk/docs/api/reference/domains#post-domains-id-addresses-addressid-forwards-forwardid-resend); SDK [`domains.resendAddressForwardConsent()`](https://openemail.uk/docs/sdk/reference/domains#resendAddressForwardConsent). ### `openemail domains list-address-members` List who can reach an address ```bash openemail domains list-address-members [flags] ``` Returns everybody who can read the mail of the address and how each one reaches it, in `via`: `owner` for the owner of the workspace, `every-address` for a role that reaches every address, `whole-domain` for a grant of the whole domain named in `viaDomain`, and `direct` for a grant of the address itself. Each person appears once. `access` is `member` for somebody who reads and sends from the address and `viewer` for somebody who only reads it. `removable` is true for a grant of the address itself, which `members.revokeAddress` takes back. The others come from the role or a domain grant, and change there. - Scopes: `members:read`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains list-address-members b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Print the raw JSON ```bash openemail domains list-address-members b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --json ``` Also available in: API [`GET /domains/{id}/addresses/{addressId}/members`](https://openemail.uk/docs/api/reference/domains#get-domains-id-addresses-addressid-members); SDK [`domains.listAddressMembers()`](https://openemail.uk/docs/sdk/reference/domains#listAddressMembers). ### `openemail domains get-address-login` Read the password sign-in of an address ```bash openemail domains get-address-login [flags] ``` Says whether the address has a password of its own, which lets somebody sign in to OpenEmail as that address alone and read and send only its mail. `login` is null when it has none, and otherwise says who set the password and when, and when it was last used to sign in. - Scopes: `members:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains get-address-login b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Print the raw JSON ```bash openemail domains get-address-login b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --json ``` Also available in: API [`GET /domains/{id}/addresses/{addressId}/login`](https://openemail.uk/docs/api/reference/domains#get-domains-id-addresses-addressid-login); SDK [`domains.getAddressLogin()`](https://openemail.uk/docs/sdk/reference/domains#getAddressLogin). ### `openemail domains set-address-login` Give an address a password, or replace it ```bash openemail domains set-address-login --password [flags] openemail domains set-address-login --data [flags] ``` Sets the password somebody uses to sign in to OpenEmail as this address alone. Whoever holds it reads and sends only the mail of the address and reaches nothing else in the workspace. OpenEmail sends the password to nobody, so hand it over yourself. Calling it again replaces the password, signs out everybody who signed in with the old one and removes the forwarding destinations they added. `created` says whether the sign-in is new. - Scopes: `members:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Flags** - `--password `: At least 8 characters, with a lowercase letter, an uppercase letter, a number and a special character. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains set-address-login b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --password example ``` Read the whole body from a JSON file ```bash openemail domains set-address-login b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --data @domain.json ``` Also available in: API [`PUT /domains/{id}/addresses/{addressId}/login`](https://openemail.uk/docs/api/reference/domains#put-domains-id-addresses-addressid-login); SDK [`domains.setAddressLogin()`](https://openemail.uk/docs/sdk/reference/domains#setAddressLogin). ### `openemail domains delete-address-login` Remove the password sign-in of an address ```bash openemail domains delete-address-login [flags] ``` Takes the password away and signs out everybody who signed in with it. The address, its mail and the people who reach it otherwise stay as they are, and the forwarding destinations added by whoever signed in as the address are removed with it. - Scopes: `members:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. - `` (required): Address id from `listAddresses` or `createAddress`, a UUID. It has to be an address on the domain named by `id`. **Examples** ```bash openemail domains delete-address-login b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 ``` Skip the confirmation, for scripts ```bash openemail domains delete-address-login b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f 7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70 --yes ``` Also available in: API [`DELETE /domains/{id}/addresses/{addressId}/login`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-addresses-addressid-login); SDK [`domains.deleteAddressLogin()`](https://openemail.uk/docs/sdk/reference/domains#deleteAddressLogin). ### `openemail domains get-dns` Read how the DNS of a domain is set up ```bash openemail domains get-dns [flags] ``` Returns whether OpenEmail writes the records of the domain itself (`managing`), through which connection and zone, where each kind of record stands in `steps`, and the records left behind to delete by hand. `zone` says which connected zone answers for the domain: one is `resolved`, several are `ambiguous` and need `setDnsZone`, `none` holds it, with the reason, or the connections could not be asked (`unusable`). The answer is kept for a few minutes, and `refresh` asks the providers again. - Scopes: `domains:read`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--refresh`: True asks the providers again which zone answers for the domain. **Examples** The required values only ```bash openemail domains get-dns b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` With optional flags ```bash openemail domains get-dns b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --refresh ``` Print the raw JSON ```bash openemail domains get-dns b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --json ``` Also available in: API [`GET /domains/{id}/dns`](https://openemail.uk/docs/api/reference/domains#get-domains-id-dns); SDK [`domains.getDns()`](https://openemail.uk/docs/sdk/reference/domains#getDns). ### `openemail domains set-dns-zone` Choose the zone a domain is set up through ```bash openemail domains set-dns-zone --connection-id --zone-id [flags] openemail domains set-dns-zone --data [flags] ``` Attaches the domain to a zone of a connection, when several connected zones could answer for it. The zone has to cover the domain, be active at the provider and take a test record. Nothing is written yet: call `syncDns` to write the records. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--connection-id `: The connection that holds the zone, from `dnsConnections.list`. Required, here or in `--data`. - `--zone-id `: The zone, as `zone.candidates` of `getDns` lists it. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains set-dns-zone b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --connection-id example --zone-id example ``` Read the whole body from a JSON file ```bash openemail domains set-dns-zone b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --data @domain.json ``` Also available in: API [`PUT /domains/{id}/dns`](https://openemail.uk/docs/api/reference/domains#put-domains-id-dns); SDK [`domains.setDnsZone()`](https://openemail.uk/docs/sdk/reference/domains#setDnsZone). ### `openemail domains sync-dns` Write the DNS records of a domain ```bash openemail domains sync-dns [flags] ``` Writes or repairs every record the domain needs through the connected zone that answers for it, as Sync does in the app. When exactly one zone answers it is attached first, and `attached` says so. With `purpose`, only that kind of record is written. A domain that was waiting for its records is verified once they are in place. When no single zone answers, nothing is written: `outcome` is `refused`, `message` says why and `zone` shows the zones to choose from with `setDnsZone`. - Scopes: `domains:write`. - Needs a sign-in. **Arguments** - `` (required): Domain id from `list` or `create`, a UUID. **Flags** - `--purpose `: Only this kind of record: `dmarc`, `tracking`, `storage`, `bimi` or `app-host`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail domains sync-dns b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f ``` Print the raw JSON ```bash openemail domains sync-dns b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f --json ``` Also available in: API [`POST /domains/{id}/dns/sync`](https://openemail.uk/docs/api/reference/domains#post-domains-id-dns-sync); SDK [`domains.syncDns()`](https://openemail.uk/docs/sdk/reference/domains#syncDns).