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

# $client->outOfOffice

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.

### `outOfOffice->list`

Read out of office replies

```php
list(?string $address = null, ?string $apiKey = null): array
```

Returns every out of office reply saved in the workspace, by address. With `address:` the list holds exactly one row, the reply of that address, which has `enabled` set to false and 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.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

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

**Example**

```php
$replies = $client->outOfOffice->list();

foreach ($replies as $reply) {
    echo $reply['address'], $reply['active'] ? ' is answering until ' : ' is not answering, set to end ', $reply['endsAt'] ?? 'it is switched off', PHP_EOL;
}

$mine = $client->outOfOffice->list(address: 'ada@example.com');

foreach ($mine as $reply) {
    echo $reply['enabled'] ? $reply['message'] : 'No reply is switched on', PHP_EOL;
}
```

**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); Ruby [`out_of_office.list`](https://openemail.uk/docs/ruby/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).

### `outOfOffice->set`

Set an out of office reply

```php
set(string $address, array $body, ?string $apiKey = null): array
```

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 null to keep it on until it is switched off. Both take a `DateTimeInterface` or an ISO 8601 string with an offset, and the SDK sends a `DateTimeInterface` as an ISO 8601 instant in UTC. 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` (`bool`): Whether the reply is switched on. Left out, true. `false` keeps the text and pauses the reply.
- `startsAt` (`string|DateTimeInterface|null`): When the reply starts. Left out or null, now, or the start it already has while the reply is on.
- `endsAt` (`string|DateTimeInterface|null`): When it stops, later than `startsAt`. Left out or null, it stays on until it is switched off.
- `contactsOnly` (`bool`): Answer only contacts and people the workspace has written to. Left out, false.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

An array, 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**

```php
$reply = $client->outOfOffice->set('ada@example.com', [
    'startsAt' => new \DateTimeImmutable('2026-12-22T00:00:00Z'),
    'endsAt' => new \DateTimeImmutable('2027-01-04T08:00:00Z'),
    'subject' => 'Away until 4 January',
    'message' => 'I am away until 4 January and will answer when I am back.',
    'contactsOnly' => true,
]);

echo $reply['address'], $reply['active'] ? ' is answering now' : ' is not answering yet', ', until ', $reply['endsAt'] ?? 'it is switched off', PHP_EOL;
```

**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); Ruby [`out_of_office.set`](https://openemail.uk/docs/ruby/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).

### `outOfOffice->clear`

Remove an out of office reply

```php
clear(string $address, ?string $apiKey = null): array
```

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.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

An array with `object` set to `out_of_office`, `address` and `deleted` set to true.

**Example**

```php
$removed = $client->outOfOffice->clear('ada@example.com');

echo $removed['address'], $removed['deleted'] ? ' answers nothing now' : ' was left as it was', PHP_EOL;
```

**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); Ruby [`out_of_office.clear`](https://openemail.uk/docs/ruby/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).