Домены
Каждая операция этой группы: что она принимает, что возвращает и какими ошибками может ответить.
Операции
GET/domains
List domains
receiving and sending are two independent facts. A verified domain can RECEIVE, and that says nothing about outbound: mail from a domain is signed once its signing record is published and confirmed, which is usually a couple of minutes after it answers in DNS. sending.status reports that state as the last check saw it (verified, pending, failed, no_identity or unknown), sending.canSend says whether a send from the domain would be accepted right now, and sending.checkedAt says how old that verdict is. A negative verdict older than a day is treated as unknown rather than as a refusal.
tracking reports the custom tracking domain, if one is set, and whether new mail uses it yet. storage reports the custom files domain the same way, which is the name the download links for files sent from this domain use.
Requires the domains:read scope.
Параметры запроса
limitintegerRows per page, 1 to 100.
Не меньше 1Не больше 100По умолчанию25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Возвращает
A page of domains, alphabetically, without addresses.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
POST/domains
Add a domain
Adds a domain to the workspace and returns it with every DNS record to publish, in the same shape as GET /domains/{id}. 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 the records exactly as records gives them, then poll GET /domains/{id} or call POST /domains/{id}/verify.
A new domain starts with its catch-all on and no addresses. Create addresses with POST /domains/{id}/addresses, or turn the catch-all off with PATCH /domains/{id}.
How many domains you can add is set by the plan of the workspace, counted within that workspace. A domain that is already added anywhere is refused, and so is a domain whose parent or subdomain belongs to somebody else, and a domain that belongs to OpenEmail.
Adding a domain reaches the whole workspace, so a key or app limited to particular addresses or domains cannot add one. Use a key with no address or domain restriction.
Requires the domains:write scope.
Тело запроса
domainstringОбязательноA bare domain such as
example.com. It is trimmed, lowercased and converted to its ASCII form, so an internationalised name is stored as punycode. Anything that is not a hostname of at least two labels is a 422invalid_parameterondomain.
Возвращает
The new domain, its DNS records and what the first check found.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.domain_allowance_reached: the plan of the workspace includes no more domains, and the message says which plan includes more.- 409
domain_already_addedwhen you have already added this domain,domain_claimedwhen somebody else has,related_domain_ownedwhen a parent or subdomain of it belongs to somebody else, andoperator_domainwhen it belongs to OpenEmail. Each namesdomaininparam.- 422
invalid_parameterondomainwhen it is missing or not a hostname,unknown_parameterfor any other field, andcapability_unsupportedondomainAllowlistfor a key or app limited to particular addresses or domains.
Ошибки, которые может вернуть любая операция401404500Каталог ошибок
Также доступно в
GET/domains/{id}
Retrieve a domain
The domain with its addresses, every DNS record it uses with what the last check found, and its DMARC reading. records is what to publish at your DNS provider, and records[].status says which of them public DNS answers with yet.
Reading an unverified domain checks its DNS again when the last check is more than 20 seconds old, so polling this route is how to wait for verification: receiving.verified turns true on the read whose check finds the records. The signing records of a verified domain are checked again when their last check is more than 10 minutes old. POST /domains/{id}/verify checks straight away.
tracking reports the custom tracking domain, if one is set, and whether new mail uses it yet. storage reports the custom files domain the same way.
Requires the domains:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Возвращает
The domain, its addresses, its DNS records and its DMARC reading.
Ошибки
- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.
Ошибки, которые может вернуть любая операция400401403422500Каталог ошибок
Также доступно в
PATCH/domains/{id}
Update a domain
Turns the catch-all on or off, sets or removes the two custom names a domain can carry, and sets its DMARC policy. All four fields are optional and independent: a field left out is left alone. A body with none of them changes nothing and answers 200 with the domain as it stands. The fields are applied in order, catchAll first, then trackingHost, then storageHost, then dmarcPolicy, and a refusal on one does not undo the ones before it: a refused storageHost leaves a catchAll or trackingHost change already made in place. Send them in separate calls when any of them has to stand on its own.
dmarcPolicy is what the DMARC record of the domain 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. A stricter policy than none needs mail from the domain to be signed first, or it would send the domain's own mail to spam. Where OpenEmail writes the DNS for the domain, the record is updated during the call, keeping every other tag it has, such as rua, and a record published by hand is replaced only if it is still the one OpenEmail last read. Otherwise publish the DMARC record records lists.
catchAll true accepts mail to any address on the domain that nobody created and delivers it to the mailbox, and the address is listed 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.
trackingHost is a subdomain such as links.example.com that tracked links and the open pixel in new mail from this domain use in place of the OpenEmail host. storageHost is a subdomain such as files.example.com that the download links for files sent from this domain use in place of the OpenEmail host. For either, null or an empty string removes that name, and a string sets it.
Each name is set up the same way, and the rest of this describes both. trackingHost reports into the tracking object on the response and storageHost into storage, and the field names below are the ones on whichever of the two you sent.
A new name is saved and checked straight away. Setting one needs the domain to be verified or its _openemail-challenge TXT record to be published, and it does not have to be receiving mail yet. Add a CNAME record named that host whose value is target, an address OpenEmail prepares for that name alone, with any proxying turned off. record in the response spells it out. If the address could not be prepared during the call, record is null and error says it is being prepared, and it is finished within a few minutes without another call. OpenEmail checks the name over HTTPS, and until a check passes, new mail keeps using the default OpenEmail host: status stays pending and error says what the last check saw. There is no need to call this again once the record is in place. A name that has not passed yet is checked every 2 minutes in its first hour, every 10 minutes in its first day, hourly in its first week and every 6 hours after that.
Once a check passes, new mail from this domain uses the name, and it is checked every 10 minutes. A failed check is retried after 1 minute and then 2, and three failures in a row put new mail back on the default host.
Sending a name that is already set checks it again at once, unless a check ran in the last 30 seconds, in which case the stored state comes back unchanged.
null or an empty string removes that name, and new mail goes back to the default host. Links in mail already sent keep the name they were sent with, whether it is removed or replaced, so they only keep working while its CNAME record stays in place. That holds for the download link on a file as much as for a tracked link. Setting a name up again can give it a different record, so publish the one the response reports.
A tracking domain serves tracking paths only and a files domain serves download paths only, and each answers only for mail the workspace that owns it sent. Either name applies to every address on the domain, so a key narrowed to individual addresses is refused with capability_unsupported. A key whose domainAllowlist holds this whole domain may set both, because that key already covers every address the change reaches.
Requires the domains:write scope.
Параметры пути
idstringОбязательноDomain id from
list, a UUID.
Тело запроса
catchAllbooleanTrue accepts mail to any address on this domain that nobody created, false refuses it. Leaving the field out leaves the catch-all alone.
trackingHoststringA subdomain of this domain, such as
links.example.com. It is trimmed and lowercased, and anhttp://orhttps://prefix, a path and a trailing dot are stripped.null, or a string that is empty once cleaned up, removes the tracking domain. Sending the name already set checks it again. Leaving the field out leaves the tracking domain alone.Может быть nullДо 512 символовstorageHoststringA subdomain of this domain, such as
files.example.com. It is cleaned up the same way astrackingHost.null, or a string that is empty once cleaned up, removes the files domain. Sending the name already set checks it again. Leaving the field out leaves the files domain alone.Может быть nullДо 512 символовdmarcPolicystringThe DMARC policy to publish:
none,quarantineorreject. Leaving the field out leaves the policy alone.Одно из"none""quarantine""reject"
Возвращает
The domain in the same shape as GET /domains/{id}, with receiving.catchAll, tracking and storage as they stand after this call.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 409
tracking_host_in_usewithparam: "trackingHost": another domain already uses that name, or the tracking domain on this one is managed by a different OpenEmail server.storage_host_in_usewithparam: "storageHost"is the same refusal for a files domain, and a name already taken by the other feature is refused here too, since one name cannot be both.domain_not_verified: this domain is not verified and its_openemail-challengeTXT record is not published yet, so it cannot take a new name, andparamis whichever field was sent.domain_not_sendablewithparam: "dmarcPolicy": mail from the domain is not signed yet, so a policy stricter thannonewould send its own mail to spam.- 422
invalid_tracking_hostwithparam: "trackingHost", orinvalid_storage_hostwithparam: "storageHost": the name is not a hostname, is not a subdomain of this domain, is the return path hostbounce.<domain>, belongs to OpenEmail, or is set up to receive mail.unknown_parameterfor any field other thancatchAll,trackingHost,storageHostanddmarcPolicy.invalid_parameterwhen the body is not a JSON object, whencatchAllis not a boolean, when a host field that is present is neither a string nor null, or is longer than 512 characters, or whendmarcPolicyis notnone,quarantineorreject. A body carrying none of the fields is not an error: it changes nothing and answers 200.capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain, which is any key narrowed to individual addresses and any key whosedomainAllowlistnames only other domains.
Ошибки, которые может вернуть любая операция401500Каталог ошибок
Также доступно в
DELETE/domains/{id}
Remove a domain
Removes the domain from the workspace. Mail to it stops being accepted, and nothing can be sent from it. Every address on it is removed 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. Any it could not take back are listed in leftBehind, and those have to be removed at your DNS provider. Records you published yourself are never touched, so remove them too once the domain is gone.
The last domain in a workspace cannot be removed here, because in the app removing it deletes the whole mailbox with it. Remove it in the app, where that is confirmed first. A domain that holds reserved account addresses cannot be removed either.
There is no undo. Adding the domain again starts it from scratch: its records have to be checked again and its addresses created again.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Возвращает
Removed, with any DNS records that have to be removed by hand.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.insufficient_authority: an OAuth access token acts for a member whose role does not holdworkspace:manage, which removing a domain needs, as it does in the app.step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 409
last_domain: this is the only domain in the workspace, so it can only be removed in the app.domain_holds_reserved_addresses: the domain holds account addresses that removing it would delete.- 422
capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция400401500Каталог ошибок
Также доступно в
POST/domains/{id}/verify
Check a domain now
Checks the DNS of the domain straight away and returns it in the same shape as GET /domains/{id}. On an unverified domain that is the check 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.
Call it after publishing records, rather than waiting for the next read to notice. When the last check ran under 10 seconds ago, the call checks nothing new and returns the domain as it stands, so polling it faster than that gains nothing. A record published a moment ago can take a few minutes to show up in public DNS.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Возвращает
The domain as the check left it.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 422
capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция400401500Каталог ошибок
Также доступно в
GET/domains/{id}/logo
Retrieve the logo of a domain
The brand logo inboxes show next to mail from the domain, with what public DNS answers with right now. published.ours turns true once the BIMI record pointing at the logo is live.
For a subdomain such as mail.example.com, parentDmarc reports the DMARC record of the domain it belongs to, because inboxes check that one too: they show the logo only when its p= and sp= both quarantine or reject at 100 percent. That record lives at the parent domain, so OpenEmail never changes it.
Requires the domains:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Возвращает
The logo and what public DNS answers with.
Ошибки
- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.
Ошибки, которые может вернуть любая операция400401403422500Каталог ошибок
Также доступно в
PUT/domains/{id}/logo
Set the logo of a domain
Uploads the brand logo inboxes show next to mail from the domain, replacing any there was. Send the SVG as svg. It is converted to the SVG Tiny PS format inboxes require: CSS is turned into attributes, the shape is made square and titled after the workspace, and anything inboxes do not draw is refused with the reason. A file that is SVG Tiny PS already is kept byte for byte.
OpenEmail serves the logo and publishes the BIMI TXT record where it writes the DNS for the domain, and records says how that went. Otherwise publish record at your DNS provider. Inboxes show the logo once the DMARC policy of the domain quarantines or rejects, which PATCH /domains/{id} with dmarcPolicy sets. Gmail also needs a mark certificate, set with PUT /domains/{id}/logo/certificate.
The domain has to be verified. A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Тело запроса
svgstringОбязательноThe logo as SVG markup, up to 1 MB. It is converted to the SVG Tiny PS format inboxes require, made square and titled after the workspace. A file that is SVG Tiny PS already is kept byte for byte, which keeps it the same as the copy inside a mark certificate.
Возвращает
The logo as it stands, and what happened to its record.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 409
domain_not_verified: the domain is not verified yet.- 422
invalid_parameteronsvgwhen it is missing, over 1 MB, not an SVG, or uses something inboxes do not draw, such as a bitmap image, a filter, a mask, a clipping path or a link to another file, and the message says which.unknown_parameterfor any other field, andcapability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция401500Каталог ошибок
Также доступно в
DELETE/domains/{id}/logo
Remove the logo of a domain
Removes the logo and deletes the stored file. Where OpenEmail writes the DNS for the domain, it takes its BIMI record down too. Otherwise remove the record yourself. Any mark certificate stays, ready for the next logo. Removing a logo from a domain that has none changes nothing.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Возвращает
The domain with url and record null.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 422
capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция400401500Каталог ошибок
Также доступно в
PUT/domains/{id}/logo/certificate
Set the mark certificate of a domain
Uploads the Verified Mark Certificate (VMC) or Common Mark Certificate (CMC) a certificate authority issued for the domain, replacing any there was. Gmail shows the logo only with one, and only a VMC earns the blue checkmark and the logo in Apple Mail.
Send the file as certificate: PEM text as it came, or a DER or PKCS #7 file encoded as base64. The chain is put in order with the mark certificate first and served as PEM, and the BIMI record points at it.
Inboxes compare the logo inside the certificate with the published one and show nothing when they differ. When they differ, the logo from the certificate becomes the published one, and logoFromCertificate says so.
The domain has to be verified. A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Тело запроса
certificatestringОбязательноThe certificate file the certificate authority sent, up to 128 KB: PEM text, which can hold the whole chain or a PKCS #7 bundle, or a DER or PKCS #7 file encoded as base64.
Возвращает
The logo with its certificate, and what happened to its record.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 409
domain_not_verified: the domain is not verified yet.- 422
invalid_parameteroncertificatewhen the file holds no certificate, cannot be read, is over 128 KB, holds no VMC or CMC, was issued for a different domain or has expired, and the message says which.unknown_parameterfor any other field, andcapability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция401500Каталог ошибок
Также доступно в
DELETE/domains/{id}/logo/certificate
Remove the mark certificate of a domain
Removes the mark certificate and deletes the stored file. The logo stays, and the BIMI record no longer points at a certificate, so Gmail and Apple Mail stop showing the logo. Removing a certificate from a domain that has none changes nothing.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Возвращает
The logo with certificate null.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 422
capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция400401500Каталог ошибок
Также доступно в
GET/domains/{id}/addresses
List the addresses on a domain
Every address on the domain, alphabetically, a page at a time, with its id, label, whether it is enabled and when it last received mail. That is the addresses created by hand or through this 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.
Requires the domains:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Параметры запроса
limitintegerRows per page, 1 to 100.
Не меньше 1Не больше 100По умолчанию25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Возвращает
A page of addresses, alphabetically.
Ошибки
- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.
Ошибки, которые может вернуть любая операция400401403422500Каталог ошибок
Также доступно в
POST/domains/{id}/addresses
Create an address
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. It does not copy them again later.
Creating an address that already exists, or one that was removed, is not an error: it comes back enabled and keeps its id, and its label changes only when you send one. Only an address that does not exist yet counts against the workspace limit. An address the catch-all picked up becomes one created by hand, so it keeps receiving when the catch-all is turned off. The workspace limit on addresses applies to new ones, and an address reserved as somebody's account address cannot be created.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Тело запроса
localPartstringОбязательноThe part in front of the @, 1 to 64 characters once trimmed, and lowercased. Letters, digits, the backtick and ! # $ % & ' * + / = ? ^ _ { | } ~ - are allowed, and so are dots between them.
*on its own is how the catch-all is written, so it is refused: turn the catch-all on withPATCH /domains/{id}instead.От 1 до 64 символовlabelstringA name for the address shown in the app, trimmed, up to 120 characters. Null, an empty string or leaving it out sets none.
Может быть nullДо 120 символов
Возвращает
The address.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.- 404
resource_not_found: no such domain. A domain in another workspace reads the same as one that does not exist.- 409
address_reservedwithparam: "localPart": the address is reserved as somebody's account address.- 422
invalid_parameteronlocalPartorlabel,unknown_parameterfor any other field,workspace_limit_reachedwhen the workspace already holds the most addresses it may have, andcapability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция401500Каталог ошибок
Также доступно в
GET/domains/{id}/addresses/{addressId}
Retrieve an address
One address on the domain.
Requires the domains:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
The address.
Ошибки
- 404
resource_not_found: no such domain, or no such address on it. A removed address is not found.
Ошибки, которые может вернуть любая операция400401403422500Каталог ошибок
Также доступно в
PATCH/domains/{id}/addresses/{addressId}
Update an address
Renames an address, or turns it off and on. Both fields are optional, and a field left out is left alone.
A disabled address stops 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 turning it back on picks up where it left off. That is the difference from DELETE.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Тело запроса
labelstringA new name for the address, trimmed, up to 120 characters. Null or an empty string removes it. Leaving the field out leaves it alone.
Может быть nullДо 120 символовenabledbooleanFalse stops the address taking mail: mail to it is refused while the sending server is still connected, so the sender gets a bounce. True takes mail again. Nothing already delivered is touched either way.
destinationstringWhere the mail of the address goes.
mailboxkeeps it here, and sends a copy to every forwarding destination that is on.forwardsends it only to the destinations and keeps no copy, so it needs at least one destination that is on, or it is refused with 409forward_required. Destinations are managed under/domains/{id}/addresses/{addressId}/forwards. Changing it asks an OAuth access token for a verification code.Одно из"mailbox""forward"
Возвращает
The address as it stands after this call.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.- 404
resource_not_found: no such domain, or no such address on it. A removed address is not found.- 422
invalid_parameteronlabelorenabled,unknown_parameterfor any other field, andcapability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция401500Каталог ошибок
Также доступно в
DELETE/domains/{id}/addresses/{addressId}
Remove an address
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 POST /domains/{id}/addresses brings it back with the same id, enabled, but without its old settings or access.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
Removed.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.insufficient_authority: an OAuth access token acts for a member whose role does not holdworkspace:manage, which removing an address needs, as it does in the app.step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.- 404
resource_not_found: no such domain, or no such address on it. An address already removed is not found.- 422
capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция400401500Каталог ошибок
Также доступно в
PUT/domains/{id}/addresses/{addressId}/photo
Set the photo of an address
Uploads the photo shown for the address in OpenEmail, in place of the domain logo, replacing any there was. Send the image itself as the body, not JSON, with its type in Content-Type: image/png, image/jpeg, image/webp, image/gif. Up to 5 MB goes in. It is cropped to a 512 pixel square and stored as JPEG or PNG, the formats other services such as Gravatar take.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Тело запроса
Тип содержимогоimage/png, image/jpeg, image/webp, image/gif
Возвращает
The address, with its new photoUrl.
Ошибки
- 404
resource_not_found: no such domain, or no such address on it. A removed address is not found.- 422
invalid_imagewhen the body is not an image of an accepted type, is too large or cannot be read.capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.- 502
image_not_stored: the image was read but could not be stored. Try again.- 503
image_busy: the image service is saturated. Try again shortly.
Ошибки, которые может вернуть любая операция400401403500Каталог ошибок
Также доступно в
DELETE/domains/{id}/addresses/{addressId}/photo
Remove the photo of an address
Removes the photo of the address and deletes the stored image, so the domain logo is shown for it again. Removing a photo from an address that has none changes nothing.
A key limited to particular addresses or domains has to hold this whole domain.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
The address, with photoUrl null.
Ошибки
- 404
resource_not_found: no such domain, or no such address on it. A removed address is not found.- 422
capability_unsupportedwithparam: "domainAllowlist"for a narrowed key that does not hold this whole domain.
Ошибки, которые может вернуть любая операция400401403500Каталог ошибок
Также доступно в
GET/app-host
Retrieve the web app address
The web app address of the workspace, with everything the Branded app tab shows: the address and the verified domain it sits under, whether people can sign in there, the DNS records to publish, and when it was last checked. With no address set, status is none, and domains and suggested list the verified domains and the address the app suggests.
Reading it checks the address again when its last check is more than 15 seconds old, so polling this route is how to wait for it to go live: active turns true on the read whose check finds it live. POST /app-host/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 and nobody can sign in there until the workspace is on a paid plan again.
Requires the domains:read scope.
Возвращает
The web app address, or status: "none" when none is set.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
PUT/app-host
Set the web app address
Sets the web app address of the workspace, replacing any it had, and returns it in the same shape as GET /app-host. 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 poll GET /app-host or call POST /app-host/verify. This call writes no DNS record itself.
An address on another domain replaces the old one once it is set up. An address on the same domain replaces the old one 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. Anyone else gets the usual wrong email or password answer, and an invited person can create their account there.
The address applies to the whole workspace, so a key or app limited to particular addresses or domains cannot set it.
Requires the domains:write scope.
Тело запроса
hoststringОбязательноA subdomain such as
mailbox.example.com, on a verified domain of this workspace or on any other domain you control. It is trimmed and lowercased, and anhttp://orhttps://prefix, a path and a trailing dot are stripped. A bare domain cannot be used.От 1 до 253 символов
Возвращает
The web app address as this call left it.
Ошибки
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lacksdomains:write.plan_required: the workspace is on the free plan, and a web app address needs a paid one.step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.- 409
app_host_in_usewithparam: "host": another workspace already uses the address, or a mail domain, a tracking host or a files host has that name. When another workspace set the address but never proved it, the message gives the TXT record that frees it for you.- 422
invalid_app_hostwithparam: "host": the address is not a hostname, it is a bare domain, or it is on a domain OpenEmail runs, and the message suggests one that works.invalid_parameteronhostwhen it is missing, empty or longer than 253 characters,unknown_parameterfor any other field, andcapability_unsupportedwithparam: "domainAllowlist"for a key or app limited to particular addresses or domains.- 503
app_host_unavailable: the address could not be set up just now, or web app addresses are switched off. Try again in a minute.
Ошибки, которые может вернуть любая операция401404500Каталог ошибок
Также доступно в
DELETE/app-host
Remove the web app address
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 not touched, so remove them at your DNS provider when you no longer need them.
Removing it when none is set changes nothing and answers deleted: false, so a repeated call is safe. Setting the same address again later sets it up from scratch.
The address applies to the whole workspace, so a key or app limited to particular addresses or domains cannot remove it.
Requires the domains:write scope.
Возвращает
What was removed.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.- 422
capability_unsupportedwithparam: "domainAllowlist"for a key or app limited to particular addresses or domains.- 503
app_host_unavailable: the address could not be removed just now, so it is still set. Try again in a minute.
Ошибки, которые может вернуть любая операция400401404500Каталог ошибок
Также доступно в
POST/app-host/verify
Check the web app address now
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 /app-host. When the last check ran under 10 seconds ago, the call checks nothing new and returns the address as it stands. With no address set, it checks nothing and answers status: "none". No body.
Requires the domains:write scope.
Возвращает
The web app address as the check left it.
Ошибки
- 403
insufficient_scope: the key lacksdomains:write.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
GET/domains/{id}/addresses/{addressId}/forwards
List the forwarding destinations of an address
Every place the mail of the address is forwarded to, with whether each destination confirmed it wants it, and destination, which says whether the address also keeps a copy here. An address forwards to 10 places at most.
Requires the domains:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
The destinations, oldest first.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
POST/domains/{id}/addresses/{addressId}/forwards
Forward the mail of an address
Adds places the mail of the address goes to. Each one is asked to confirm by email first, and receives nothing until it does. An address hosted here, one already on the list, one that would make a loop or one that refused mail from this workspace before is skipped and named in skipped with the reason, and the rest are added. An address that is switched off is refused with 409 address_disabled. A key or an app limited to some addresses needs the whole domain, and an app acting for a member can only forward an address that member reaches.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Тело запроса
emailsstring[]ОбязательноThe addresses to forward to, 1 to 10 of them. Each is trimmed and lowercased.
От 1 до 10 элементов
Возвращает
What was added and what was skipped.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
PATCH/domains/{id}/addresses/{addressId}/forwards/{forwardId}
Switch a forwarding destination on or off
Pauses a destination, or switches it back on. A paused destination keeps its confirmation, so switching it on again needs no new one. When the last destination that is on is paused, the address goes back to keeping its mail here.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.forwardIdstringОбязательноA forwarding destination of the address, as
GET /domains/{id}/addresses/{addressId}/forwardslists it.
Тело запроса
enabledbooleanОбязательноFalse pauses the destination, true switches it back on.
Возвращает
The destination as it is now.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
DELETE/domains/{id}/addresses/{addressId}/forwards/{forwardId}
Remove a forwarding destination
Stops forwarding to that place. When it was the last destination that was on, the address goes back to keeping its mail here.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.forwardIdstringОбязательноA forwarding destination of the address, as
GET /domains/{id}/addresses/{addressId}/forwardslists it.
Возвращает
Removed.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
POST/domains/{id}/addresses/{addressId}/forwards/{forwardId}/resend
Ask a forwarding destination to confirm again
Sends the confirmation email to the destination again. status says what happened: sent, already-confirmed when it has confirmed and needs nothing, too-soon when the last one went out moments ago, revoked when it refused mail from this workspace, and send-failed when the email could not be sent.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.forwardIdstringОбязательноA forwarding destination of the address, as
GET /domains/{id}/addresses/{addressId}/forwardslists it.
Возвращает
What became of the request.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
GET/domains/{id}/addresses/{addressId}/members
List who reaches an address
Everybody who can read the address, and how: the owner of the workspace, a role that reaches every address, a grant of the whole domain, or a grant of the address itself. removable says whether the grant can be taken back from the address alone. Change grants with POST /members/{userId}/addresses and DELETE /members/{userId}/addresses/{addressId}.
Requires the members:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
Who reaches the address.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
GET/domains/{id}/addresses/{addressId}/login
Read the sign-in of an address
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. It needs members:write, like setting one.
Requires the members:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
The sign-in, or null.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
PUT/domains/{id}/addresses/{addressId}/login
Set the password of an address
Gives the address a password, or replaces the one it has. Whoever holds it signs in as the address and reaches only its mail. The password needs at least 8 characters with a lowercase letter, an uppercase letter, a number and a special character, or the call is a 422 invalid_parameter on password. An address an OpenEmail account already signs in as is refused with 409 account_exists, a first password needs a plan with team access, and a key or an app has to hold everything a sign-in for one address may do.
Requires the members:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Тело запроса
passwordstringОбязательноAt least 8 characters, with a lowercase letter, an uppercase letter, a number and a special character.
От 1 до 512 символов
Возвращает
The sign-in as it is now.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
DELETE/domains/{id}/addresses/{addressId}/login
Remove the sign-in of an address
Takes the password away and signs out whoever used it. The address and its mail stay. An address with no password is a 404.
Requires the members:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.addressIdstringОбязательноThe address id, from
GET /domains/{id}/addressesorPOST /domains/{id}/addresses. It has to be an address on the domain in the path, and a removed address is not found.
Возвращает
Removed.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
GET/dns-connections
List DNS connections
The DNS provider accounts connected to the workspace, through which OpenEmail writes the records of a domain itself, with the domains each one serves. configured is false when this server cannot connect a provider at all. A connection is made in the app, because the provider asks the person to sign in.
Requires the domains:read scope.
Возвращает
Every connection, disconnected ones included.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
GET/dns-connections/{id}
Retrieve a DNS connection
One connection with what disconnecting it would leave behind: the domains it serves, the records OpenEmail wrote through it, busy for the domains a sync is running on right now, and keepsMail for the verified domains whose records come down with it.
Requires the domains:read scope.
Параметры пути
idstringОбязательноA DNS connection, as
GET /dns-connectionslists it.
Возвращает
The connection.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
DELETE/dns-connections/{id}
Disconnect a DNS connection
Takes the records OpenEmail wrote through the connection down, detaches every domain it serves and revokes it at the provider, so a verified domain whose records come down stops receiving mail. detached counts what came down and lists what is still published. A connection that is already disconnected is removed from the list instead, once nothing is left on it. A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member needs workspace:manage in their role.
Requires the domains:write scope.
Параметры пути
idstringОбязательноA DNS connection, as
GET /dns-connectionslists it.
Возвращает
Disconnected, or removed.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
GET/domains/{id}/dns
Read how the DNS of a domain is set up
Whether OpenEmail writes the records of the domain itself, through which connection and zone, where each kind of record stands, 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 a choice, none holds it, or the connections could not be asked (unusable).
Requires the domains:read scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Параметры запроса
refreshbooleanTrue asks the providers again which zone answers for the domain, rather than using the answer from the last minutes.
Возвращает
The DNS setup of the domain.
Ошибки
Ошибки, которые может вернуть любая операция400401403404422500Каталог ошибок
Также доступно в
PUT/domains/{id}/dns
Choose the zone a domain is set up through
Attaches the domain to a zone of a connection, after checking the zone covers the domain, is active and takes a test record. Nothing is written yet: sync the domain to write its records. A domain set up through another zone is refused with 409 dns_zone_conflict.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Тело запроса
connectionIdstringОбязательноThe connection that holds the zone, from
dnsConnections.list.От 1 до 64 символовzoneIdstringОбязательноThe zone, as
zone.candidatesofgetDnslists it.От 1 до 64 символов
Возвращает
The DNS setup as it is now.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
POST/domains/{id}/dns/sync
Write the DNS records of a domain
Finds the zone that answers for the domain among the connections, attaches it when it is the only one, and writes or repairs every record the domain needs there. With purpose, only that kind of record. When no single zone answers, nothing is written and outcome is refused with the reason in message. A domain that was waiting for its records is verified once they are in place.
Requires the domains:write scope.
Параметры пути
idstringОбязательноThe domain id, from
GET /domainsorPOST /domains. A domain in another workspace reads the same as one that does not exist.
Тело запроса
purposestringOnly this kind of record:
dmarc,tracking,storage,bimiorapp-host.Одно из"dmarc""tracking""storage""bimi""app-host"
Возвращает
What was written, or why nothing was.
Ошибки
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code.
Ошибки, которые может вернуть любая операция400401404422500Каталог ошибок
Также доступно в
Объекты
AddressForwardobject
objectstring- Одно из
"address_forward" idstringaddressIdstringemailstringWhere the mail goes.
enabledbooleanFalse while the destination is paused.
statusstringliveonce the destination confirmed it wants this mail,pendingwhile it has not answered,refusedwhen it said no, andpausedwhile it is switched off. Only a live destination receives anything.Одно из"live""pending""refused""paused"confirmedAtstring- Может быть nullФормат
date-time askedAtstringWhen the confirmation email last went out.
Может быть nullФорматdate-timelastRelayAtstring- Может быть nullФормат
date-time lastErrorstringWhy the last forward failed, cleared once one succeeds.
Может быть nullfailuresintegerFailures in a row.
createdAtstring- Формат
date-time
AddressForwardChangeobject
objectstring- Одно из
"address_forward" idstringaddressIdstringemailstringWhere the mail goes.
enabledbooleanFalse while the destination is paused.
statusstringliveonce the destination confirmed it wants this mail,pendingwhile it has not answered,refusedwhen it said no, andpausedwhile it is switched off. Only a live destination receives anything.Одно из"live""pending""refused""paused"destinationstringWhere the mail of the address goes after the change.
Одно из"mailbox""forward"
AddressForwardConsentobject
objectstring- Одно из
"address_forward_consent" idstringaddressIdstringemailstringstatusstring- Одно из
"sent""already-confirmed""revoked""too-soon""send-failed"
AddressForwardListobject
objectstring- Одно из
"list" addressstringdestinationstring- Одно из
"mailbox""forward" maxintegerHow many destinations one address may have.
dataAddressForward[]
AddressForwardsAddedobject
objectstring- Одно из
"address_forwards" addedAddressForward[]skippedobject[]emailstringreasonstring
AddressLoginobject
objectstring- Одно из
"address_login" addressIdstringaddressstringcreatedbooleanOn a PUT, true when the password is new rather than a replacement.
loginobject- Может быть null
userIdstringnamestringcreatedAtstring- Формат
date-time createdBystring- Может быть null
passwordSetAtstring- Формат
date-time passwordSetBystring- Может быть null
lastSignedInAtstring- Может быть nullФормат
date-time
AddressMemberobject
objectstring- Одно из
"address_member" userIdstringemailstringnamestring- Может быть null
imagestring- Может быть null
accessstring- Одно из
"member""viewer" viastring- Одно из
"owner""every-address""whole-domain""direct" viaDomainstringThe domain whose grant brings them here, when
viaiswhole-domain.Может быть nullremovableboolean
AddressMemberListobject
objectstring- Одно из
"list" dataAddressMember[]
AppHostobject
The web app address of the workspace: a subdomain such as mailbox.example.com, on one of its verified domains or on any other domain it controls, where its people open the OpenEmail web app under the workspace brand. A workspace has at most one. Set it with PUT /app-host and remove it with DELETE /app-host.
objectstring- Одно из
"app_host" idstringThe id of the address,
ahost_and 24 hex characters. Null when none is set.Может быть nullhoststringThe address, lowercased. Null when none is set.
Может быть nulldomainIdstringThe id of the verified domain of the workspace the address sits under, as
GET /domainslists it. Null when none is set, or when the address is on another domain.Может быть nulldomainstringThe verified domain of the workspace the address sits under. Null when none is set, or when the address is on another domain.
Может быть nullstatusstringnonemeans no address is set.pendingmeans it is set and waiting for its DNS records to answer and its certificate to be issued.activemeans the address answers over HTTPS.failedmeans setting it up failed, usually because the record was missing or wrong for too long, anderrorsays why. Set the address again to start over.Одно из"none""pending""active""failed"activebooleanWhether people can sign in at the address right now. True exactly when
statusisactiveand the workspace is on a paid plan.pausedbooleanTrue when an address is set and the workspace is on the free plan. Nobody can sign in there, and emails link to openemail.uk instead, until the workspace is on a paid plan again. The address and its record are kept.
targetstringThe host the CNAME record points at, the same for every workspace. Null only while web app addresses cannot be set up.
Может быть nullrecordobjectThe CNAME record to add at your DNS provider. Null when no address is set.
Может быть nulltypestringAlways
CNAME.Одно из"CNAME"namestringThe record name, which is
host.valuestringThe record value, which is
target.
ownershipRecordobjectThe TXT record that proves the domain of the address is yours, to add next to
record. Nothing is set up for the address until it answers. Null when no address is set, or when the address is on a verified domain of the workspace, which proves it already.Может быть nulltypestringAlways
TXT.Одно из"TXT"namestringThe record name,
_openemail-challenge.in front ofhost.valuestringThe record value. It stays the same for this address in this workspace.
ownershipVerifiedbooleanWhether the address is proven to be yours: true when it is on a verified domain of the workspace or
ownershipRecordanswered. False when no address is set.errorstringWhy setting the address up failed or has not finished, written to be shown to a person. Null when there is nothing to report.
Может быть nullcheckedAtstringWhen the address was last checked. Null until the first check.
Может быть nullФорматdate-timeverifiedAtstringWhen the address first answered over HTTPS. Null while it never has.
Может быть nullФорматdate-timeavailablebooleanWhether web app addresses can be set up right now. False only while they are switched off, and then
PUT /app-hostanswers 503app_host_unavailable.paidPlanbooleanWhether the workspace is on a paid plan, which a web app address needs.
domainsstring[]The verified domains of the workspace, alphabetically. An address on one of them needs only
record.suggestedstringThe address the app suggests: the current one, or
mailbox.in front of the first verified domain. Null when the workspace has no verified domain.Может быть null
DeletedAddressForwardobject
objectstring- Одно из
"address_forward" idstringaddressIdstringemailstringdeletedboolean- Одно из
true destinationstring- Одно из
"mailbox""forward"
DeletedAddressLoginobject
objectstring- Одно из
"address_login" addressIdstringaddressstringdeletedboolean- Одно из
true
DeletedAppHostobject
objectstring- Одно из
"app_host" idstringThe id of the address that was removed. Null when none was set.
Может быть nullhoststringThe address that was removed. Null when none was set.
Может быть nulldeletedbooleanTrue when an address was removed, false when none was set, so a repeated call is safe.
DeletedDnsConnectionobject
objectstring- Одно из
"dns_connection" idstringproviderstring- Одно из
"cloudflare""operator-cloudflare" subjectstringWho the connection signed in as at the DNS provider, usually an email address.
accountsDnsAccount[]The provider accounts the connection reaches.
statusstringactivewhile OpenEmail may write through it,needs-reauthwhen the provider wants the account connected again,revokedonce it was disconnected, anderrorwhen the last call failed.Одно из"active""needs-reauth""revoked""error"lastVerifiedAtstring- Может быть nullФормат
date-time lastErrorstring- Может быть null
createdAtstring- Формат
date-time removedbooleanTrue when the connection was already disconnected and is now gone.
confirmedbooleanWhether the provider confirmed the revocation. Null when it was removed.
Может быть nulldetachedobject- Может быть null
domainsintegerdetachedintegerremovedintegerRecords deleted.
rewrittenintegerRecords shared with others, rewritten.
pendingintegerRecords still published.
leftDnsLeftRecord[]
DeletedDomainobject
objectstring- Одно из
"domain" idstringdomainstringdeletedboolean- Одно из
true leftBehindstring[]DNS records OpenEmail wrote for this domain and could not take back, one line each naming the record and why. They are still published, so remove them at your DNS provider. Empty when nothing was left, which is always the case for a domain whose DNS OpenEmail never wrote.
DeletedDomainAddressobject
objectstring- Одно из
"address" idstringaddressstringThe full address that was removed, lowercased.
deletedboolean- Одно из
true
DnsAccountobject
idstringnamestring- Может быть null
DnsConnectionobject
objectstring- Одно из
"dns_connection" idstringproviderstring- Одно из
"cloudflare""operator-cloudflare" subjectstringWho the connection signed in as at the DNS provider, usually an email address.
accountsDnsAccount[]The provider accounts the connection reaches.
statusstringactivewhile OpenEmail may write through it,needs-reauthwhen the provider wants the account connected again,revokedonce it was disconnected, anderrorwhen the last call failed.Одно из"active""needs-reauth""revoked""error"lastVerifiedAtstring- Может быть nullФормат
date-time lastErrorstring- Может быть null
createdAtstring- Формат
date-time domainsDnsConnectionDomain[]recordsintegerHow many records OpenEmail wrote through the connection and still keeps.
removablebooleanTrue for a disconnected connection with nothing left on it, which a second
DELETEremoves from the list.
DnsConnectionDetailobject
objectstring- Одно из
"dns_connection" idstringproviderstring- Одно из
"cloudflare""operator-cloudflare" subjectstringWho the connection signed in as at the DNS provider, usually an email address.
accountsDnsAccount[]The provider accounts the connection reaches.
statusstringactivewhile OpenEmail may write through it,needs-reauthwhen the provider wants the account connected again,revokedonce it was disconnected, anderrorwhen the last call failed.Одно из"active""needs-reauth""revoked""error"lastVerifiedAtstring- Может быть nullФормат
date-time lastErrorstring- Может быть null
createdAtstring- Формат
date-time domainsDnsConnectionDomain[]recordsintegerHow many records OpenEmail wrote through the connection and still keeps.
removablebooleanTrue for a disconnected connection with nothing left on it, which a second
DELETEremoves from the list.busystring[]The domains a sync is running on, which stop a disconnect until it ends.
keepsMailstring[]The verified domains that stop receiving mail when their records come down.
DnsConnectionDomainobject
domainIdstringdomainstring- Может быть null
zoneIdstring- Может быть null
zoneNamestring- Может быть null
statestring- Может быть nullОдно из
"unmanaged""ready""awaiting-sync""awaiting-signing""conflict""blocked" recordsintegerkeepsMailbooleanTrue for a verified domain, which stops receiving when its records come down.
busybooleanTrue while a sync is running on the domain.
DnsConnectionListobject
objectstring- Одно из
"list" configuredbooleanFalse when this server cannot connect a DNS provider.
dataDnsConnection[]
DnsLeftRecordobject
A record still published that OpenEmail could not take down.
purposestring- Одно из
"challenge""dkim""spf""mx""mail-from""dmarc""tracking""storage""bimi""app-host" namestringtypestringcontentstringstandingstring- Одно из
"ours""theirs""unverified" detailstring
DnsZoneobject
idstringnamestringaccountIdstring- Может быть null
activebooleanstatusstringtypestringnameServersstring[]coversbooleanWhether the zone covers the domain.
DnsZoneCandidateobject
connectionIdstringsubjectstringstatusstring- Одно из
"active""needs-reauth""revoked""error" accountsDnsAccount[]accountDnsAccountzoneDnsZone
DnsZoneObstacleobject
connectionIdstringsubjectstringstatusstring- Одно из
"active""needs-reauth""revoked""error" accountsDnsAccount[]obstaclestring- Одно из
"needs-reauth""unreachable" detailstring
DnsZoneResolutionobject
kindstring- Одно из
"resolved""ambiguous""none""unusable" checkedAtstring- Формат
date-time cachedbooleancandidateDnsZoneCandidatecandidatesDnsZoneCandidate[]reasonstringWhy no zone answers, when
kindisnone.Может быть nullОдно из"not-configured""no-links""not-held"connectedinteger- Может быть null
hoststringWho serves the DNS of the domain, when
kindisnone.Может быть nullОдно из"cloudflare""elsewhere""unknown"blockedDnsZoneObstacle[]The connections that could not be asked.
Domainobject
objectstring- Одно из
"domain" idstringdomainstringreceivingobjectverifiedbooleanWhether ownership has been proven. A verified domain can receive mail.
verifiedAtstring- Может быть nullФормат
date-time catchAllbooleanWhether mail to a local-part nobody created on this domain is accepted.
lastCheckedAtstring- Может быть nullФормат
date-time errorstringWhy the last ownership check failed.
Может быть null
sendingobjectstatusstringThe signing state as the last check saw it.
Одно из"unknown""no_identity""pending""verified""failed"canSendbooleanWhether a send from this domain would be accepted right now.
checkedAtstringWhen
statuswas last checked. Null until the first check.Может быть nullФорматdate-timeerrorstringWhy the last signing check failed.
Может быть nullnotestringWhat
statusmeans, written to be shown to a person.
trackingDomainTrackingstorageDomainStoragelogoDomainLogodmarcPolicystringThe DMARC policy set with
PATCH /domains/{id}. Null when it was never set, in which case the DMARC record of the domain is left as it is. Where OpenEmail writes the DNS for the domain, it publishes this policy and keeps every other tag of the record, such asrua. Otherwise publish the DMARC record inrecords.Может быть nullОдно из"none""quarantine""reject"createdAtstring- Формат
date-time
DomainAddressobject
objectstring- Одно из
"address" idstringThe address id. Pass it as
addressId.domainIdstringThe domain the address is on.
addressstringThe full address, lowercased.
localPartstringThe part in front of the @, lowercased.
labelstringThe name mail from the address is sent under and shown in the app, such as
Support. Null when none is set, and mail then goes out under the name of the workspace or the person sending.Может быть nullphotoUrlstringThe photo set for the address with
PUT /domains/{id}/addresses/{addressId}/photo, shown for it in OpenEmail. Null when none is set, and the domain logo is shown instead.Может быть nullenabledbooleanWhether the address takes mail. Mail to a disabled address is refused while the sending server is still connected, so the sender gets a bounce, and nothing can be sent from it.
destinationstringmailboxwhen mail to the address lands here, with a copy to each forwarding destination that is on, andforwardwhen it only goes to the destinations.Одно из"mailbox""forward"lastReceivedAtstringWhen mail last arrived for the address. Null when none has.
Может быть nullФорматdate-timecreatedAtstring- Формат
date-time updatedAtstring- Формат
date-time
DomainAddressListobject
objectstring- Одно из
"list" dataDomainAddress[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Может быть null
DomainDetailobject
A domain as GET /domains lists it, plus its addresses, every DNS record it uses and its DMARC reading.
objectstring- Одно из
"domain" idstringdomainstringreceivingobjectverifiedbooleanWhether ownership has been proven. A verified domain can receive mail.
verifiedAtstring- Может быть nullФормат
date-time catchAllbooleanWhether mail to a local-part nobody created on this domain is accepted.
lastCheckedAtstring- Может быть nullФормат
date-time errorstringWhy the last ownership check failed.
Может быть null
sendingobjectstatusstringThe signing state as the last check saw it.
Одно из"unknown""no_identity""pending""verified""failed"canSendbooleanWhether a send from this domain would be accepted right now.
checkedAtstringWhen
statuswas last checked. Null until the first check.Может быть nullФорматdate-timeerrorstringWhy the last signing check failed.
Может быть nullnotestringWhat
statusmeans, written to be shown to a person.
trackingDomainTrackingstorageDomainStoragelogoDomainLogodmarcPolicystringThe DMARC policy set with
PATCH /domains/{id}. Null when it was never set, in which case the DMARC record of the domain is left as it is. Where OpenEmail writes the DNS for the domain, it publishes this policy and keeps every other tag of the record, such asrua. Otherwise publish the DMARC record inrecords.Может быть nullОдно из"none""quarantine""reject"createdAtstring- Формат
date-time addressesobject[]Every address on this domain. Not present on a
GET /domainsrow.addressstringThe full address, lowercased.
enabledboolean
recordsDomainRecord[]Every DNS record the domain uses, in this order: the MX records and the SPF record that bring mail in, the
_openemail-challengeTXT record that proves you own the domain, a starter DMARC record, the signing records once they are prepared, the two return path records on the bounce host, and the CNAME records for a tracking domain and a files domain when either is set. The domain is verified once public DNS answers with both the MX records and the challenge record. Publishing the signing records is what lets mail from the domain be sent.dmarcobjectWhat the domain's DMARC record says, read from public DNS, and whether a stricter policy is safe yet. OpenEmail only changes this record for you to publish the starter record it offers, or the policy set as
dmarcPolicy.Может быть nullstagestringmissingwhen the domain has no DMARC record,invalidwhen it has one receivers cannot use, and otherwise the policy it sets:monitorforp=none,quarantineorreject.Одно из"missing""invalid""monitor""quarantine""reject"recordstringThe record as published, or null when there is none. For a zone OpenEmail writes to, this can show the starter record for up to an hour before public DNS answers with it.
Может быть nullissuesstring[]Problems found in the record, each written to be shown to a person. Empty when there are none.
alignmentPossiblebooleanWhether this domain has a signing key set up. Without one, a policy stricter than
p=nonewould tell receivers to throw away the domain's own mail.caveatstringWhat to check before tightening the policy, written to be shown to a person beside it.
DomainDnsobject
objectstring- Одно из
"domain_dns" domainIdstringdomainstringmanagingbooleanTrue while OpenEmail writes the records of the domain itself.
connectionIdstring- Может быть null
connectionobject- Может быть null
idstringstatusstring- Одно из
"active""needs-reauth""revoked""error" subjectstringaccountsDnsAccount[]
zoneIdstring- Может быть null
zoneNamestring- Может быть null
zoneHolderstring- Может быть null
statestring- Одно из
"unmanaged""ready""awaiting-sync""awaiting-signing""conflict""blocked" stepsobject[]purposestring- Одно из
"challenge""dkim""spf""mx""mail-from""dmarc""tracking""storage""bimi""app-host" okbooleandetailstringvisibilitystring- Одно из
"held""missing""unchecked""public" recordsobject[]namestringtypestringvaluesstring[]requiredbooleanvisibilitystring- Одно из
"held""missing""unchecked""public"
leftoversDnsLeftRecord[]probeobjectA test record OpenEmail wrote to check it may write in the zone and could not take down again, to delete by hand.
Может быть nullnamestring- Может быть null
typestringzoneIdstringzoneNamestring- Может быть null
detailstringnoticedAtstring- Формат
date-time
errorstring- Может быть null
syncedAtstring- Может быть nullФормат
date-time
DomainDnsSyncobject
objectstring- Одно из
"domain_dns_sync" outcomestring- Одно из
"synced""refused" messagestringWhy nothing was written, when
outcomeisrefused.Может быть nullattachedbooleanTrue when this sync attached the domain to its zone.
provisionobject- Может быть null
outcomestring- Одно из
"applied""unmanaged""lease-held""domain-missing""link-unusable""zone-unusable""provider-unreachable" statestring- Одно из
"unmanaged""ready""awaiting-sync""awaiting-signing""conflict""blocked" connectionIdstring- Может быть null
zoneIdstring- Может быть null
provenbooleanWhether the domain proved it belongs here.
ownershipstringwrittenobject[]purposestring- Одно из
"challenge""dkim""spf""mx""mail-from""dmarc""tracking""storage""bimi""app-host" namestringtypestringmodestring- Одно из
"created""merged"
adoptedintegerRecords that were already right.
conflictsobject[]kindstring- Одно из
"foreign-mx""foreign-record""spf-lookup-limit""spf-redirect""spf-duplicate""email-routing-locked""cname-flattening""zone-not-active""name-taken""delegated" purposestring- Может быть null
namestringexistingstring- Может быть null
detailstring
failuresobject[]purposestringnamestringerrorstring
stepsobject[]purposestring- Одно из
"challenge""dkim""spf""mx""mail-from""dmarc""tracking""storage""bimi""app-host" okbooleandetailstringvisibilitystring- Одно из
"held""missing""unchecked""public" recordsobject[]namestringtypestringvaluesstring[]requiredbooleanvisibilitystring- Одно из
"held""missing""unchecked""public"
retiredobject[]purposestringoutcomestring- Одно из
"deleted""rewritten""kept""pending""failed" detailstring
leftoversDnsLeftRecord[]probeobjectA test record OpenEmail wrote to check it may write in the zone and could not take down again, to delete by hand.
Может быть nullnamestring- Может быть null
typestringzoneIdstringzoneNamestring- Может быть null
detailstringnoticedAtstring- Формат
date-time
errorstring- Может быть null
dnsDomainDns
DomainListobject
objectstring- Одно из
"list" dataDomain[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Может быть null
DomainLogoobject
The brand logo inboxes show next to mail from the domain, through BIMI. Yahoo, AOL and Fastmail show it once the DMARC policy of the domain quarantines or rejects. Gmail also needs a mark certificate, and Apple Mail a VMC.
urlstringWhere the logo is served, in the SVG Tiny PS format inboxes require. Null when the domain has no logo.
Может быть nullrecordobjectOne DNS record the domain uses, with what the last check found. Publish
type,nameandvalueexactly as given. The values are specific to this domain and this service, so a value copied from anywhere else does not work.Может быть nulltypestringThe record type:
MX,TXTorCNAME.namestringThe full record name, such as
example.comor_dmarc.example.com. Some DNS providers want only the part in front of your domain.valuestringThe record value, to publish exactly as given.
priorityintegerThe priority of an MX record. Null on every other type.
Может быть nullpurposestringWhat the record is for, written to be shown to a person. Null on the MX records and the SPF record on the domain itself, which are the records that bring mail in.
Может быть nullstatusstringfoundwhen the last check saw the record in public DNS, andmissingwhen it looked and did not. Null means the record has not been checked yet. Where OpenEmail writes the DNS for this domain itself, what the zone holds is reported instead.Может быть nullОдно из"found""missing"
certificateobjectThe mark certificate published with the logo. Gmail shows a logo only with one, and Apple Mail only with a VMC.
Может быть nullurlstringWhere the certificate chain is served as PEM, the
a=of the BIMI record.markstringverifiedfor a Verified Mark Certificate (VMC),commonfor a Common Mark Certificate (CMC), andunknownwhen the certificate does not say.Одно из"verified""common""unknown"expiresAtstringWhen the certificate expires. Inboxes stop showing the logo after that.
Может быть nullФорматdate-timedomainsstring[]The domains the certificate was issued for.
issuerstringThe certificate authority that issued it.
Может быть null
matchesCertificatebooleanWhether the published logo is the one inside the certificate. Gmail and Apple Mail only show the logo when the two match. Null when there is no certificate, or it carries no logo.
Может быть null
DomainLogoChangeobject
The brand logo inboxes show next to mail from the domain, through BIMI. Yahoo, AOL and Fastmail show it once the DMARC policy of the domain quarantines or rejects. Gmail also needs a mark certificate, and Apple Mail a VMC.
urlstringWhere the logo is served, in the SVG Tiny PS format inboxes require. Null when the domain has no logo.
Может быть nullrecordobjectOne DNS record the domain uses, with what the last check found. Publish
type,nameandvalueexactly as given. The values are specific to this domain and this service, so a value copied from anywhere else does not work.Может быть nulltypestringThe record type:
MX,TXTorCNAME.namestringThe full record name, such as
example.comor_dmarc.example.com. Some DNS providers want only the part in front of your domain.valuestringThe record value, to publish exactly as given.
priorityintegerThe priority of an MX record. Null on every other type.
Может быть nullpurposestringWhat the record is for, written to be shown to a person. Null on the MX records and the SPF record on the domain itself, which are the records that bring mail in.
Может быть nullstatusstringfoundwhen the last check saw the record in public DNS, andmissingwhen it looked and did not. Null means the record has not been checked yet. Where OpenEmail writes the DNS for this domain itself, what the zone holds is reported instead.Может быть nullОдно из"found""missing"
certificateobjectThe mark certificate published with the logo. Gmail shows a logo only with one, and Apple Mail only with a VMC.
Может быть nullurlstringWhere the certificate chain is served as PEM, the
a=of the BIMI record.markstringverifiedfor a Verified Mark Certificate (VMC),commonfor a Common Mark Certificate (CMC), andunknownwhen the certificate does not say.Одно из"verified""common""unknown"expiresAtstringWhen the certificate expires. Inboxes stop showing the logo after that.
Может быть nullФорматdate-timedomainsstring[]The domains the certificate was issued for.
issuerstringThe certificate authority that issued it.
Может быть null
matchesCertificatebooleanWhether the published logo is the one inside the certificate. Gmail and Apple Mail only show the logo when the two match. Null when there is no certificate, or it carries no logo.
Может быть nullobjectstring- Одно из
"domain_logo" domainIdstringdomainstringdmarcPolicystringThe DMARC policy set with
PATCH /domains/{id}, as on the domain.Может быть nullОдно из"none""quarantine""reject"recordsstringWhat happened to the BIMI record.
publishedwhen OpenEmail writes the DNS for the domain and the record is in place.manualwhen it does not, so publishrecordyourself.blockedwhen a record you published yourself is in the way, which OpenEmail does not replace without asking: replace it yourself, or sync the domain in the app.busywhen another change to the DNS of the domain was running, andfailedwhen the DNS provider refused. Call again for either.Одно из"published""manual""blocked""busy""failed"logoFromCertificatebooleanTrue when the certificate carried a different logo from the one published, so its logo is now the published one. Inboxes compare the two.
DomainLogoStatusobject
The brand logo inboxes show next to mail from the domain, through BIMI. Yahoo, AOL and Fastmail show it once the DMARC policy of the domain quarantines or rejects. Gmail also needs a mark certificate, and Apple Mail a VMC.
urlstringWhere the logo is served, in the SVG Tiny PS format inboxes require. Null when the domain has no logo.
Может быть nullrecordobjectOne DNS record the domain uses, with what the last check found. Publish
type,nameandvalueexactly as given. The values are specific to this domain and this service, so a value copied from anywhere else does not work.Может быть nulltypestringThe record type:
MX,TXTorCNAME.namestringThe full record name, such as
example.comor_dmarc.example.com. Some DNS providers want only the part in front of your domain.valuestringThe record value, to publish exactly as given.
priorityintegerThe priority of an MX record. Null on every other type.
Может быть nullpurposestringWhat the record is for, written to be shown to a person. Null on the MX records and the SPF record on the domain itself, which are the records that bring mail in.
Может быть nullstatusstringfoundwhen the last check saw the record in public DNS, andmissingwhen it looked and did not. Null means the record has not been checked yet. Where OpenEmail writes the DNS for this domain itself, what the zone holds is reported instead.Может быть nullОдно из"found""missing"
certificateobjectThe mark certificate published with the logo. Gmail shows a logo only with one, and Apple Mail only with a VMC.
Может быть nullurlstringWhere the certificate chain is served as PEM, the
a=of the BIMI record.markstringverifiedfor a Verified Mark Certificate (VMC),commonfor a Common Mark Certificate (CMC), andunknownwhen the certificate does not say.Одно из"verified""common""unknown"expiresAtstringWhen the certificate expires. Inboxes stop showing the logo after that.
Может быть nullФорматdate-timedomainsstring[]The domains the certificate was issued for.
issuerstringThe certificate authority that issued it.
Может быть null
matchesCertificatebooleanWhether the published logo is the one inside the certificate. Gmail and Apple Mail only show the logo when the two match. Null when there is no certificate, or it carries no logo.
Может быть nullobjectstring- Одно из
"domain_logo" domainIdstringdomainstringdmarcPolicystringThe DMARC policy set with
PATCH /domains/{id}, as on the domain.Может быть nullОдно из"none""quarantine""reject"publishedobjectWhat public DNS answers with at
default._bimi.<domain>right now.foundbooleanWhether a BIMI record is published.
oursbooleanWhether the published record points at the logo OpenEmail serves.
valuestringThe published record, or null when there is none.
Может быть null
parentDmarcobjectFor a subdomain such as
mail.example.com, inboxes also check the DMARC record of the domain it belongs to before they show a logo. Null on a domain that is not a subdomain.Может быть nulldomainstringThe parent domain, such as
example.com.recordstringIts DMARC record, or null when it has none.
Может быть nullpolicystringIts
p=.Может быть nullsubdomainPolicystringIts
sp=, which falls back top=when the record has none.Может быть nullpercentintegerIts
pct=, 100 when the record has none.readablebooleanFalse when public DNS could not be asked. The other fields are then empty.
enforcedbooleanWhether both
p=andsp=quarantine or reject at 100 percent, which inboxes need before they show a logo for the subdomain.
DomainRecordobject
One DNS record the domain uses, with what the last check found. Publish type, name and value exactly as given. The values are specific to this domain and this service, so a value copied from anywhere else does not work.
typestringThe record type:
MX,TXTorCNAME.namestringThe full record name, such as
example.comor_dmarc.example.com. Some DNS providers want only the part in front of your domain.valuestringThe record value, to publish exactly as given.
priorityintegerThe priority of an MX record. Null on every other type.
Может быть nullpurposestringWhat the record is for, written to be shown to a person. Null on the MX records and the SPF record on the domain itself, which are the records that bring mail in.
Может быть nullstatusstringfoundwhen the last check saw the record in public DNS, andmissingwhen it looked and did not. Null means the record has not been checked yet. Where OpenEmail writes the DNS for this domain itself, what the zone holds is reported instead.Может быть nullОдно из"found""missing"
DomainStorageobject
The custom files domain on a domain: a subdomain such as files.example.com that the download links for files sent from that domain use in place of the OpenEmail host, once a check has passed. A domain has at most one. Set or remove it with PATCH /domains/{id}.
hoststringThe files domain, lowercased. Null when none is set.
Может быть nullstatusstringnonemeans no files domain is set.pendingmeans one is set and has never passed a check, so download links still use the default OpenEmail host.activemeans new mail from this domain uses it.failedmeans it passed a check before and is not in use now, so new links are back on the default host until a check passes again.Одно из"none""pending""active""failed"activebooleanWhether the download links in new mail from this domain use the files domain right now. True exactly when
statusisactive. Links fall back to the default host after three failed checks in a row, or once the last successful check is more than 2 hours old, so a name that has failed once or twice is still active and carries the reason inerror.targetstringThe address the CNAME record must point at, prepared by OpenEmail for this files domain alone. An empty string when no files domain is set, and while the address for a new one is still being prepared.
recordobjectThe DNS record to add at your DNS provider, as a plain CNAME with any proxying turned off. Null when no files domain is set, and while its address is still being prepared.
Может быть nulltypestringAlways
CNAME.Одно из"CNAME"namestringThe record name, which is
host.valuestringThe record value, which is
target.
checkedAtstringWhen the last check ran, whether it passed or not. Null until the first one.
Может быть nullФорматdate-timeverifiedAtstringWhen a check last passed. Null while the name has never passed one.
Может быть nullФорматdate-timeerrorstringWhy the last check failed, written to be shown to a person. Null when the last check passed or none has run yet. A name managed by a different OpenEmail server always carries a message saying so.
Может быть null
DomainTrackingobject
The custom tracking domain on a domain: a subdomain such as links.example.com that tracked links and the open pixel in new mail from that domain use in place of the OpenEmail host, once a check has passed. A domain has at most one. Set or remove it with PATCH /domains/{id}.
hoststringThe tracking domain, lowercased. Null when none is set.
Может быть nullstatusstringnonemeans no tracking domain is set.pendingmeans one is set and has never passed a check, so mail still uses the default OpenEmail host.activemeans new mail from this domain uses it.failedmeans it passed a check before and is not in use now, so new mail is back on the default host until a check passes again.Одно из"none""pending""active""failed"activebooleanWhether new mail from this domain uses the tracking domain right now. True exactly when
statusisactive. Mail falls back to the default host after three failed checks in a row, or once the last successful check is more than 2 hours old, so a name that has failed once or twice is still active and carries the reason inerror.targetstringThe address the CNAME record must point at, prepared by OpenEmail for this tracking domain alone. An empty string when no tracking domain is set, and while the address for a new one is still being prepared.
recordobjectThe DNS record to add at your DNS provider, as a plain CNAME with any proxying turned off. Null when no tracking domain is set, and while its address is still being prepared.
Может быть nulltypestringAlways
CNAME.Одно из"CNAME"namestringThe record name, which is
host.valuestringThe record value, which is
target.
checkedAtstringWhen the last check ran, whether it passed or not. Null until the first one.
Может быть nullФорматdate-timeverifiedAtstringWhen a check last passed. Null while the name has never passed one.
Может быть nullФорматdate-timeerrorstringWhy the last check failed, written to be shown to a person. Null when the last check passed or none has run yet. A name managed by a different OpenEmail server always carries a message saying so.
Может быть null