--- title: "openemail.outOfOffice" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://openemail.uk/docs/sdk/reference/out-of-office" area: "TypeScript" category: "Reference" --- # openemail.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 ```ts list(options?: OutOfOfficeListOptions): Promise> ``` Resolves every out of office reply saved in the workspace, by address. With `options.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** - `options.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. - `options.signal` (`AbortSignal`): Cancels the request. - `options.apiKey` (`string`): Overrides the client's API key for this call only. **Returns** `Array`, each `{ object: 'out_of_office', address, enabled, active, startsAt, endsAt, subject, message, contactsOnly, 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** ```ts const replies = await openemail.outOfOffice.list() for (const reply of replies) console.log(reply.address, reply.active, reply.endsAt) const [mine] = await openemail.outOfOffice.list({ address: 'ada@example.com' }) console.log(mine?.enabled, mine?.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); 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); 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). ### `outOfOffice.set()` Set an out of office reply ```ts set(address: string, body: OutOfOfficeSet, options?: RequestScope): Promise ``` 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 `Date` or an ISO 8601 string with an offset, and the SDK converts a `Date` with `toISOString()`. 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. - `body.message` (`string`, required): The reply, as plain text, 1 to 10,000 characters once trimmed. Line breaks are kept. - `body.subject` (`string`): The subject of the reply, at most 255 characters. Left out or empty, the reply answers with `Re:` and the subject received. - `body.enabled` (`boolean`): Whether the reply is switched on. Left out, true. `false` keeps the text and pauses the reply. - `body.startsAt` (`Date | string | null`): When the reply starts. Left out or null, now, or the start it already has while the reply is on. - `body.endsAt` (`Date | string | null`): When it stops, later than `startsAt`. Left out or null, it stays on until it is switched off. - `body.contactsOnly` (`boolean`): Answer only contacts and people the workspace has written to. Left out, false. - `options.signal` (`AbortSignal`): Cancels the request. - `options.apiKey` (`string`): Overrides the client's API key for this call only. **Returns** `OutOfOfficeResource`, the reply read back as it is stored: `{ object: 'out_of_office', address, enabled, active, startsAt, endsAt, subject, message, contactsOnly, updatedAt }`, with `active` saying whether mail arriving now is answered. **Example** ```ts const reply = await openemail.outOfOffice.set('ada@example.com', { startsAt: new Date('2026-12-22T00:00:00Z'), endsAt: new Date('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 }) console.log(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); 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); 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). ### `outOfOffice.clear()` Remove an out of office reply ```ts clear(address: string, options?: RequestScope): Promise ``` 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. - `options.signal` (`AbortSignal`): Cancels the request. - `options.apiKey` (`string`): Overrides the client's API key for this call only. **Returns** `DeletedOutOfOfficeResource`, `{ object: 'out_of_office', address, deleted: true }`. **Example** ```ts const removed = await openemail.outOfOffice.clear('ada@example.com') console.log(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); 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); 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).