> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> API reference for EmailOctopus: every `emailoctopus.api.*` operation with input and output types.

Every `emailoctopus.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Automations

### start

`automations.start`

Queue a contact into an automation

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.automations.start({ automation_id: '00000000-0000-0000-0000-000000000000', contact_id: '631251b876fece73bc9dd647fe596d5f' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `automation_id` | `string` | Yes | — |
| `contact_id` | `string` | Yes | — |

**Output:** *empty object*

***

## Campaigns

### get

`campaigns.get`

Get one campaign, including its subject and HTML content

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.campaigns.get({ campaign_id: '00000000-0000-0000-0000-000000000000' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `campaign_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description | |
| - | - | - | - | - |
| `id` | `string` | No | — | |
| `status` | `string` | No | — | |
| `name` | `string` | No | — | |
| `subject` | `string` | No | — | |
| `preview_text` | \`string | null\` | No | — |
| `to` | `string[]` | No | — | |
| `from` | `object` | No | — | |
| `content` | `object` | No | — | |
| `created_at` | `string` | No | — | |
| `sent_at` | `string` | No | — | |

> [accordion] from full type
>
> ```ts theme={null}
> {
>   name?: string,
>   email_address?: string
> }
> ```

> [accordion] content full type
>
> ```ts theme={null}
> {
>   html?: string
> }
> ```

***

### list

`campaigns.list`

List campaigns, one page at a time

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.campaigns.list({ limit: 10 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Page size. EmailOctopus returns at most 100. |
| `starting_after` | `string` | No | Cursor from paging.next.starting\_after. Pass it back unchanged. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | No | — |
| `paging` | `object` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   id?: string,
>   status?: string,
>   name?: string,
>   subject?: string,
>   preview_text?: string | null,
>   to?: string[],
>   from?: {
>     name?: string,
>     email_address?: string
>   },
>   content?: {
>     html?: string
>   },
>   created_at?: string,
>   sent_at?: string
> }[]
> ```

> [accordion] paging full type
>
> ```ts theme={null}
> {
>   next?: {
>     url?: string | null,
>     starting_after?: string | null
>   } | null
> }
> ```

***

### reportContacts

`campaigns.reportContacts`

List contacts for one campaign event, such as opened or bounced

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.campaigns.reportContacts({ campaign_id: '00000000-0000-0000-0000-000000000000', status: 'opened' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `campaign_id` | `string` | Yes | — |
| `status` | `bounced \| clicked \| complained \| opened \| sent \| unsubscribed \| not-opened \| not-clicked` | Yes | — |
| `limit` | `number` | No | Page size. EmailOctopus returns at most 100. |
| `starting_after` | `string` | No | Cursor from paging.next.starting\_after. Pass it back unchanged. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `string` | No | — |
| `data` | `object[]` | No | — |
| `paging` | `object` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   contact_id?: string,
>   contact_email_address?: string,
>   occurred_at?: string
> }[]
> ```

> [accordion] paging full type
>
> ```ts theme={null}
> {
>   next?: {
>     url?: string | null,
>     starting_after?: string | null
>   } | null
> }
> ```

***

### reportLinks

`campaigns.reportLinks`

Get click totals for each link in a campaign

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.campaigns.reportLinks({ campaign_id: '00000000-0000-0000-0000-000000000000' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `campaign_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   url?: string,
>   clicked_total?: number,
>   clicked_unique?: number
> }[]
> ```

***

### reportSummary

`campaigns.reportSummary`

Get sent, bounce, open, click, complaint and unsubscribe totals

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.campaigns.reportSummary({ campaign_id: '00000000-0000-0000-0000-000000000000' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `campaign_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `sent` | `number` | No | — |
| `bounced` | `object` | No | — |
| `opened` | `object` | No | — |
| `clicked` | `object` | No | — |
| `complained` | `number` | No | — |
| `unsubscribed` | `number` | No | — |

> [accordion] bounced full type
>
> ```ts theme={null}
> {
>   hard?: number,
>   soft?: number
> }
> ```

> [accordion] opened full type
>
> ```ts theme={null}
> {
>   total?: number,
>   unique?: number
> }
> ```

> [accordion] clicked full type
>
> ```ts theme={null}
> {
>   total?: number,
>   unique?: number
> }
> ```

***

## Contacts

### batch

`contacts.batch`

Update many contacts on a list. Each entry is reported under success or errors

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.contacts.batch({ list_id: '00000000-0000-0000-0000-000000000000', contacts: [{ id: '00000000-0000-0000-0000-000000000001', status: 'subscribed' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `contacts` | `object[]` | Yes | — |

> [accordion] contacts full type
>
> ```ts theme={null}
> {
>   id: string,
>   email_address?: string,
>   fields?: Record<string, string | number | string[] | null>,
>   tags?: Record<string, boolean>,
>   status?: 'pending' | 'subscribed' | 'unsubscribed'
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `object[]` | No | — |
| `errors` | `object[]` | No | — |

> [accordion] success full type
>
> ```ts theme={null}
> {
>   success?: boolean,
>   data?: {
>     id?: string | null,
>     email_address?: string | null,
>     fields?: Record<string, string | number | string[] | null> | null,
>     tags?: string[] | null,
>     status?: string | null,
>     created_at?: string | null,
>     last_updated_at?: string | null
>   }
> }[]
> ```

> [accordion] errors full type
>
> ```ts theme={null}
> {
>   success?: boolean,
>   id?: string,
>   type?: string,
>   title?: string,
>   detail?: string,
>   status?: number
> }[]
> ```

***

### create

`contacts.create`

Add a contact to a list. Fails if that email is already on it

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.contacts.create({ list_id: '00000000-0000-0000-0000-000000000000', email_address: 'otto@example.com', tags: ['vip'], status: 'subscribed' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `email_address` | `string` | Yes | — |
| `fields` | `object` | No | — |
| `tags` | `string[]` | No | — |
| `status` | `'pending' \| 'subscribed' \| 'unsubscribed'` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `email_address` | `string` | No | — |
| `fields` | `object` | No | — |
| `tags` | `string[]` | No | — |
| `status` | `string` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

***

### delete

`contacts.delete`

Permanently delete a contact from a list

**Risk:** `destructive`

```ts theme={null}
await corsair.emailoctopus.api.contacts.delete({ list_id: '00000000-0000-0000-0000-000000000000', contact_id: '00000000-0000-0000-0000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `contact_id` | `string` | Yes | — |

**Output:** *empty object*

***

### get

`contacts.get`

Get one contact on a list

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.contacts.get({ list_id: '00000000-0000-0000-0000-000000000000', contact_id: '00000000-0000-0000-0000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `contact_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `email_address` | `string` | No | — |
| `fields` | `object` | No | — |
| `tags` | `string[]` | No | — |
| `status` | `string` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

***

### list

`contacts.list`

List contacts on a list, optionally filtered by status, tag or time, with cursor paging

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.contacts.list({ list_id: '00000000-0000-0000-0000-000000000000', status: 'subscribed', limit: 10 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `limit` | `number` | No | Page size. EmailOctopus returns at most 100. |
| `starting_after` | `string` | No | Cursor from paging.next.starting\_after. Pass it back unchanged. |
| `tag` | `string` | No | — |
| `status` | `'pending' \| 'subscribed' \| 'unsubscribed'` | No | — |
| `created_at.lte` | `string` | No | — |
| `created_at.gte` | `string` | No | — |
| `last_updated_at.lte` | `string` | No | — |
| `last_updated_at.gte` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | No | — |
| `paging` | `object` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   email_address?: string | null,
>   fields?: Record<string, string | number | string[] | null> | null,
>   tags?: string[] | null,
>   status?: string | null,
>   created_at?: string | null,
>   last_updated_at?: string | null
> }[]
> ```

> [accordion] paging full type
>
> ```ts theme={null}
> {
>   next?: {
>     url?: string | null,
>     starting_after?: string | null
>   } | null
> }
> ```

***

### update

`contacts.update`

Update a contact by id

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.contacts.update({ list_id: '00000000-0000-0000-0000-000000000000', contact_id: '00000000-0000-0000-0000-000000000001', status: 'unsubscribed' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `contact_id` | `string` | Yes | — |
| `email_address` | `string` | No | — |
| `fields` | `object` | No | — |
| `tags` | `object` | No | — |
| `status` | `'pending' \| 'subscribed' \| 'unsubscribed'` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

> [accordion] tags full type
>
> ```ts theme={null}
> Record<string, boolean>
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `email_address` | `string` | No | — |
| `fields` | `object` | No | — |
| `tags` | `string[]` | No | — |
| `status` | `string` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

***

### upsert

`contacts.upsert`

Create a contact or update the existing one with the same email address

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.contacts.upsert({ list_id: '00000000-0000-0000-0000-000000000000', email_address: 'otto@example.com', tags: { vip: true } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `email_address` | `string` | Yes | — |
| `fields` | `object` | No | — |
| `tags` | `object` | No | — |
| `status` | `'pending' \| 'subscribed' \| 'unsubscribed'` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

> [accordion] tags full type
>
> ```ts theme={null}
> Record<string, boolean>
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `email_address` | `string` | No | — |
| `fields` | `object` | No | — |
| `tags` | `string[]` | No | — |
| `status` | `string` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> Record<string, string | number | string[] | null>
> ```

***

## Fields

### create

`fields.create`

Add a custom field to a list

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.fields.create({ list_id: '00000000-0000-0000-0000-000000000000', label: 'Hometown', tag: 'Hometown', type: 'text', fallback: 'Unknown' });
```

**Input:** `object`

> [accordion] Input full type
>
> ```ts theme={null}
> {
>   list_id: string,
>   label: string,
>   tag: string,
>   type: 'text' | 'number' | 'date',
>   fallback?: string | null
> } | {
>   list_id: string,
>   label: string,
>   tag: string,
>   type: 'choice_single' | 'choice_multiple',
>   choices: string[],
>   fallback?: string | null
> }
> ```

**Output**

| Name | Type | Required | Description | |
| - | - | - | - | - |
| `label` | `string` | No | — | |
| `tag` | `string` | No | — | |
| `type` | `string` | No | — | |
| `choices` | `string[]` | No | — | |
| `fallback` | \`string | null\` | No | — |

***

### delete

`fields.delete`

Permanently delete a custom field from a list

**Risk:** `destructive`

```ts theme={null}
await corsair.emailoctopus.api.fields.delete({ list_id: '00000000-0000-0000-0000-000000000000', tag: 'Hometown' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `tag` | `string` | Yes | — |

**Output:** *empty object*

***

### update

`fields.update`

Update a text, number or date field on a list

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.fields.update({ list_id: '00000000-0000-0000-0000-000000000000', label: 'Hometown', tag: 'Hometown', type: 'text' });
```

**Input**

| Name | Type | Required | Description | |
| - | - | - | - | - |
| `list_id` | `string` | Yes | — | |
| `label` | `string` | Yes | — | |
| `tag` | `string` | Yes | — | |
| `type` | `'text' \| 'number' \| 'date'` | Yes | — | |
| `fallback` | \`string | null\` | No | — |

**Output**

| Name | Type | Required | Description | |
| - | - | - | - | - |
| `label` | `string` | No | — | |
| `tag` | `string` | No | — | |
| `type` | `string` | No | — | |
| `choices` | `string[]` | No | — | |
| `fallback` | \`string | null\` | No | — |

***

## Lists

### create

`lists.create`

Create a list

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.lists.create({ name: 'New clients list' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `double_opt_in` | `boolean` | No | — |
| `fields` | `object[]` | No | — |
| `tags` | `string[]` | No | — |
| `counts` | `object[]` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   label?: string,
>   tag?: string,
>   type?: string,
>   choices?: string[],
>   fallback?: string | null
> }[]
> ```

> [accordion] counts full type
>
> ```ts theme={null}
> {
>   pending?: number,
>   subscribed?: number,
>   unsubscribed?: number
> }[]
> ```

***

### delete

`lists.delete`

Permanently delete a list and its contacts

**Risk:** `destructive`

```ts theme={null}
await corsair.emailoctopus.api.lists.delete({ list_id: '00000000-0000-0000-0000-000000000000' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |

**Output:** *empty object*

***

### get

`lists.get`

Get one list, including its fields, tags and contact counts

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.lists.get({ list_id: '00000000-0000-0000-0000-000000000000' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `double_opt_in` | `boolean` | No | — |
| `fields` | `object[]` | No | — |
| `tags` | `string[]` | No | — |
| `counts` | `object[]` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   label?: string,
>   tag?: string,
>   type?: string,
>   choices?: string[],
>   fallback?: string | null
> }[]
> ```

> [accordion] counts full type
>
> ```ts theme={null}
> {
>   pending?: number,
>   subscribed?: number,
>   unsubscribed?: number
> }[]
> ```

***

### list

`lists.list`

List every list in the account, one page at a time

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.lists.list({ limit: 10 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Page size. EmailOctopus returns at most 100. |
| `starting_after` | `string` | No | Cursor from paging.next.starting\_after. Pass it back unchanged. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | No | — |
| `paging` | `object` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string,
>   double_opt_in?: boolean,
>   fields?: {
>     label?: string,
>     tag?: string,
>     type?: string,
>     choices?: string[],
>     fallback?: string | null
>   }[],
>   tags?: string[],
>   counts?: {
>     pending?: number,
>     subscribed?: number,
>     unsubscribed?: number
>   }[],
>   created_at?: string,
>   last_updated_at?: string
> }[]
> ```

> [accordion] paging full type
>
> ```ts theme={null}
> {
>   next?: {
>     url?: string | null,
>     starting_after?: string | null
>   } | null
> }
> ```

***

### update

`lists.update`

Rename a list

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.lists.update({ list_id: '00000000-0000-0000-0000-000000000000', name: 'Renamed list' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `name` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `double_opt_in` | `boolean` | No | — |
| `fields` | `object[]` | No | — |
| `tags` | `string[]` | No | — |
| `counts` | `object[]` | No | — |
| `created_at` | `string` | No | — |
| `last_updated_at` | `string` | No | — |

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   label?: string,
>   tag?: string,
>   type?: string,
>   choices?: string[],
>   fallback?: string | null
> }[]
> ```

> [accordion] counts full type
>
> ```ts theme={null}
> {
>   pending?: number,
>   subscribed?: number,
>   unsubscribed?: number
> }[]
> ```

***

## Tags

### create

`tags.create`

Create a tag on a list

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.tags.create({ list_id: '00000000-0000-0000-0000-000000000000', tag: 'vip' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `tag` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tag` | `string` | No | — |

***

### delete

`tags.delete`

Permanently delete a tag from a list

**Risk:** `destructive`

```ts theme={null}
await corsair.emailoctopus.api.tags.delete({ list_id: '00000000-0000-0000-0000-000000000000', tag: 'vip' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `tag` | `string` | Yes | — |

**Output:** *empty object*

***

### list

`tags.list`

List the tags on a list

**Risk:** `read`

```ts theme={null}
await corsair.emailoctopus.api.tags.list({ list_id: '00000000-0000-0000-0000-000000000000' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `limit` | `number` | No | Page size. EmailOctopus returns at most 100. |
| `starting_after` | `string` | No | Cursor from paging.next.starting\_after. Pass it back unchanged. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | No | — |
| `paging` | `object` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   tag?: string
> }[]
> ```

> [accordion] paging full type
>
> ```ts theme={null}
> {
>   next?: {
>     url?: string | null,
>     starting_after?: string | null
>   } | null
> }
> ```

***

### update

`tags.update`

Rename a tag. The current name is the URL; the new name is the body

**Risk:** `write`

```ts theme={null}
await corsair.emailoctopus.api.tags.update({ list_id: '00000000-0000-0000-0000-000000000000', tag: 'vip', name: 'customer' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `list_id` | `string` | Yes | — |
| `tag` | `string` | Yes | Current tag name. Sent in the URL. |
| `name` | `string` | Yes | Replacement tag name. Sent as body.tag. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tag` | `string` | No | — |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.