openemail.appHost
Cada método de este espacio de nombres: su firma, sus parámetros, lo que devuelve y un ejemplo.
Métodos
The web app address of the workspace: a subdomain on any domain it controls, where its people open OpenEmail under its brand, with its DNS records and status. Read it, set or replace it, check it now and remove it.
appHost.get()
Read the web app address of the workspace, its status and its DNS records
get(options?: RequestScope): Promise<AppHostResource>Returns the web app address of the workspace with everything the Branded app tab shows: the address, such as mailbox.example.com, the verified domain it sits under, its status, whether people can sign in there right now, the DNS records to publish and when it was last checked. A workspace has at most one.
The address can be on one of the verified domains of the workspace, where it needs only the CNAME record in record, or on any other domain the workspace controls, where it also needs the TXT record in ownershipRecord that proves the domain is yours. domain and domainId are null for an address on another domain.
With no address set, status is none, host, record and the other fields about the address are null, domains lists the verified domains of the workspace and suggested is the address the app would offer, mailbox. in front of the first of them.
Reading it checks the address again when its last check is more than 15 seconds old, so polling get is one way to wait for it to go live: active turns true on the read whose check finds it live. verify checks straight away.
Only the members of the workspace, the people who sign in with one of its addresses and anyone with a pending invitation can sign in at the address, and they see the workspace brand there. On the free plan the address is kept but paused: paused is true, active is false and nobody can sign in there until the workspace is on a paid plan again.
Parámetros
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Devuelve
AppHostResource with object: 'app_host': id, host, domainId, domain, status, active, paused, target, record as { type: 'CNAME', name, value }, ownershipRecord as { type: 'TXT', name, value } or null, ownershipVerified, error, checkedAt and verifiedAt about the address, plus available, paidPlan, domains and suggested about the workspace.
Ejemplo
const appHost = await openemail.appHost.get() if (appHost.host === null) console.log('none set, try', appHost.suggested)else console.log(appHost.host, appHost.status, appHost.active, appHost.record?.value)Notas
statusisnonewith no address,pendingwhile its DNS records do not answer yet or its certificate is not issued,activeonce the address answers over HTTPS, andfailedwhen setting it up failed, with the reason inerror. Set the address again to start over.activeis true exactly whenstatusisactiveand the workspace is on a paid plan, so branch onactiveto know whether people can sign in there.A key limited to particular addresses or domains can read it, but cannot set or remove it.
También disponible en
appHost.set()
Set or replace the web app address of the workspace
set(body: AppHostSet, options?: RequestScope): Promise<AppHostResource>Sets the web app address of the workspace, replacing any it had, and returns it in the same shape as get. host is a subdomain such as mailbox.example.com, on a verified domain of the workspace or on any other domain you control, and the workspace has to be on a paid plan. Setting the address it already has changes nothing and checks it again.
On a verified domain of the workspace the address is set up during the call. On any other domain it is set up once the TXT record in ownershipRecord answers, which proves the domain is yours. Either way it stays pending until its records answer and its certificate is issued, usually a few minutes after they are published. Publish record, and ownershipRecord when it is not null, at your DNS provider exactly as given, then call verify or poll get until active is true. The call writes no DNS record itself.
An address on another domain replaces the old one once it is set up, and an address on the same domain replaces it straight away. Everyone signed in at a replaced address is signed out.
Only the members of the workspace, the people who sign in with one of its addresses and anyone with a pending invitation can sign in at the address, under the workspace brand. Anyone else gets the usual wrong email or password answer, and an invited person can create their account there.
Parámetros
body.hoststringObligatorioA subdomain such as
mailbox.example.com, on a verified domain of the workspace or on any other domain you control, at most 253 characters. It is trimmed and lower cased, and a leadinghttps://orhttp://, any path and any trailing dots are stripped. A bare domain cannot be used.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Devuelve
AppHostResource as the call left it, usually with status pending, the record to publish, and the ownershipRecord too when the address is not on a verified domain of the workspace.
Ejemplo
const appHost = await openemail.appHost.set({ host: 'mailbox.example.com' }) console.log(appHost.status, appHost.record?.type, appHost.record?.name, appHost.record?.value)Notas
A workspace on the free plan is refused with 403
plan_required.An address that is not a hostname, a bare domain, or one on a domain OpenEmail runs is refused with 422
invalid_app_host. One that another workspace already uses, or that a mail domain, a tracking host or a files host already has, gets 409app_host_in_use. When another workspace set the address but never proved it, that message gives the TXT record that frees it for you. Each nameshostinparam.The address applies to the whole workspace, so a key or app limited to particular addresses or domains is refused with 422
capability_unsupportedondomainAllowlist. Use a key with no address or domain restriction.Replacing an address that is already set signs everyone out there, so an OAuth access token needs a verification code for it, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.isStepUpRequiredon the error says so. Setting the first address, or the one already set, needs no code, and an API key is never asked for one.When the address cannot be set up just now, the call is refused with 503
app_host_unavailable. Try again in a minute.Retried automatically on network failure and retryable statuses, since setting the same address again changes nothing and only checks it again.
También disponible en
appHost.verify()
Check the web app address now
verify(options?: RequestScope): Promise<AppHostResource>Checks the web app address straight away, whether its DNS records answer and its certificate is issued, and returns it in the same shape as get.
When the last check ran less than 10 seconds ago, nothing new is checked and the address comes back as it stands, so calling it faster than that gains nothing. With no address set, nothing is checked and status comes back as none. A record published a moment ago can take a few minutes to show up in public DNS.
Parámetros
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Devuelve
AppHostResource as the check left it.
Ejemplo
let appHost = await openemail.appHost.verify() while (appHost.status === 'pending') { console.log(appHost.error ?? 'waiting for', appHost.record?.name, appHost.record?.value) await new Promise((resolve) => setTimeout(resolve, 30_000)) appHost = await openemail.appHost.verify()} console.log(appHost.status, appHost.active)Notas
Reading with
getalso checks the address again when its last check is more than 15 seconds old, so either call works for polling.verifyneedsdomains:writeandgetneeds onlydomains:read.Retried automatically on network failure and retryable statuses, since a repeated check changes nothing but the time of the check.
También disponible en
appHost.delete()
Remove the web app address of the workspace
delete(options?: RequestScope): Promise<DeletedAppHostResource>Removes the web app address of the workspace. Everyone signed in there is signed out, the address stops opening the workspace, and emails link to openemail.uk again. People keep working at openemail.uk with the same accounts.
Its DNS records are left at your DNS provider, so remove them there when you no longer need them. Removing the address when none is set changes nothing and answers deleted: false. Setting the same address again later sets it up from scratch.
Parámetros
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Devuelve
DeletedAppHostResource, { object: 'app_host', id, host, deleted }, where deleted is false and id and host are null when no address was set.
Ejemplo
const removed = await openemail.appHost.delete() if (removed.deleted) console.log('remove the DNS records for', removed.host, 'at your DNS provider')Notas
The address applies to the whole workspace, so a key or app limited to particular addresses or domains is refused with 422
capability_unsupportedondomainAllowlist.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.isStepUpRequiredon the error says so. An API key is never asked for a code.When the address cannot be removed just now, the call is refused with 503
app_host_unavailableand the address is still set. Try again in a minute.Retried automatically on network failure and retryable statuses, since a second attempt after one that went through finds nothing to remove and answers
deleted: false.