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

# openemail.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

```python
def list(
    *,
    address: str | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> builtins.list[OutOfOfficeResource]
```

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 reads `enabled` as `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` (`str`): 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` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

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

**Example**

```python
from openemail import openemail

replies = openemail.out_of_office.list()

for reply in replies:
    print(reply['address'], reply['active'], reply['endsAt'])

mine = openemail.out_of_office.list(address='ada@example.com')

if mine:
    print(mine[0]['enabled'], mine[0]['message'])
```

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

```python
def set(
    address: str,
    body: OutOfOfficeSet,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> OutOfOfficeResource
```

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 `None` to keep it on until it is switched off. Both take a `datetime` or an ISO 8601 string with an offset, and the SDK sends a `datetime` as a UTC ISO 8601 string. 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` (`str`, 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.
- `body['message']` (`str`, required): The reply, as plain text, 1 to 10,000 characters once trimmed. Line breaks are kept.
- `body['subject']` (`str`): The subject of the reply, at most 255 characters. Left out or empty, the reply answers with `Re:` and the subject received.
- `body['enabled']` (`bool`): Whether the reply is switched on. Left out, `True`. `False` keeps the text and pauses the reply.
- `body['startsAt']` (`datetime | str | None`): When the reply starts. Left out or `None`, now, or the start it already has while the reply is on.
- `body['endsAt']` (`datetime | str | None`): When it stops, later than `startsAt`. Left out or `None`, it stays on until it is switched off.
- `body['contactsOnly']` (`bool`): Answer only contacts and people the workspace has written to. Left out, `False`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`OutOfOfficeResource`, 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**

```python
from datetime import datetime, timezone

from openemail import openemail

reply = openemail.out_of_office.set(
    'ada@example.com',
    {
        'startsAt': datetime(2026, 12, 22, tzinfo=timezone.utc),
        'endsAt': datetime(2027, 1, 4, 8, tzinfo=timezone.utc),
        'subject': 'Away until 4 January',
        'message': 'I am away until 4 January and will answer when I am back.',
        'contactsOnly': True,
    },
)

print(reply['address'], reply['active'], reply['endsAt'])
```

**Notes**

- It replaces the whole reply, so a key 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.
- A naive `datetime` is read in the local zone of the machine running the SDK, so give it a `tzinfo`.

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

```python
def clear(
    address: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DeletedOutOfOfficeResource
```

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` set to `False` through `set` instead.

Scopes: `settings:write`.

**Parameters**

- `address` (`str`, 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` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DeletedOutOfOfficeResource` with `object` set to `out_of_office`, the `address`, and `deleted` set to `True`.

**Example**

```python
from openemail import openemail

removed = openemail.out_of_office.clear('ada@example.com')

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