client.Addresses
Каждый метод этого пространства имён: его сигнатура, параметры, что он возвращает, и пример.
Методы
Which addresses and domains the key may send from.
Addresses.ListAsync
List the addresses and domains this key may send as
Task<AddressBookPage> ListAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Answers the question behind an unexplained 403 from_address_forbidden: which addresses this key may put in from. It returns one page of the addresses created on the workspace's domains, alphabetically, each with a canSend verdict for this key, plus the domains themselves. ListAllAsync collects every page into one book and IterateAsync walks the addresses lazily.
unrestricted is true when the key is narrowed by nothing, in which case the API accepts any local-part on the workspace's domains, including ones nobody has created. A key can be narrowed by whole domains, by individual addresses, or by both, and any of those makes unrestricted false. canSend is then true only for an enabled address the key covers, either because its domain is one of the whole domains the key holds or because the address itself is on its address list. A disabled address always reports canSend false.
The SDK reshapes the wire envelope: the server's data object arrives as addresses, so the result is a single AddressBookPage rather than a list.
Параметры
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?Reports on this key instead of the one the client was built with.
cancellationTokenCancellationTokenCancels the request.
Возвращает
An AddressBookPage with unrestricted, hasMore, nextCursor, addresses (objects with address, enabled and canSend) and domains (objects with domain, receivingVerified, sendingVerified and catchAll). Looping over it or counting it goes through addresses.
Пример
var page = await client.Addresses.ListAsync(); Console.WriteLine($"{(page.Unrestricted == true ? "Any address on these domains" : "Only the addresses marked")}"); foreach (var entry in page){ if ((bool?)entry["canSend"] == true) { Console.WriteLine($"{entry["address"]}"); }} foreach (var domain in page.Domains){ Console.WriteLine($"{domain["domain"]}{((bool?)domain["sendingVerified"] == true ? "" : " (cannot sign yet)")}");}Примечания
It needs
emails:send, not a read scope, because it describes what a send would accept.An app a member connected always reports
unrestricted: false, because its access token is held to what that member reaches: the addresses and domains they were granted, or every domain of the workspace when their role holdsaddresses:all. That is worked out again on every call, so a domain added later appears on the next one.canSendis false when the address is disabled, when the key's allowlists leave it out, or when the domain cannot sign yet.sendingVerifiedon each domain is that last fact on its own, so a domain that is verified for receiving and not yet for sending showsreceivingVerified: true, sendingVerified: false.Only created addresses appear in
addresses. An allowlisted address with no mailbox behind it can still be sent from without ever showing up here, and a key that holds a whole domain can send as any local-part on it, including ones created after the key was.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.
Также доступно в
- API
GET /addresses- TypeScript
addresses.list()- Python
addresses.list()- Ruby
addresses.list- PHP
addresses->list- Go
Addresses.List- Java
addresses().list- CLI
openemail addresses list
Addresses.ListAllAsync
Collect every address this key may see into one book
Task<AddressBook> ListAllAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Walks every page of ListAsync and returns one AddressBook holding all addresses, alphabetically, with unrestricted and domains as the last page reported them. One request per page.
Параметры
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?Reports on this key instead of the one the client was built with.
cancellationTokenCancellationTokenCancels the request.
Возвращает
An AddressBook with unrestricted, every address in addresses, and domains. Looping over it or counting it goes through addresses.
Пример
var book = await client.Addresses.ListAllAsync(limit: 100); Console.WriteLine(book.Count);Примечания
If any page fails the call throws and the addresses already fetched are discarded.
Также доступно в
- API
GET /addresses- TypeScript
addresses.listAll()- Python
addresses.list_all()- Ruby
addresses.list_all- PHP
addresses->listAll- Go
Addresses.ListAll- Java
addresses().listAll
Addresses.IterateAsync
Stream the addresses 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 addresses one at a time, alphabetically, each with its canSend verdict for this key, and requests the next page only once the current one is drained. It yields addresses only. Read ListAsync for unrestricted and domains.
Параметры
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?Reports on this key instead of the one the client was built with.
cancellationTokenCancellationTokenCancels the request.
Возвращает
An IAsyncEnumerable<JsonObject> that yields one address per step.
Пример
await foreach (var entry in client.Addresses.IterateAsync(limit: 50)){ if ((bool?)entry["canSend"] == true) { Console.WriteLine($"{entry["address"]}"); }}Примечания
The generator is lazy, so an abandoned loop costs only the pages you consumed.
Также доступно в
- API
GET /addresses- TypeScript
addresses.iterate()- Python
addresses.iterate()- Ruby
addresses.iterate- PHP
addresses->iterate- Go
Addresses.Iterate- Java
addresses().iterate