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

# client.out_of_office

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

## Methods

The automatic reply an address sends while its owner is away: read the replies saved in the workspace, set one for an address or a catch-all with its dates, subject and message, and remove it.

### `out_of_office.list`

Read out of office replies

```ruby
list(address: nil, api_key: nil) -> Array<Hash>
```

Returns every out of office reply saved in the workspace, by address. With `address:` the Array holds exactly one row, the reply of that address, which reads `enabled` false with empty text when none was ever saved.

`active` says whether the reply is going out right now: it is on, the start has passed and the end has not. An address is one address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain.

Scopes: `settings:read`.

**Parameters**

- `address` (`String`): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. Left out, every reply saved in the workspace.
- `api_key` (`String`): Overrides the client's API key for this call only.

**Returns**

An Array of Hashes, each with `object` set to `out_of_office`, `address`, `enabled`, `active`, `startsAt`, `endsAt`, `subject`, `message`, `contactsOnly` and `updatedAt`. `startsAt` and `updatedAt` are nil on an address that never saved a reply, and a nil `endsAt` keeps the reply on until it is switched off.

**Example**

```ruby
replies = client.out_of_office.list

replies.each { |reply| puts "#{reply[:address]} #{reply[:active]} #{reply[:endsAt]}" }

mine = client.out_of_office.list(address: "ada@example.com").first

puts mine[:enabled], mine[:message] if mine
```

**Notes**

- A key or an app limited to particular addresses or domains lists only the replies of the addresses it holds, and of a catch-all only when it holds the domain whole. Naming an address it does not hold is a 422 `capability_unsupported`.
- A whole domain, written `@example.com`, is a 422 `invalid_parameter` on `address`, because a reply is set on one address or on a catch-all.
- Read only, so the SDK retries it after a network failure like any other read.

Also available in: API [`GET /out-of-office`](https://openemail.uk/docs/api/reference/settings#get-out-of-office); TypeScript [`outOfOffice.list()`](https://openemail.uk/docs/sdk/reference/out-of-office#list); Python [`out_of_office.list()`](https://openemail.uk/docs/python/reference/out-of-office#list); PHP [`outOfOffice->list`](https://openemail.uk/docs/php/reference/out-of-office#list); Go [`OutOfOffice.List`](https://openemail.uk/docs/go/reference/out-of-office#list); Java [`outOfOffice().list`](https://openemail.uk/docs/java/reference/out-of-office#list); C# [`OutOfOffice.ListAsync`](https://openemail.uk/docs/csharp/reference/out-of-office#list); CLI [`openemail out-of-office list`](https://openemail.uk/docs/cli/reference/out-of-office#out-of-office-list).

### `out_of_office.set`

Set an out of office reply

```ruby
set(address, body = nil, api_key: nil, **fields) -> Hash
```

Saves the out of office reply of one address, or of a catch-all with `*@example.com`, replacing whatever was saved. While it is active, each person who writes to the address gets the message once for the whole away period, as a reply in the same thread. Mail that would not alert anyone gets no reply: spam, mail a rule filed away, newsletters and other bulk mail, automatic mail, bounces, blocked senders and the workspace's own addresses. With `contactsOnly`, only people in the contacts, or people the workspace has written to, are answered.

Leave `startsAt` out to start now, or to keep the start of a reply that is already on, and `endsAt` out or nil to keep it on until it is switched off. Both take a `Time`, a `DateTime` or an ISO 8601 string with an offset, and the SDK sends a `Time` or a `DateTime` as a UTC ISO 8601 instant. An address with a reply of its own is never answered by the catch-all. Replies count toward the monthly sends, carry no tracking, and still go out on muted threads.

Scopes: `settings:write`.

**Parameters**

- `address` (`String`, required): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.
- `message` (`String`, required): The reply, as plain text, 1 to 10,000 characters once trimmed. Line breaks are kept.
- `subject` (`String`): The subject of the reply, at most 255 characters. Left out or empty, the reply answers with `Re:` and the subject received.
- `enabled` (`Boolean`): Whether the reply is switched on. Left out, true. `false` keeps the text and pauses the reply.
- `startsAt` (`Time, DateTime, String or nil`): When the reply starts. Left out or nil, now, or the start it already has while the reply is on.
- `endsAt` (`Time, DateTime, String or nil`): When it stops, later than `startsAt`. Left out or nil, it stays on until it is switched off.
- `contactsOnly` (`Boolean`): Answer only contacts and people the workspace has written to. Left out, false.
- `api_key` (`String`): Overrides the client's API key for this call only.

**Returns**

A Hash, the reply read back as it is stored, with `object` set to `out_of_office`, `address`, `enabled`, `active`, `startsAt`, `endsAt`, `subject`, `message`, `contactsOnly` and `updatedAt`. `active` says whether mail arriving now is answered.

**Example**

```ruby
reply = client.out_of_office.set(
  "ada@example.com",
  startsAt: Time.utc(2026, 12, 22),
  endsAt: Time.utc(2027, 1, 4, 8),
  subject: "Away until 4 January",
  message: "I am away until 4 January and will answer when I am back.",
  contactsOnly: true
)

puts reply[:address], reply[:active], reply[:endsAt]
```

**Notes**

- It replaces the whole reply, so a field left out goes back to its default instead of keeping what was saved. Send the full reply each time.
- An address that is not in the workspace or names a whole domain, an empty message, and an `endsAt` that is not after `startsAt` or is already in the past are each a 422 `invalid_parameter`. A key or an app that does not hold the address gets a 422 `capability_unsupported`.
- The SDK retries this call after a network failure, which is safe because saving the same reply twice leaves the same reply.

Also available in: API [`PUT /out-of-office`](https://openemail.uk/docs/api/reference/settings#put-out-of-office); TypeScript [`outOfOffice.set()`](https://openemail.uk/docs/sdk/reference/out-of-office#set); Python [`out_of_office.set()`](https://openemail.uk/docs/python/reference/out-of-office#set); PHP [`outOfOffice->set`](https://openemail.uk/docs/php/reference/out-of-office#set); Go [`OutOfOffice.Set`](https://openemail.uk/docs/go/reference/out-of-office#set); Java [`outOfOffice().set`](https://openemail.uk/docs/java/reference/out-of-office#set); C# [`OutOfOffice.SetAsync`](https://openemail.uk/docs/csharp/reference/out-of-office#set); CLI [`openemail out-of-office set`](https://openemail.uk/docs/cli/reference/out-of-office#out-of-office-set).

### `out_of_office.clear`

Remove an out of office reply

```ruby
clear(address, api_key: nil) -> Hash
```

Removes the saved reply of one address or catch-all, so nothing is answered from it any more. Removing a reply that was never saved changes nothing, which is why the SDK retries this call.

To pause a reply and keep its text, save it with `enabled: false` through `set` instead.

Scopes: `settings:write`.

**Parameters**

- `address` (`String`, required): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.
- `api_key` (`String`): Overrides the client's API key for this call only.

**Returns**

A Hash with `object` set to `out_of_office`, the `address` and `deleted` set to true.

**Example**

```ruby
removed = client.out_of_office.clear("ada@example.com")

puts removed[:address], removed[:deleted]
```

**Notes**

- A whole domain, written `@example.com`, is a 422 `invalid_parameter` on `address`. A key or an app that does not hold the address gets a 422 `capability_unsupported`.
- Removing the reply of a catch-all leaves the replies of single addresses on that domain as they are.

Also available in: API [`DELETE /out-of-office`](https://openemail.uk/docs/api/reference/settings#delete-out-of-office); TypeScript [`outOfOffice.clear()`](https://openemail.uk/docs/sdk/reference/out-of-office#clear); Python [`out_of_office.clear()`](https://openemail.uk/docs/python/reference/out-of-office#clear); PHP [`outOfOffice->clear`](https://openemail.uk/docs/php/reference/out-of-office#clear); Go [`OutOfOffice.Clear`](https://openemail.uk/docs/go/reference/out-of-office#clear); Java [`outOfOffice().clear`](https://openemail.uk/docs/java/reference/out-of-office#clear); C# [`OutOfOffice.ClearAsync`](https://openemail.uk/docs/csharp/reference/out-of-office#clear); CLI [`openemail out-of-office clear`](https://openemail.uk/docs/cli/reference/out-of-office#out-of-office-clear).