client.Domains
Bu ad alanındaki her yöntem: imzası, parametreleri, döndürdüğü değer ve bir örnek.
Yöntemler
Custom domains attached to the workspace: add and remove them, read the DNS records to publish or have OpenEmail write them through a connected provider, check whether they can receive and send, manage their addresses with their photos, forwarding and password sign-ins, and set the catch-all, the tracking and files domains, the DMARC policy, the sender name and the brand logo.
Domains.ListAsync
List the workspace's domains and their receiving state
Task<Page> ListAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the domains added to the workspace, alphabetically by domain. Domains.ListAllAsync collects every page and Domains.IterateAsync walks them lazily. receiving reports the inbound checks: verified is true once verifiedAt is set, catchAll is the domain's catch all setting, lastCheckedAt is the most recent check and error is the last verification failure.
receiving and sending are independent. A verified domain can receive mail, and that says nothing about whether outbound mail from it is signed. sending.status is the signing state as the last check saw it, one of verified, pending, failed, no_identity or unknown, sending.canSend says whether a send from the domain would be accepted right now, sending.checkedAt dates that verdict, and sending.error carries the last failure. A negative verdict older than a day is treated as unknown rather than as a refusal, so canSend can be true while status is pending.
tracking reports the domain's custom tracking domain, set with Domains.UpdateAsync, and only a tracking.status of active means tracked links and the open pixel in new mail from the domain use its host instead of the default OpenEmail host. storage reports the domain's custom files domain the same way, and only a storage.status of active means the download links for files sent from the domain use its host.
Parametreler
limitint?Page size, from 1 to 100. The server defaults to 25.
cursorstring?The
nextCursorof the previous page. Leave it out for the first page.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A Page of domain objects, with items, hasMore and nextCursor. Each item has id, domain, receiving, sending, tracking, storage, logo, dmarcPolicy, senderName and createdAt.
Örnek
var page = await client.Domains.ListAsync(limit: 100); foreach (var domain in page){ var receiving = domain["receiving"]; if ((bool?)receiving?["verified"] != true) { Console.WriteLine($"{domain["domain"]}: {receiving?["error"]?.ToString() ?? "waiting for DNS"}, checked {receiving?["lastCheckedAt"]?.ToString() ?? "never"}"); }}Notlar
A narrowed key still sees every domain in the workspace, whether it is narrowed by whole domains or by individual addresses.
Addresses, DNS records and the DMARC reading are only on
Domains.GetAsync.Domains.ListAddressesAsyncpages through the addresses on one domain.The cursor is opaque and holds where the last row sat in this order, so a row deleted or edited between pages never breaks the walk: the next page starts at the first row that sorts after it. A cursor this list did not hand out is a 400
invalid_cursor.
Şurada da var
- API
GET /domains- TypeScript
domains.list()- Python
domains.list()- Ruby
domains.list- PHP
domains->list- Go
Domains.List- Java
domains().list- CLI
openemail domains list
Domains.ListAllAsync
Collect every domain into one object
Task<IReadOnlyList<JsonObject>> ListAllAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Walks every page of Domains.ListAsync and returns all domains in one object, alphabetically by domain. One request per page.
Parametreler
limitint?Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?Starts the walk after this cursor instead of the first page.
apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A list of domain objects holding every domain, each shaped like an item of Domains.ListAsync.
Örnek
var domains = await client.Domains.ListAllAsync(limit: 100); Console.WriteLine(domains.Count);Notlar
If any page fails, the exception is thrown and the domains already fetched are discarded.
Şurada da var
- API
GET /domains- TypeScript
domains.listAll()- Python
domains.list_all()- Ruby
domains.list_all- PHP
domains->listAll- Go
Domains.ListAll- Java
domains().listAll
Domains.IterateAsync
Stream the domains one at a time
IAsyncEnumerable<JsonObject> IterateAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns an IAsyncEnumerable<JsonObject> that yields domains one at a time, alphabetically by domain, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the await foreach stops the requests.
Parametreler
limitint?Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?Starts the walk after this cursor instead of the first page.
apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
Döndürür
An IAsyncEnumerable<JsonObject> that yields one domain per step, each shaped like an item of Domains.ListAsync.
Örnek
await foreach (var domain in client.Domains.IterateAsync()){ if ((string?)domain["tracking"]?["status"] == "failed") { Console.WriteLine($"{domain["domain"]}: tracking domain {domain["tracking"]?["host"]} failed, {domain["tracking"]?["error"]}"); }}Notlar
The generator is lazy, so an abandoned loop costs only the pages you consumed.
Şurada da var
- API
GET /domains- TypeScript
domains.iterate()- Python
domains.iterate()- Ruby
domains.iterate- PHP
domains->iterate- Go
Domains.Iterate- Java
domains().iterate
Domains.GetAsync
Read one domain with its addresses, DNS records and DMARC reading
Task<JsonObject> GetAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Returns the same receiving and sending blocks as Domains.ListAsync, plus addresses: every address on the domain as a full lower cased address with its enabled flag. Disabled addresses are listed too. Domains.ListAddressesAsync returns the same addresses with their ids and labels. It also carries the tracking and storage blocks described on Domains.ListAsync, whose record is the CNAME record to add at your DNS provider for the tracking domain and for the files domain.
records is every DNS record the domain uses, each with type, name, value, priority on an MX record, a purpose written to be shown to a person, and status: found when the last check saw it in public DNS, missing when it did not, and null when it has not been checked yet. Publish each one exactly as given, since the values are specific to this domain. dmarc is the domain's DMARC record as public DNS has it, with its stage, any issues, and whether a policy stricter than p=none is safe yet. It is null until the domain is verified.
Reading an unverified domain checks its DNS again when the last check is more than 20 seconds old, so polling Domains.GetAsync is one way to wait for verification. Domains.VerifyAsync checks straight away.
The id must belong to the calling workspace. Another workspace's domain id is a 404, the same as an id that does not exist, and the domain name is not accepted in its place.
Parametreler
idstringZorunluDomain id from
Domains.ListAsync, a UUID.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with the fields of a Domains.ListAsync item plus addresses, records and dmarc. Each entry of addresses is an object with address and enabled, each entry of records an object with type, name, value, priority, purpose and status, and dmarc an object with stage, record, issues, alignmentPossible and caveat, or null.
Örnek
var domain = await client.Domains.GetAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); Console.WriteLine($"{domain["domain"]}{((bool?)domain["sending"]?["canSend"] == true ? " can send" : " cannot send yet")}"); foreach (var record in domain["records"]?.AsArray() ?? []){ Console.WriteLine($"{record?["type"]} {record?["name"]} {record?["value"]}: {record?["status"]?.ToString() ?? "not checked"}");}Notlar
sending.canSendis the value to branch on before a send: when it is false,Emails.SendAsyncfrom this domain is refused with 409domain_not_sendable.A narrowed key still sees every address on the domain, whether it is narrowed by whole domains or by individual addresses.
Şurada da var
- API
GET /domains/{id}- TypeScript
domains.get()- Python
domains.get()- Ruby
domains.get- PHP
domains->get- Go
Domains.Get- Java
domains().get- CLI
openemail domains get
Domains.CreateAsync
Add a domain to the workspace
Task<JsonObject> CreateAsync( IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Adds a domain and returns it with every DNS record to publish, in the same shape as Domains.GetAsync. The first DNS check runs during the call, so the status of each entry in records already says what public DNS answers with.
The domain receives mail once public DNS answers with its MX records and its _openemail-challenge TXT record, and it can send once its signing records are in place. Publish every entry in records exactly as given, since the values are specific to this domain, then call Domains.VerifyAsync or poll Domains.GetAsync until receiving.verified is true.
A new domain starts with its catch-all on and no addresses. Create addresses with Domains.CreateAddressAsync, or turn the catch-all off with Domains.UpdateAsync.
Parametreler
domainstringZorunluA bare domain such as
example.com. It is trimmed, lower cased and converted to its ASCII form, so an internationalised name is stored as punycode.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the new domain with addresses empty, records holding every DNS record to publish, and dmarc null until the domain is verified.
Örnek
try{ var domain = await client.Domains.CreateAsync(new Body { ["domain"] = "example.com" });}catch (OpenEmailApiException error) when (error.IsConflict){ Console.WriteLine($"Not added: {error.Code}");}Notlar
How many domains you can add is set by the plan of the workspace, counted within that workspace. Past it the call is refused with 403
domain_allowance_reached, and the message says which plan includes more.A domain you already added is 409
domain_already_added, one somebody else added is 409domain_claimed, one whose parent or subdomain belongs to somebody else is 409related_domain_owned, and one that belongs to OpenEmail is 409operator_domain. Anything that is not a hostname is 422invalid_parameterondomain.Adding a domain reaches the whole workspace, so a key or app limited to particular addresses or domains is refused with 422
capability_unsupportedondomainAllowlist. Use a key with no address or domain restriction.The SDK does not retry a create after a network failure. A second attempt after a lost response is refused with 409
domain_already_added, which means the first one worked: read the domain withDomains.ListAsync.
Şurada da var
- API
POST /domains- TypeScript
domains.create()- Python
domains.create()- Ruby
domains.create- PHP
domains->create- Go
Domains.Create- Java
domains().create- CLI
openemail domains create
Domains.VerifyAsync
Check a domain's DNS now
Task<JsonObject> VerifyAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Checks the DNS of the domain straight away and returns it in the same shape as Domains.GetAsync. On an unverified domain it looks for the records that verify it, and receiving.verified comes back true when they are found. On a verified domain it checks the signing and return path records again and asks whether mail from the domain can be sent, so sending is fresh.
When the last check ran less than 10 seconds ago, nothing new is checked and the domain comes back as it stands, so calling it faster than that gains nothing. A record published a moment ago can take a few minutes to show up in public DNS.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.GetAsync, as the check left it.
Örnek
var domain = await client.Domains.VerifyAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); Console.WriteLine($"{domain["domain"]} is verified");Notlar
Reading an unverified domain with
Domains.GetAsyncalso checks it again when its last check is more than 20 seconds old, so either call works for polling.Domains.VerifyAsyncneedsdomains:writeandDomains.GetAsyncneeds onlydomains:read.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.A domain id from another workspace is a 404, the same as an id that does not exist.
Retried automatically on network failure and retryable statuses, since a repeated check changes nothing but the time of the check.
Şurada da var
- API
POST /domains/{id}/verify- TypeScript
domains.verify()- Python
domains.verify()- Ruby
domains.verify- PHP
domains->verify- Go
Domains.Verify- Java
domains().verify- CLI
openemail domains verify
Domains.UpdateAsync
Turn the catch-all on or off, set or remove the tracking and files domains, and set the DMARC policy and the sender name
Task<JsonObject> UpdateAsync( string id, IReadOnlyDictionary<string, object?> patch, string? apiKey = null, CancellationToken cancellationToken = default)catchAll true accepts mail to any address on the domain that nobody created, and the address shows up in Domains.ListAddressesAsync 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 and storageHost set the two custom names a domain can carry once it is verified or its _openemail-challenge TXT record is published, each of them a subdomain of it. trackingHost, such as links.example.com, is the name tracked links and the open pixel use. storageHost, such as files.example.com, is the name the download links for files sent from the domain use. All five fields are optional and independent: a field left out is left alone, and for either host null or an empty string removes that name and a string sets it. A patch carrying none of them changes nothing and answers with the domain as it stands. Each value is trimmed and lower cased, and a leading https:// or http://, any path, query or fragment and any trailing dots are stripped.
A new host is validated, saved and checked in the same call, so the response already carries the result of that first check. trackingHost reports into the tracking block and storageHost into storage, and the two blocks carry the same fields. The check asks the host over HTTPS for an answer signed by OpenEmail, on /t/v/<nonce> for a tracking domain and /f/v/<nonce> for a files domain, so the host needs a CNAME record named record.name with the value record.value, with any proxying turned off. That value, also reported as target, is an address prepared for this host alone. When it could not be prepared during the call, record is null, target is an empty string and error says so, and it is finished within a few minutes without another call. Until a check passes, status is pending and new mail keeps using the default OpenEmail host. Once one passes, status is active and new mail from the domain uses the host.
Sending a host the domain already has runs the check again, unless the last check was less than 30 seconds ago, in which case the stored state comes back unchanged. A different host replaces the current one at once, so new mail uses the default host until the new one passes a check. Null or an empty string removes that name, and its block then reports status as none with host and record null.
dmarcPolicy is what the domain's DMARC record tells receivers to do with mail that fails its checks: none only monitors, quarantine sends it to spam and reject refuses it. Inboxes show the domain logo only at quarantine or reject, and where OpenEmail writes the DNS for the domain the record is updated during the call, keeping its other tags such as rua, while elsewhere you publish the DMARC record records lists.
senderName is the name recipients see beside every address on the domain that has no name of its own, such as Acme Support. Mail sent without a name in from goes out under the name of the address, then this one, then the name of the workspace. It is trimmed, and null or a string that is empty once trimmed removes it.
Parametreler
idstringZorunluDomain id from
Domains.ListAsync, a UUID.catchAllboolTrue accepts mail to any address on the domain that nobody created, false refuses it. Leaving the field out leaves the catch-all alone.
trackingHoststringA subdomain of the domain of at most 512 characters, such as
links.example.com. Null or an empty string removes the tracking domain, and leaving the field out leaves it alone.storageHoststringA subdomain of the domain of at most 512 characters, such as
files.example.com. Null or an empty string removes the files domain, and leaving the field out leaves it alone.dmarcPolicystringnone,quarantineorreject, also inOpenEmail\Constants\DomainDmarcPolicies. A policy stricter thannoneneeds mail from the domain to be signed first. Leaving the field out leaves the policy alone.senderNamestringThe name mail from the domain goes out under when the address has no name of its own, at most 120 characters once trimmed, such as
Acme Support. Null or an empty string removes it, and leaving the field out leaves it alone.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.GetAsync, with receiving.catchAll, tracking, storage, dmarcPolicy and senderName as they stand after the call.
Örnek
using OpenEmail.Constants; var domain = await client.Domains.UpdateAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", new Body { ["trackingHost"] = "links.example.com", ["storageHost"] = "files.example.com" }); if ((string?)domain["sending"]?["status"] == "verified"){ await client.Domains.UpdateAsync(domain["id"]!.GetValue<string>(), new Body { ["dmarcPolicy"] = DomainDmarcPolicies.Quarantine });}Notlar
The host is refused with 422
invalid_tracking_host, orinvalid_storage_hostfor the files domain, when it is not a hostname, is not a strict subdomain of the domain, is the return path hostbounce.<domain>, belongs to OpenEmail or is a domain set up to receive mail. A new host on a domain whosereceiving.verifiedis false and whose_openemail-challengeTXT record is not published yet gets 409domain_not_verified. The domain does not have to be receiving mail for a host to be accepted. A host another domain already uses gets 409tracking_host_in_useorstorage_host_in_use, and so does a host already in use for the other feature, since one name cannot be both. AdmarcPolicystricter thannonewhilesending.statusis notverifiedgets 409domain_not_sendable, since unsigned mail from the domain would then go to spam. Every refusal names the field it came from inparam, and a refused field changes nothing. The fields are applied in order,catchAllfirst, thentrackingHost, thenstorageHost, thendmarcPolicy, thensenderName, so a patch carrying more than one can have an earlier change saved before a later field is refused. Send them in separate calls when any of them has to stand on its own.Every call on a domain whose tracking domain is managed by a different OpenEmail server, removal included, gets 409
tracking_host_in_useuntil it is removed on that server. A files domain behaves the same way understorage_host_in_use.A tracking domain and a files domain each apply to every address on the domain, so only a key that holds the whole domain may set one. A key whose
domainAllowlistcontains this domain is allowed through, and any other narrowed key gets 422capability_unsupportedondomainAllowlist. The catch-all, the DMARC policy and the sender name need the whole domain the same way. A body key other thancatchAll,trackingHost,storageHost,dmarcPolicyandsenderNameis a 422unknown_parameter, and acatchAllthat is not a boolean, admarcPolicythat is not one of the three policies, asenderNamethat is neither a string nor null or runs past 120 characters once trimmed, or a host field that is present but is neither a string nor null, or runs past 512 characters, is a 422invalid_parameter. A body carrying none of the fields is not an error: it changes nothing and comes back 200.OpenEmail keeps checking on its own. A host that has not passed a check 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. An active host is checked every 10 minutes, and a failed check on it is retried after 1 minute and then 2. From the third failure in a row the wait starts at 4 minutes and doubles each time, up to an hour.
An active host that fails one or two checks in a row still reads
active, with the reason inerror. It stops being used after the third, or once its last successful check is 2 hours old. New mail then goes back to the default host, andstatusreadsfaileduntil a check passes again.A tracking domain serves only tracking paths and a files domain serves only download paths, and each answers only for mail sent by the workspace that owns it.
Links in mail already sent keep the host they were sent with, and that covers the download link on a file as much as a tracked link. After removing or changing a name, those links work only for as long as the old CNAME record stays in place. Setting a host up again can give it a different
record.value, so publish the one the response reports.Retried automatically on network failure and retryable statuses, since repeating a call that already went through finds the catch-all, the DMARC policy, the sender name and the hosts already set, or already removed, and at most checks a host again.
Şurada da var
- API
PATCH /domains/{id}- TypeScript
domains.update()- Python
domains.update()- Ruby
domains.update- PHP
domains->update- Go
Domains.Update- Java
domains().update- CLI
openemail domains update
Domains.DeleteAsync
Remove a domain from the workspace
Task<JsonObject> DeleteAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Removes the domain. Mail to it stops being accepted and nothing can be sent from it. Every address on it goes with it, their password sign-ins are revoked, its signing key is released, its tracking and files domains are retired, and the domain.deleted webhook fires. Mail already received stays in the mailbox.
Where OpenEmail wrote the DNS for this domain itself, it takes those records back, and any it could not take back are listed in leftBehind for you to remove at your DNS provider. Records you published yourself are never touched, so remove them too once the domain is gone.
There is no undo. Adding the domain again starts it from scratch.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to domain, id, domain, deleted set to true and leftBehind, the DNS records that have to be removed by hand, one line each.
Örnek
try{ var removed = await client.Domains.DeleteAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); foreach (var line in removed["leftBehind"]?.AsArray() ?? []) { Console.WriteLine($"Remove by hand: {line}"); }}catch (OpenEmailApiException error) when (error.IsConflict){ Console.WriteLine($"Kept: {error.Code}");}Notlar
The last domain in a workspace cannot be removed here, because in the app removing it deletes the whole mailbox with it. The call is refused with 409
last_domain. Remove it in the app, where that is confirmed first.A domain that holds reserved account addresses is refused with 409
domain_holds_reserved_addresses.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.An access token acting for a member also needs
workspace:managein that member's role, as removing one in the app does. It is console-only, so no approval can give it to an app, and without it the call is refused with 403insufficient_authority.The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Şurada da var
- API
DELETE /domains/{id}- TypeScript
domains.delete()- Python
domains.delete()- Ruby
domains.delete- PHP
domains->delete- Go
Domains.Delete- Java
domains().delete- CLI
openemail domains delete
Domains.GetLogoAsync
Read the brand logo of a domain and what public DNS publishes for it
Task<JsonObject> GetLogoAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Returns the logo inboxes show next to mail from the domain through BIMI, with its mark certificate and DMARC policy, and asks public DNS what default._bimi.<domain> holds right now: published.ours turns true once the record pointing at the logo is live. For a subdomain, parentDmarc reports the DMARC record of the domain it belongs to, because inboxes show the logo only when its p= and sp= both quarantine or reject at 100 percent.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with url, record, certificate, matchesCertificate and dmarcPolicy, plus published, an object with found, ours and value, and parentDmarc, which is null unless the domain is a subdomain.
Örnek
var logo = await client.Domains.GetLogoAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); Console.WriteLine($"{logo["url"]?.ToString() ?? "No logo"}{((bool?)logo["published"]?["ours"] == true ? ", the BIMI record is live" : ", the BIMI record is not published yet")}"); if (logo["parentDmarc"] is not null && (bool?)logo["parentDmarc"]?["enforced"] != true){ Console.WriteLine($"The DMARC record of {logo["parentDmarc"]?["domain"]} does not enforce yet");}Notlar
Domains.GetAsyncandDomains.ListAsynccarry the sameurl,record,certificateandmatchesCertificatein each domain'slogo, but onlyDomains.GetLogoAsyncasks public DNS what is published.A domain id from another workspace is a 404, the same as an id that does not exist.
Şurada da var
Domains.SetLogoAsync
Upload the brand logo inboxes show for a domain
Task<JsonObject> SetLogoAsync( string id, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Converts the SVG to the SVG Tiny PS format inboxes require, replaces any logo the domain had, and publishes the BIMI record where OpenEmail writes the DNS for the domain. Inboxes show the logo once dmarcPolicy is quarantine or reject, which Domains.UpdateAsync sets, and Gmail also needs a mark certificate from Domains.SetLogoCertificateAsync.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.svgstringZorunluThe logo as SVG markup, up to 1 MB. A file that is SVG Tiny PS already is kept byte for byte, so it stays the same as the copy inside a mark certificate.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the logo as it stands, with url, record, certificate, matchesCertificate, dmarcPolicy, records and logoFromCertificate. records is published once the BIMI record is in place, manual when you publish record yourself, blocked when a record you published is in the way, and busy or failed when calling again may help.
Örnek
using OpenEmail.Constants; var svg = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\"><circle cx=\"32\" cy=\"32\" r=\"30\" fill=\"#4f46e5\"/></svg>"; var logo = await client.Domains.SetLogoAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", new Body { ["svg"] = svg }); if ((string?)logo["records"] == DomainLogoRecordOutcomes.Manual){ Console.WriteLine($"Publish {logo["record"]?["type"]} {logo["record"]?["name"]} {logo["record"]?["value"]}");}else{ Console.WriteLine($"BIMI record: {logo["records"]}");}Notlar
A domain that is not verified is refused with 409
domain_not_verified. Ansvgthat is not SVG, is over 1 MB or uses something inboxes do not draw, such as a bitmap image, a filter or a link to another file, is a 422invalid_parameterwhose message says which.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist. Safe to replay, so the SDK retries it after a network failure.
Şurada da var
Domains.RemoveLogoAsync
Remove the brand logo of a domain
Task<JsonObject> RemoveLogoAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Removes the logo and deletes the stored file, and takes the BIMI record down where OpenEmail writes the DNS for the domain. Elsewhere remove the record yourself. Any mark certificate stays, ready for the next logo.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.SetLogoAsync, with url and record null, and records saying what happened to the BIMI record.
Örnek
var logo = await client.Domains.RemoveLogoAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); Console.WriteLine($"Logo removed, BIMI record: {logo["records"]}");Notlar
A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.Removing a logo from a domain that has none changes nothing, so the SDK retries it after a network failure.
Şurada da var
Domains.SetLogoCertificateAsync
Upload the mark certificate for a domain logo
Task<JsonObject> SetLogoCertificateAsync( string id, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Stores the Verified Mark Certificate (VMC) or Common Mark Certificate (CMC) a certificate authority issued for the domain, replacing any there was, and points the BIMI record at it. Gmail shows the logo only with one and Apple Mail only with a VMC, and when the logo inside the certificate differs from the published one, it becomes the published one and logoFromCertificate is true.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.certificatestringZorunluThe file the certificate authority sent, up to 128 KB: PEM text as it came, which can hold the whole chain, or a DER or PKCS #7 file encoded as base64, which
OpenEmailClient.ToBase64does.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.SetLogoAsync, with certificate, an object with url, mark, expiresAt, domains and issuer, plus matchesCertificate, records and logoFromCertificate.
Örnek
var logo = await client.Domains.SetLogoCertificateAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", new Body { ["certificate"] = Environment.GetEnvironmentVariable("ACME_VMC_PEM") }); Console.WriteLine($"{logo["certificate"]?["mark"]} certificate, valid until {logo["certificate"]?["expiresAt"]}"); if ((bool?)logo["logoFromCertificate"] == true){ Console.WriteLine("The logo inside the certificate is now the published one");}Notlar
A domain that is not verified is refused with 409
domain_not_verified. A file that cannot be read, is over 128 KB, holds no VMC or CMC, was issued for a different domain or has expired is a 422invalid_parameteroncertificatewhose message says which.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist. Safe to replay, so the SDK retries it after a network failure.
Şurada da var
Domains.RemoveLogoCertificateAsync
Remove the mark certificate of a domain logo
Task<JsonObject> RemoveLogoCertificateAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Removes the mark certificate and deletes the stored file, while the logo stays. The BIMI record no longer points at a certificate, so Gmail and Apple Mail stop showing the logo.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.SetLogoAsync, with certificate and matchesCertificate null.
Örnek
var logo = await client.Domains.RemoveLogoCertificateAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); Console.WriteLine($"The certificate is gone, the logo stays at {logo["url"]?.ToString() ?? "nowhere"}");Notlar
A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.Removing a certificate from a domain that has none changes nothing, so the SDK retries it after a network failure.
Şurada da var
Domains.ListAddressesAsync
List one page of the addresses on a domain
Task<Page> ListAddressesAsync( string id, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the addresses on the domain, alphabetically by address, with each one's id, label, enabled and lastReceivedAt. That covers the addresses created by hand or through the API and the ones the catch-all picked up when mail first arrived for them. Disabled addresses are listed. Removed addresses and the catch-all itself are not: the catch-all is receiving.catchAll on the domain.
Domains.ListAllAddressesAsync collects every page and Domains.IterateAddressesAsync walks them lazily.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.limitint?Page size, from 1 to 100. The server defaults to 25.
cursorstring?The
nextCursorof the previous page. Leave it out for the first page.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A Page of address objects, with items, hasMore and nextCursor. Each item is shaped like what Domains.GetAddressAsync returns.
Örnek
var page = await client.Domains.ListAddressesAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", limit: 100); foreach (var address in page){ Console.WriteLine($"{address["address"]}{((bool?)address["enabled"] == true ? "" : ", switched off")} {address["label"]}");}Notlar
A narrowed key still sees every address on the domain, the same as
Domains.GetAsync.A domain id from another workspace is a 404, the same as an id that does not exist.
The cursor is opaque. A cursor this list did not hand out is a 400
invalid_cursor.
Şurada da var
Domains.ListAllAddressesAsync
Collect every address on a domain into one object
Task<IReadOnlyList<JsonObject>> ListAllAddressesAsync( string id, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Walks every page of Domains.ListAddressesAsync and returns all the addresses on the domain in one object, alphabetically by address. One request per page.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.limitint?Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?Starts the walk after this cursor instead of the first page.
apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A list of address objects holding every address on the domain, each shaped like what Domains.GetAddressAsync returns.
Örnek
var addresses = await client.Domains.ListAllAddressesAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); Console.WriteLine(addresses.Count);Notlar
If any page fails, the exception is thrown and the addresses already fetched are discarded.
Şurada da var
Domains.IterateAddressesAsync
Stream the addresses on a domain one at a time
IAsyncEnumerable<JsonObject> IterateAddressesAsync( string id, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns an IAsyncEnumerable<JsonObject> that yields the addresses on the domain one at a time, alphabetically by address, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the await foreach stops the requests.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.limitint?Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?Starts the walk after this cursor instead of the first page.
apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
Döndürür
An IAsyncEnumerable<JsonObject> that yields one address per step, each shaped like what Domains.GetAddressAsync returns.
Örnek
await foreach (var address in client.Domains.IterateAddressesAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")){ Console.WriteLine($"{address["address"]}, last mail {address["lastReceivedAt"]?.ToString() ?? "never"}");}Notlar
The generator is lazy, so an abandoned loop costs only the pages you consumed.
Şurada da var
Domains.CreateAddressAsync
Create an address on a domain
Task<JsonObject> CreateAddressAsync( string id, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Creates an address on the domain, enabled, and returns it. The domain does not have to be verified yet, but the address receives nothing until it is.
When the domain has its catch-all on, the new address starts with the per-address settings of the catch-all, such as its signature and tracking, apart from the privacy settings. They are copied once, not kept in step.
Creating an address that already exists, or one that was removed, is not an error: it comes back enabled, with the label you sent or none, and keeps its id. An address the catch-all picked up becomes one created by hand, so it keeps receiving when the catch-all is turned off.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.localPartstringZorunluThe part in front of the @, 1 to 64 characters once trimmed, lower cased. Letters, digits, the backtick and ! # $ % & ' * + / = ? ^ _ { | } ~ - are allowed, and so are dots between them.
*on its own is how the catch-all is written and is refused.labelstringA name for the address shown in the app, trimmed, up to 120 characters. Leave it out, or send null or an empty string, for none.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the address, shaped like what Domains.GetAddressAsync returns, with its id, address, label and enabled true.
Örnek
var address = await client.Domains.CreateAddressAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", new Body { ["localPart"] = "support", ["label"] = "Support" }); Console.WriteLine($"Created {address["address"]} with id {address["id"]}");Notlar
An address reserved as somebody's account address is refused with 409
address_reservedonlocalPart. Past the workspace limit on addresses the call is refused with 422workspace_limit_reached.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.A domain id from another workspace is a 404, the same as an id that does not exist.
Retried automatically on network failure and retryable statuses, since creating the same address twice leaves one address with the same id.
Şurada da var
Domains.GetAddressAsync
Read one address on a domain
Task<JsonObject> GetAddressAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Returns one address on the domain with its label, enabled, lastReceivedAt and timestamps.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to address, id, domainId, address, localPart, label, photoUrl, enabled, destination, lastReceivedAt, createdAt and updatedAt.
Örnek
var address = await client.Domains.GetAddressAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine($"{address["address"]}{((bool?)address["enabled"] == true ? " takes mail" : " is switched off")}, last mail {address["lastReceivedAt"]?.ToString() ?? "never"}");Notlar
An address id that is not on this domain, or an address that was removed, is a 404
resource_not_found, and so is a domain from another workspace.
Şurada da var
Domains.UpdateAddressAsync
Rename an address, turn it off and on, or choose where its mail goes
Task<JsonObject> UpdateAddressAsync( string id, string addressId, IReadOnlyDictionary<string, object?> patch, string? apiKey = null, CancellationToken cancellationToken = default)Changes the fields you send and leaves the rest alone. label renames the address, and null or an empty string removes the name. enabled false stops the address taking mail: mail to it is refused while the sending server is still connected, so the sender gets a bounce, and nothing can be sent from it. It keeps its mail, its settings and the people who can reach it, so enabled true picks up where it left off. That is the difference from Domains.DeleteAddressAsync.
destination chooses where the mail of the address goes: mailbox keeps a copy here, as an address does by default, and forward only sends it on to the destinations from Domains.AddAddressForwardsAsync, keeping nothing here. forward needs at least one destination that is switched on.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.labelstringA new name, trimmed, up to 120 characters. Null or an empty string removes it.
enabledboolFalse stops the address taking mail, true takes mail again.
destinationdictionarymailboxkeeps a copy of the mail here,forwardonly forwards it. Both are inOpenEmail\Constants\DomainAddressDestinations.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the address as it stands after the change, shaped like what Domains.GetAddressAsync returns.
Örnek
var address = await client.Domains.UpdateAddressAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", new Body { ["label"] = "Old support inbox", ["enabled"] = false }); Console.WriteLine($"{address["address"]}{((bool?)address["enabled"] == true ? " takes mail" : " is switched off")}");Notlar
A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.A body key other than
label,enabledanddestinationis a 422unknown_parameter.["destination"] = "forward"on an address with no destination switched on is refused with 409forward_requiredondestination.Sending
destinationwith an OAuth access token needs a verification code, and is refused with 403step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An access token acting for a member can only change where the mail of an address goes when that member reaches it, or it is refused with 403insufficient_authority. An API key is never asked for a code.Retried automatically on network failure and retryable statuses, since the same patch sent twice leaves the same address.
Şurada da var
Domains.SetAddressPhotoAsync
Upload the photo shown for an address
Task<JsonObject> SetAddressPhotoAsync( string id, string addressId, Stream data, string? contentType = null, string? apiKey = null, CancellationToken cancellationToken = default)Sends the image bytes as the request body, replacing any photo the address had: PNG, JPEG, WebP or GIF up to 5 MB, cropped to a 512 pixel square, stored as JPEG or PNG and shown for the address in OpenEmail in place of the domain logo. The type is read from contentType:, and without it the server refuses the bytes with 422 invalid_image.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.dataStreamZorunluThe image: a readable
Stream.contentTypestring?image/png,image/jpeg,image/webporimage/gif. Required, because aStreamcarries no type of its own.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the address, shaped like what Domains.GetAddressAsync returns, with the new photoUrl.
Örnek
await using var avatar = File.OpenRead("avatar.png"); var address = await client.Domains.SetAddressPhotoAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", avatar); Console.WriteLine($"{address["address"]} now shows {address["photoUrl"]}");Notlar
A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.A busy image service answers 503
image_busyand a failed save 502image_not_stored, which the SDK retries like any other retryable status.
Şurada da var
Domains.RemoveAddressPhotoAsync
Remove the photo of an address
Task<JsonObject> RemoveAddressPhotoAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Removes the photo of the address and deletes the stored image, so the domain logo is shown for it again.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the address, shaped like what Domains.GetAddressAsync returns, with photoUrl null.
Örnek
var address = await client.Domains.RemoveAddressPhotoAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine($"{address["address"]} shows {address["photoUrl"]?.ToString() ?? "the domain logo"}");Notlar
A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.Removing a photo from an address that has none changes nothing, so the SDK retries it after a network failure.
Şurada da var
Domains.DeleteAddressAsync
Remove an address from a domain
Task<JsonObject> DeleteAddressAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)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 Domains.CreateAddressAsync brings it back with the same id, enabled, but without its old settings or access.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to address, id, address and deleted set to true.
Örnek
var removed = await client.Domains.DeleteAddressAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine($"Removed {removed["address"]}");Notlar
A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.An access token acting for a member also needs
workspace:managein that member's role, as removing one in the app does. It is console-only, so no approval can give it to an app, and without it the call is refused with 403insufficient_authority.The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Şurada da var
Domains.ListAddressForwardsAsync
List where the mail of an address is forwarded
Task<JsonObject> ListAddressForwardsAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Returns every place the mail of the address is forwarded to, oldest first, as the Forwarding section of the address in the app lists them. Each destination says whether it is switched on (enabled) and where it stands (status): only a live destination, one that confirmed by email that it wants this mail, receives anything.
destination on the list says whether the address also keeps a copy of its mail here (mailbox) or only forwards it (forward), and max is how many destinations one address may have.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with address, destination, max and the destinations in data, a list of objects each with id, email, enabled, status, confirmedAt, askedAt, lastRelayAt, lastError, failures and createdAt.
Örnek
using OpenEmail.Constants; var forwards = await client.Domains.ListAddressForwardsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine($"{forwards["address"]} goes to {forwards["destination"]}, {forwards["data"]?.AsArray().Count} of {forwards["max"]} destinations used"); foreach (var forward in forwards["data"]?.AsArray() ?? []){ Console.WriteLine($" {forward?["email"]} {forward?["status"]}{((string?)forward?["status"] == AddressForwardStatuses.Pending ? ", waiting for confirmation" : "")}");}Notlar
An address id that is not on this domain, or an address that was removed, is a 404
resource_not_found, and so is a domain from another workspace.A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's
MaxRetries.
Şurada da var
Domains.AddAddressForwardsAsync
Forward the mail of an address to more places
Task<JsonObject> AddAddressForwardsAsync( string id, string addressId, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Adds places the mail of the address goes to, as adding a destination in the app does. Each new destination is sent an email asking it to confirm, and receives nothing until it does, so it comes back pending and turns live once its owner confirms.
An address hosted here, one already on the list, one that would make a loop, one past the limit of 10 and one that refused mail from this workspace before are not added. Each is named in skipped with the reason, and the rest are still added.
The address keeps a copy of its mail here as before. To stop keeping one, set destination to forward with Domains.UpdateAddressAsync once a destination is switched on.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.emailsIEnumerable<string>ZorunluThe addresses to forward to, 1 to 10 of them. Each is trimmed and lowercased.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with the destinations added in added, and every address that was not, with the reason, in skipped.
Örnek
var result = await client.Domains.AddAddressForwardsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", new Body { ["emails"] = new[] { "[email protected]", "[email protected]" } }); foreach (var forward in result["added"]?.AsArray() ?? []){ Console.WriteLine($"Asked {forward?["email"]} to confirm");} foreach (var skipped in result["skipped"]?.AsArray() ?? []){ Console.WriteLine($"Skipped {skipped?["email"]}: {skipped?["reason"]}");}Notlar
An address that is switched off is refused with 409
address_disabled. Switch it on withDomains.UpdateAddressAsyncfirst.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist. An access token acting for a member can only change the forwarding of an address that member reaches, or it is refused with 403insufficient_authority.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried automatically by the SDK, since a lost attempt may already have asked a destination to confirm.
Şurada da var
Domains.UpdateAddressForwardAsync
Pause a forwarding destination or switch it back on
Task<JsonObject> UpdateAddressForwardAsync( string id, string addressId, string forwardId, IReadOnlyDictionary<string, object?> patch, string? apiKey = null, CancellationToken cancellationToken = default)enabled false pauses the destination: nothing is forwarded to it until it is switched on again. It keeps its confirmation, so switching it back on needs no new one, and switching it on clears the failures recorded against it.
When the last destination that is on is paused, the address goes back to keeping its mail here. destination in the result says where the mail of the address goes now.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.forwardIdstringZorunluA destination id from
Domains.ListAddressForwardsAsyncorDomains.AddAddressForwardsAsync. It has to be a destination of the address named byaddressId.enabledboolZorunluFalse pauses the destination, true switches it back on.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject for the destination as it is now, with id, email, enabled, status and destination for the address.
Örnek
var forward = await client.Domains.UpdateAddressForwardAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b", new Body { ["enabled"] = false }); Console.WriteLine($"{forward["email"]} is {forward["status"]}, the mail of the address now goes to {forward["destination"]}");Notlar
A destination id that is not on this address is a 404
resource_not_found.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist. An access token acting for a member can only change the forwarding of an address that member reaches, or it is refused with 403insufficient_authority.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Retried automatically on network failure, since the same patch sent twice leaves the same destination.
Şurada da var
- API
PATCH /domains/{id}/addresses/{addressId}/forwards/{forwardId}- TypeScript
domains.updateAddressForward()- Python
domains.update_address_forward()- Ruby
domains.update_address_forward- PHP
domains->updateAddressForward- Go
Domains.UpdateAddressForward- Java
domains().updateAddressForward- CLI
openemail domains update-address-forward
Domains.DeleteAddressForwardAsync
Stop forwarding to a destination
Task<JsonObject> DeleteAddressForwardAsync( string id, string addressId, string forwardId, string? apiKey = null, CancellationToken cancellationToken = default)Removes the destination, so nothing more is forwarded to it. When it was the last destination that was on, the address goes back to keeping its mail here, and destination in the result says where the mail of the address goes now.
To stop forwarding for a while instead, pause the destination with Domains.UpdateAddressForwardAsync, which keeps its confirmation.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.forwardIdstringZorunluA destination id from
Domains.ListAddressForwardsAsyncorDomains.AddAddressForwardsAsync. It has to be a destination of the address named byaddressId.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to address_forward, id, addressId, email, deleted set to true and destination.
Örnek
var removed = await client.Domains.DeleteAddressForwardAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"); Console.WriteLine($"Stopped forwarding to {removed["email"]}, the mail now goes to {removed["destination"]}");Notlar
A destination id that is not on this address is a 404
resource_not_found.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist. An access token acting for a member can only change the forwarding of an address that member reaches, or it is refused with 403insufficient_authority.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried by the SDK. Repeating a delete that succeeded is a 404.
Şurada da var
- API
DELETE /domains/{id}/addresses/{addressId}/forwards/{forwardId}- TypeScript
domains.deleteAddressForward()- Python
domains.delete_address_forward()- Ruby
domains.delete_address_forward- PHP
domains->deleteAddressForward- Go
Domains.DeleteAddressForward- Java
domains().deleteAddressForward- CLI
openemail domains delete-address-forward
Domains.ResendAddressForwardConsentAsync
Ask a forwarding destination to confirm again
Task<JsonObject> ResendAddressForwardConsentAsync( string id, string addressId, string forwardId, string? apiKey = null, CancellationToken cancellationToken = default)Sends the confirmation email to the destination once more, for when the first one was lost or ignored. status says what became of the request: sent, already-confirmed when the destination has confirmed and needs nothing, too-soon when the last email went out moments ago, revoked when the destination refused mail from this workspace, and send-failed when the email could not be sent.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.forwardIdstringZorunluA destination id from
Domains.ListAddressForwardsAsyncorDomains.AddAddressForwardsAsync. It has to be a destination of the address named byaddressId.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with the destination id, addressId, email and the status of the request.
Örnek
var consent = await client.Domains.ResendAddressForwardConsentAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"); Console.WriteLine(consent.ToJsonString());Notlar
A destination id that is not on this address is a 404
resource_not_found.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist. An access token acting for a member can only change the forwarding of an address that member reaches, or it is refused with 403insufficient_authority.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried automatically by the SDK, since every attempt can send an email.
Şurada da var
- API
POST /domains/{id}/addresses/{addressId}/forwards/{forwardId}/resend- TypeScript
domains.resendAddressForwardConsent()- Python
domains.resend_address_forward_consent()- Ruby
domains.resend_address_forward_consent- PHP
domains->resendAddressForwardConsent- Go
Domains.ResendAddressForwardConsent- Java
domains().resendAddressForwardConsent- CLI
openemail domains resend-address-forward-consent
Domains.ListAddressMembersAsync
List who can reach an address
Task<JsonObject> ListAddressMembersAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Returns everybody who can read the mail of the address and how each one reaches it, in via: owner for the owner of the workspace, every-address for a role that reaches every address, whole-domain for a grant of the whole domain named in viaDomain, and direct for a grant of the address itself. Each person appears once.
access is member for somebody who reads and sends from the address and viewer for somebody who only reads it. removable is true for a grant of the address itself, which Members.RevokeAddressAsync takes back. The others come from the role or a domain grant, and change there.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with the people in data, a list of objects each with userId, email, name, image, access, via, viaDomain and removable.
Örnek
var members = await client.Domains.ListAddressMembersAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine(members.ToJsonString());Notlar
An address id that is not on this domain, or an address that was removed, is a 404
resource_not_found, and so is a domain from another workspace.A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's
MaxRetries.
Şurada da var
Domains.GetAddressLoginAsync
Read the password sign-in of an address
Task<JsonObject> GetAddressLoginAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Says whether the address has a password of its own, which lets somebody sign in to OpenEmail as that address alone and read and send only its mail. login is null when it has none, and otherwise says who set the password and when, and when it was last used to sign in.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with addressId, address and login, which is null when the address has no password and otherwise an object with userId, name, createdAt, createdBy, passwordSetAt, passwordSetBy and lastSignedInAt.
Örnek
var result = await client.Domains.GetAddressLoginAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); var login = result["login"]; if (login is null){ Console.WriteLine($"{result["address"]} has no password sign-in");}else{ Console.WriteLine($"Password set by {login["passwordSetBy"]} at {login["passwordSetAt"]}, last sign-in {login["lastSignedInAt"]?.ToString() ?? "never"}");}Notlar
It needs
members:write, the scope that sets a password, as the app does, rather than a read scope.An address id that is not on this domain, or an address that was removed, is a 404
resource_not_found, and so is a domain from another workspace.A key limited to particular addresses or domains is refused with 422
capability_unsupported. An access token acting for a member can only reach the sign-in of an address that member reaches, or it is refused with 403insufficient_authority.A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's
MaxRetries.
Şurada da var
Domains.SetAddressLoginAsync
Give an address a password, or replace it
Task<JsonObject> SetAddressLoginAsync( string id, string addressId, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Sets the password somebody uses to sign in to OpenEmail as this address alone. Whoever holds it reads and sends only the mail of the address and reaches nothing else in the workspace. OpenEmail sends the password to nobody, so hand it over yourself.
Calling it again replaces the password, signs out everybody who signed in with the old one and removes the forwarding destinations they added. created says whether the sign-in is new.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.passwordstringZorunluAt least 8 characters, with a lowercase letter, an uppercase letter, a number and a special character.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.GetAddressLoginAsync, as it stands after the change, with created.
Örnek
var password = "Aa1!" + Guid.NewGuid().ToString("N")[..16]; var login = await client.Domains.SetAddressLoginAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", new Body{ ["password"] = password,}); Console.WriteLine($"{((bool?)login["created"] == true ? "New sign-in for " : "Password replaced for ")}{login["address"]}");Console.WriteLine($"Hand this password over yourself: {password}");Notlar
A password that misses a rule is a 422
invalid_parameteronpassword. An address an OpenEmail account already signs in as is refused with 409account_exists, so invite that account to the workspace instead, and an address that is switched off is refused with 409address_unavailable.The first password on a workspace whose plan has no team access is refused with 403
plan_required.A key or an access token has to hold every scope a sign-in for one address may use, or it is refused with 403
insufficient_authority. A key limited to particular addresses or domains is refused with 422capability_unsupported, and an access token acting for a member can only set the password of an address that member reaches withmemberaccess.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried automatically by the SDK.
Şurada da var
Domains.DeleteAddressLoginAsync
Remove the password sign-in of an address
Task<JsonObject> DeleteAddressLoginAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Takes the password away and signs out everybody who signed in with it. The address, its mail and the people who reach it otherwise stay as they are, and the forwarding destinations added by whoever signed in as the address are removed with it.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to address_login, addressId, address and deleted set to true.
Örnek
try{ var removed = await client.Domains.DeleteAddressLoginAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine($"Nobody can sign in as {removed["address"]} with a password now");}catch (OpenEmailApiException error) when (error.IsNotFound){ Console.WriteLine("The address had no password");}Notlar
An address with no password is a 404.
A key limited to particular addresses or domains is refused with 422
capability_unsupported. An access token acting for a member can only reach the sign-in of an address that member reaches, or it is refused with 403insufficient_authority.Not retried by the SDK. Repeating a delete that succeeded is a 404.
Şurada da var
Domains.GetMailAppSettingsAsync
Read the mail app settings of an address
Task<JsonObject> GetMailAppSettingsAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Returns what to enter in Apple Mail, Gmail, Outlook, Thunderbird or any other mail app to add the address to it: the IMAP, SMTP and POP3 servers, each with its host, port and security, and the username to sign in with, which is the address itself. Every server encrypts the connection from the first byte, so security is always ssl-tls.
caldav is the server that puts the calendar of the address into Apple Calendar, Thunderbird, DAVx5 on Android or any other CalDAV app, and carddav the one that puts the contacts of the workspace into Apple Contacts or any other CardDAV app. Each has a url to enter, with the same username and password, a principalUrl for apps that ask for the account address on the server, and host, port and security like the others.
protocols says which of these connections the address accepts, as true or false for imap, smtp, pop3, caldav and carddav. Domains.UpdateMailAppSettingsAsync changes them.
The password is an app password of the address, such as one Domains.CreateAppPasswordAsync makes, or the password Domains.SetAddressLoginAsync set when the address has a sign-in of its own without two-factor.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to mail_app_settings, address, username, imap, smtp and pop3, each an object with host, port and security, caldav and carddav with the same three, their url and principalUrl, and protocols.
Örnek
var settings = await client.Domains.GetMailAppSettingsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine($"Sign in as {settings["username"]}");Notlar
An address id that is not on this domain, or an address that was removed, is a 404
resource_not_found, and so is a domain from another workspace. An access token acting for a member gets the same 404 for an address that member cannot read.A key or an access token limited to particular addresses or domains reads only the addresses it is limited to, and any other address is a 404
resource_not_found.A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's
MaxRetries.
Şurada da var
Domains.UpdateMailAppSettingsAsync
Turn mail app connections on or off for an address
Task<JsonObject> UpdateMailAppSettingsAsync( string id, string addressId, IReadOnlyDictionary<string, object?> patch, string? apiKey = null, CancellationToken cancellationToken = default)Switches each kind of connection the address accepts on or off: imap, smtp and pop3 for mail, caldav for its calendar and carddav for contacts. Send only the ones to change, and the rest stay as they are. Every kind is on until it is switched off.
A switched-off kind refuses every sign-in to it, whatever the password, with a message that says it is turned off. Mail apps and calendar or contacts apps that are already connected over it are signed out within minutes. App passwords stay as they are, so switching a kind back on lets them in again.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.imapboolIMAP, which keeps folders and read state in step with OpenEmail.
smtpboolSMTP, for sending from a mail app.
pop3boolPOP3, for apps that only download the inbox.
caldavboolCalDAV, which puts the calendar of the address into calendar apps.
carddavboolCardDAV, which puts the contacts of the workspace into contacts apps.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject, the settings as Domains.GetMailAppSettingsAsync returns them, with protocols as the switches now stand.
Örnek
var settings = await client.Domains.UpdateMailAppSettingsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", new Body { ["pop3"] = false }); Console.WriteLine(settings.ToJsonString());Notlar
Only the workspace owner, or someone whose role manages domains, may change the switches. An access token acting for anyone else is refused with 403
insufficient_authority. An API key acts for the workspace owner.An address id that is not on this domain is a 404
resource_not_found. A key or an access token limited to particular addresses or domains changes only the addresses it is limited to, and any other address is a 404resource_not_found.An unknown field is refused with 422
unknown_parameter, and a value that is not a boolean with 422invalid_parameter.Retried automatically on network failure, since the same patch sent twice leaves the same switches.
Şurada da var
- API
PATCH /domains/{id}/addresses/{addressId}/mail-apps- TypeScript
domains.updateMailAppSettings()- Python
domains.update_mail_app_settings()- Ruby
domains.update_mail_app_settings- PHP
domains->updateMailAppSettings- Go
Domains.UpdateMailAppSettings- Java
domains().updateMailAppSettings- CLI
openemail domains update-mail-app-settings
Domains.ListAppPasswordsAsync
List the app passwords of an address
Task<JsonObject> ListAppPasswordsAsync( string id, string addressId, string? apiKey = null, CancellationToken cancellationToken = default)Returns every app password a mail app can sign in to the address with, newest first. Each one has the name it was given, last4, the last four letters of the password, to tell them apart, owner, the person it signs in as, and origin, which says where it was made: settings in the app, api through Domains.CreateAppPasswordAsync, and setup-link by opening an emailed setup link, such as one Domains.SendMailAppSetupAsync sends.
lastUsedAt and lastUsedProtocol say when an app last signed in with it and over which of imap, smtp, pop3, caldav and carddav, and lastUsedClient names the mail app when it named itself. The passwords themselves are shown only when they are made, and revoked ones are left out.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with the app passwords in data, newest first, a list of objects each with object set to app_password, id, name, last4, origin, owner, an object with id, name and email, createdAt, lastUsedAt, lastUsedProtocol and lastUsedClient. lastUsedAt and lastUsedProtocol are null until an app signs in with it.
Örnek
var passwords = await client.Domains.ListAppPasswordsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70"); Console.WriteLine(passwords.ToJsonString());Notlar
It needs
members:write, the scope that makes and revokes app passwords, as the app does, rather than a read scope.An address id that is not on this domain, or an address that was removed, is a 404
resource_not_found, and so is a domain from another workspace.A key or an access token limited to particular addresses or domains is refused with 422
capability_unsupported, and so is an app a member connected, because its access token is always limited to the addresses that member reaches.A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's
MaxRetries.
Şurada da var
Domains.CreateAppPasswordAsync
Create an app password for an address
Task<JsonObject> CreateAppPasswordAsync( string id, string addressId, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Makes a password a mail app signs in to the address with, using the address as the username, and returns it in password with the server settings in servers. That is the only time the password is shown, so hand it over or store it then.
The password signs in as the caller for this address alone: an API key makes it for the workspace owner, and an access token for the person who connected the app. A mail app using it reaches the mail of the address with what that person may do there, and nothing else in the workspace. It is 16 letters in four groups joined by dashes, and the dashes, or spaces in their place, can be left out when it is typed.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.namestringZorunluWhat to call the password, such as the device it is for, 1 to 64 characters. It is trimmed.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject shaped like an entry of Domains.ListAppPasswordsAsync, with origin set to api, plus password, shown this once, servers, the same object as Domains.GetMailAppSettingsAsync returns, and appleProfile, an Apple configuration profile with the password inside. Saved as a .mobileconfig file and opened on an iPhone, iPad or Mac, the profile adds the address to Mail and its calendar and contacts to Calendar and Contacts in one step, for the connections the address accepts. It holds the password, so keep it like one.
Örnek
var created = await client.Domains.CreateAppPasswordAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", new Body { ["name"] = "Front desk iPad" }); var servers = created["servers"]; Console.WriteLine($"Sign in as {servers?["username"]} with {created["password"]}");Console.WriteLine($"IMAP {servers?["imap"]?["host"]}:{servers?["imap"]?["port"]}, SMTP {servers?["smtp"]?["host"]}:{servers?["smtp"]?["port"]}");Notlar
One person can hold 20 app passwords for one address, and the 21st is refused with 422
app_password_limit_reached, so revoke one withDomains.DeleteAppPasswordAsyncfirst. An address that only forwards its mail, or is switched off, has no mailbox for a mail app to open and is refused with 422address_has_no_mailbox.A key or an access token limited to particular addresses or domains is refused with 422
capability_unsupported, and so is an app a member connected, because its access token is always limited to the addresses that member reaches.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried automatically by the SDK, since a lost attempt may already have made a password. The success status is 201.
Şurada da var
Domains.UpdateAppPasswordAsync
Rename an app password
Task<JsonObject> UpdateAppPasswordAsync( string id, string addressId, string passwordId, IReadOnlyDictionary<string, object?> patch, string? apiKey = null, CancellationToken cancellationToken = default)Changes the name shown for the app password, such as when the device it is for changes hands. The password itself stays the same, and a mail app signed in with it stays signed in.
A person renames the app passwords they hold. The workspace owner, and someone whose role manages members, rename anyone's.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.passwordIdstringZorunluAn app password id from
Domains.ListAppPasswordsAsyncorDomains.CreateAppPasswordAsync. It has to be an app password of the address named byaddressId.namestringZorunluThe new name, 1 to 64 characters. It is trimmed.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject shaped like an entry of Domains.ListAppPasswordsAsync, with the new name.
Örnek
var password = await client.Domains.UpdateAppPasswordAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", "map_3f9a1c7e5b2d4f6a8c0e1b3d", new Body { ["name"] = "Reception iPad" }); Console.WriteLine($"{password["name"]} (ending {password["last4"]})");Notlar
An app password id that is not on this address, one already revoked, or one held by someone else when the caller cannot manage members, is a 404
resource_not_found.A key or an access token limited to particular addresses or domains is refused with 422
capability_unsupported, and so is an app a member connected, because its access token is always limited to the addresses that member reaches.Retried automatically on network failure, since the same name sent twice leaves the same password.
Şurada da var
- API
PATCH /domains/{id}/addresses/{addressId}/app-passwords/{passwordId}- TypeScript
domains.updateAppPassword()- Python
domains.update_app_password()- Ruby
domains.update_app_password- PHP
domains->updateAppPassword- Go
Domains.UpdateAppPassword- Java
domains().updateAppPassword- CLI
openemail domains update-app-password
Domains.DeleteAppPasswordAsync
Revoke an app password
Task<JsonObject> DeleteAppPasswordAsync( string id, string addressId, string passwordId, string? apiKey = null, CancellationToken cancellationToken = default)Revokes the app password, so no mail app can sign in with it again, and a mail app that is signed in with it is signed out within minutes. The address, its mail and its other app passwords stay as they are.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.passwordIdstringZorunluAn app password id from
Domains.ListAppPasswordsAsyncorDomains.CreateAppPasswordAsync. It has to be an app password of the address named byaddressId.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to app_password, id and deleted set to true.
Örnek
try{ var revoked = await client.Domains.DeleteAppPasswordAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", "map_3f9a1c7e5b2d4f6a8c0e1b3d"); Console.WriteLine($"Revoked {revoked["id"]}, so no mail app can sign in with it");}catch (OpenEmailApiException error) when (error.IsNotFound){ Console.WriteLine("That app password was already revoked");}Notlar
An app password id that is not on this address, or one already revoked, is a 404
resource_not_found.A key or an access token limited to particular addresses or domains is refused with 422
capability_unsupported, and so is an app a member connected, because its access token is always limited to the addresses that member reaches.Not retried by the SDK. Repeating a delete that succeeded is a 404.
Şurada da var
- API
DELETE /domains/{id}/addresses/{addressId}/app-passwords/{passwordId}- TypeScript
domains.deleteAppPassword()- Python
domains.delete_app_password()- Ruby
domains.delete_app_password- PHP
domains->deleteAppPassword- Go
Domains.DeleteAppPassword- Java
domains().deleteAppPassword- CLI
openemail domains delete-app-password
Domains.SendMailAppSetupAsync
Email a mail app setup link for an address
Task<JsonObject> SendMailAppSetupAsync( string id, string addressId, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Emails the recipient a link that sets the address up in a mail app. Opening it makes an app password named after the recipient, shows it once with the server settings, and offers a profile that sets up an Apple device in one step. The link works once and expires in three days, at expiresAt.
The app password it makes signs in as the caller, as one from Domains.CreateAppPasswordAsync does: an API key makes it for the workspace owner, and an access token for the person who connected the app. It then appears in Domains.ListAppPasswordsAsync with origin set to setup-link.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.addressIdstringZorunluAddress id from
Domains.ListAddressesAsyncorDomains.CreateAddressAsync, a UUID. It has to be an address on the domain named byid.recipientstringZorunluThe email address to send the link to, such as the person who will use the mail app. It is trimmed and lowercased.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with object set to mail_app_setup, address, recipient and expiresAt, when the link stops working.
Örnek
var setup = await client.Domains.SendMailAppSetupAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70", new Body { ["recipient"] = "[email protected]" }); Console.WriteLine($"Sent {setup["recipient"]} a link for {setup["address"]}, good until {setup["expiresAt"]}");Notlar
When the email cannot be sent the call is a 503
setup_email_not_sentand nothing is made, so it is safe to call again. An address that only forwards its mail, or is switched off, has no mailbox for a mail app to open and is refused with 422address_has_no_mailbox. A workspace can email 50 setup links a day, and past that the call is a 429setup_email_rate_limited.A key or an access token limited to particular addresses or domains is refused with 422
capability_unsupported, and so is an app a member connected, because its access token is always limited to the addresses that member reaches. Only the workspace owner, or someone whose role holdsmembers:write, can send a link, and anyone else is refused with 403insufficient_authority.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried automatically by the SDK, since every attempt can send an email.
Şurada da var
Domains.GetDnsAsync
Read how the DNS of a domain is set up
Task<JsonObject> GetDnsAsync( string id, bool? refresh = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns whether OpenEmail writes the records of the domain itself (managing), through which connection and zone, where each kind of record stands in steps, and the records left behind to delete by hand.
zone says which connected zone answers for the domain: one is resolved, several are ambiguous and need Domains.SetDnsZoneAsync, none holds it, with the reason, or the connections could not be asked (unusable). The answer is kept for a few minutes, and refresh: asks the providers again.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.refreshbool?True asks the providers again which zone answers for the domain.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with domainId, domain, managing, connectionId, connection, zoneId, zoneName, state, steps, leftovers, error, syncedAt and zone, whose kind is one of the four answers above and whose candidates are the zones to choose from.
Örnek
var dns = await client.Domains.GetDnsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", refresh: true); Console.WriteLine(dns.ToJsonString());Notlar
A domain id that is not in this workspace is a 404
resource_not_found.A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's
MaxRetries.
Şurada da var
- API
GET /domains/{id}/dns- TypeScript
domains.getDns()- Python
domains.get_dns()- Ruby
domains.get_dns- PHP
domains->getDns- Go
Domains.GetDNS- Java
domains().getDns- CLI
openemail domains get-dns
Domains.SetDnsZoneAsync
Choose the zone a domain is set up through
Task<JsonObject> SetDnsZoneAsync( string id, IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Attaches the domain to a zone of a connection, when several connected zones could answer for it. The zone has to cover the domain, be active at the provider and take a test record. Nothing is written yet: call Domains.SyncDnsAsync to write the records.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.connectionIdstringZorunluThe connection that holds the zone, from
DnsConnections.ListAsync.zoneIdstringZorunluThe zone, as the
candidatesinzoneofDomains.GetDnsAsynclist it.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
The same object as Domains.GetDnsAsync, as it stands after the change.
Örnek
var dns = await client.Domains.GetDnsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", refresh: true); if (dns["zone"]?["candidates"]?.AsArray().FirstOrDefault() is { } candidate){ var attached = await client.Domains.SetDnsZoneAsync(dns["domainId"]!.GetValue<string>(), new Body { ["connectionId"] = candidate["connectionId"], ["zoneId"] = candidate["zone"]?["id"], }); Console.WriteLine($"{attached["domain"]} is attached to {attached["zoneName"]}");}Notlar
A zone that does not cover the domain is a 422
invalid_parameteronzoneId. A domain already set up through another zone is refused with 409dns_zone_conflict, a zone that is not active or refuses the test record with 409dns_zone_unusable, and a connection that was disconnected with 409dns_connection_unusable.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried by the SDK.
Şurada da var
Domains.SyncDnsAsync
Write the DNS records of a domain
Task<JsonObject> SyncDnsAsync( string id, IReadOnlyDictionary<string, object?>? body = null, string? apiKey = null, CancellationToken cancellationToken = default)Writes or repairs every record the domain needs through the connected zone that answers for it, as Sync does in the app. When exactly one zone answers it is attached first, and attached says so. With purpose, only that kind of record is written. A domain that was waiting for its records is verified once they are in place.
When no single zone answers, nothing is written: outcome is refused, message says why and zone shows the zones to choose from with Domains.SetDnsZoneAsync.
Parametreler
idstringZorunluDomain id from
Domains.ListAsyncorDomains.CreateAsync, a UUID.purposedictionaryOnly this kind of record:
dmarc,tracking,storage,bimiorapp-host, also inOpenEmail\Constants\DnsSyncPurposes.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Döndürür
A JsonObject with outcome, message, attached, the provision that ran and the DNS setup as it is now in dns, shaped like what Domains.GetDnsAsync returns.
Örnek
using OpenEmail.Constants; var sync = await client.Domains.SyncDnsAsync("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f"); if ((string?)sync["outcome"] == DnsSyncOutcomes.Refused){ Console.WriteLine($"Nothing written: {sync["message"]}");}else{ foreach (var record in sync["provision"]?["written"]?.AsArray() ?? []) { Console.WriteLine($"{record?["mode"]} {record?["type"]} {record?["name"]}"); }}Notlar
A sync already running on the domain is refused with 409
dns_busy. A provider that refuses the request is a 502dns_provider_error.A key limited to particular addresses or domains has to hold this whole domain in its
domainAllowlist, or the call is refused with 422capability_unsupportedondomainAllowlist.An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.IsStepUpRequiredon the error says so. An API key is never asked for a code.Not retried by the SDK.