---
title: "client.addresses"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/ruby/reference/addresses"
area: "Ruby"
category: "Reference"
---

# client.addresses

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

Which addresses and domains the key may send from.

### `addresses.list`

List the addresses and domains this key may send as

```ruby
list(limit: nil, cursor: nil, api_key: nil) -> OpenEmail::AddressBookPage
```

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. `list_all` collects every page into one book and `iterate` 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` array arrives as `addresses`, so the result is a single `OpenEmail::AddressBookPage` rather than a list.

Scopes: `emails:send`.

**Parameters**

- `limit` (`Integer`): Page size, from 1 to 100. The server defaults to 25.
- `cursor` (`String`): The `next_cursor` of the previous page. Leave it out for the first page.
- `api_key` (`String`): Reports on this key instead of the one the client was built with.

**Returns**

An `OpenEmail::AddressBookPage` with `unrestricted`, `has_more?`, `next_cursor`, `addresses` (Hashes with `address`, `enabled` and `canSend`) and `domains` (Hashes with `domain`, `receivingVerified`, `sendingVerified` and `catchAll`).

**Example**

```ruby
page = client.addresses.list

sendable = page.addresses.filter_map { |entry| entry[:address] if entry[:canSend] }

puts page.unrestricted
p sendable
```

**Notes**

- 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 holds `addresses:all`. That is worked out again on every call, so a domain added later appears on the next one.
- `canSend` is false when the address is disabled, when the key's allowlists leave it out, or when the domain cannot sign yet. `sendingVerified` on each domain is that last fact on its own, so a domain that is verified for receiving and not yet for sending shows `receivingVerified: 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`.

Also available in: API [`GET /addresses`](https://openemail.uk/docs/api/reference/account#get-addresses); TypeScript [`addresses.list()`](https://openemail.uk/docs/sdk/reference/addresses#list); Python [`addresses.list()`](https://openemail.uk/docs/python/reference/addresses#list); CLI [`openemail addresses list`](https://openemail.uk/docs/cli/reference/addresses#addresses-list).

### `addresses.list_all`

Collect every address this key may see into one book

```ruby
list_all(limit: nil, cursor: nil, api_key: nil) -> OpenEmail::AddressBook
```

Walks every page of `list` and returns one `OpenEmail::AddressBook` holding all addresses, alphabetically, with `unrestricted` and `domains` as the last page reported them. One request per page.

Scopes: `emails:send`.

**Parameters**

- `limit` (`Integer`): Page size for each request, from 1 to 100. The server defaults to 25.
- `cursor` (`String`): Starts the walk after this cursor instead of the first page.
- `api_key` (`String`): Reports on this key instead of the one the client was built with.

**Returns**

An `OpenEmail::AddressBook` with `unrestricted`, every address in `addresses`, and `domains`.

**Example**

```ruby
book = client.addresses.list_all

puts book.addresses.count { |entry| entry[:canSend] }
```

**Notes**

- If any page fails the call raises, and the addresses already fetched are discarded.

Also available in: API [`GET /addresses`](https://openemail.uk/docs/api/reference/account#get-addresses); TypeScript [`addresses.listAll()`](https://openemail.uk/docs/sdk/reference/addresses#listAll); Python [`addresses.list_all()`](https://openemail.uk/docs/python/reference/addresses#listAll).

### `addresses.iterate`

Stream the addresses one at a time

```ruby
iterate(limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>
```

Returns an Enumerator that yields addresses individually, alphabetically, each with its `canSend` verdict for this key, and requests the next page only once the current one is drained. Given a block, it yields each address to the block instead. It yields addresses only. Read `list` for `unrestricted` and `domains`.

Scopes: `emails:send`.

**Parameters**

- `limit` (`Integer`): Page size for each request, from 1 to 100. The server defaults to 25.
- `cursor` (`String`): Starts the walk after this cursor instead of the first page.
- `api_key` (`String`): Reports on this key instead of the one the client was built with.

**Returns**

An Enumerator of Hashes, one address per step, or yields each one to a block.

**Example**

```ruby
client.addresses.iterate do |entry|
  puts entry[:address] if entry[:canSend]
end
```

**Notes**

- The Enumerator is lazy, so an abandoned loop costs only the pages you consumed.

Also available in: API [`GET /addresses`](https://openemail.uk/docs/api/reference/account#get-addresses); TypeScript [`addresses.iterate()`](https://openemail.uk/docs/sdk/reference/addresses#iterate); Python [`addresses.iterate()`](https://openemail.uk/docs/python/reference/addresses#iterate).