> ## 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 Campayn: every `campayn.api.*` operation with input and output types.

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

<Info>
  **New to Corsair?** See [API access](/concepts/api), [authentication](/concepts/auth), and [error handling](/concepts/error-handling).
</Info>

## Contacts

### createContact

`contacts.createContact`

Create a new contact in a contact list.

**Risk:** `write`

```ts theme={null}
await corsair.campayn.api.contacts.createContact({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `email` | `string` | Yes | — |
| `first_name` | `string` | No | — |
| `last_name` | `string` | No | — |
| `title` | `string` | No | — |
| `address` | `string` | No | — |
| `city` | `string` | No | — |
| `state` | `string` | No | — |
| `zip` | `string` | No | — |
| `company` | `string` | No | — |
| `country` | `string` | No | — |
| `phones` | `object[]` | No | — |
| `sites` | `object[]` | No | — |
| `social` | `object[]` | No | — |
| `custom_fields` | `object[]` | No | — |
| `failOnDuplicate` | `boolean` | No | — |

<AccordionGroup>
  <Accordion title="phones full type">
    ```ts theme={null}
    {
      value: string,
      type: string
    }[]
    ```
  </Accordion>

  <Accordion title="sites full type">
    ```ts theme={null}
    {
      value: string,
      type: string
    }[]
    ```
  </Accordion>

  <Accordion title="social full type">
    ```ts theme={null}
    {
      value: string,
      type: string,
      protocol: string
    }[]
    ```
  </Accordion>

  <Accordion title="custom_fields full type">
    ```ts theme={null}
    {
      field: string,
      value?: string,
      variable?: string
    }[]
    ```
  </Accordion>
</AccordionGroup>

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean \| 1 \| 0` | Yes | — |

***

### deleteContact

`contacts.deleteContact`

Delete a contact by contact ID.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.campayn.api.contacts.deleteContact({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `contactId` | `string \| number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean \| 1 \| 0` | Yes | — |

***

### getContact

`contacts.getContact`

Get full contact details by contact ID.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.contacts.getContact({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `contactId` | `string \| number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `email` | `string` | Yes | — |
| `first_name` | `string` | No | — |
| `last_name` | `string` | No | — |
| `title` | `string` | No | — |
| `company` | `string` | No | — |
| `address` | `string` | No | — |
| `country_id` | `string` | No | — |
| `country` | `string` | No | — |
| `city` | `string` | No | — |
| `state` | `string` | No | — |
| `zip` | `string` | No | — |
| `birthday` | `string` | No | — |
| `tags` | `string` | No | — |
| `phones` | `object[]` | No | — |
| `sites` | `object[]` | No | — |
| `social` | `object[]` | No | — |
| `custom_fields` | `object[]` | No | — |
| `image_url` | `string` | No | — |

<AccordionGroup>
  <Accordion title="phones full type">
    ```ts theme={null}
    {
      value: string,
      type: string
    }[]
    ```
  </Accordion>

  <Accordion title="sites full type">
    ```ts theme={null}
    {
      value: string,
      type: string
    }[]
    ```
  </Accordion>

  <Accordion title="social full type">
    ```ts theme={null}
    {
      value: string,
      type: string,
      protocol: string
    }[]
    ```
  </Accordion>

  <Accordion title="custom_fields full type">
    ```ts theme={null}
    {
      field: string,
      value?: string,
      variable?: string
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### getContacts

`contacts.getContacts`

List contacts for a contact list, with optional contact keyword filtering.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.contacts.getContacts({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `contactFilter` | `string` | No | — |

**Output:** `object[]`

<AccordionGroup>
  <Accordion title="Output full type">
    ```ts theme={null}
    {
      id: string,
      email: string,
      first_name?: string | null,
      last_name?: string | null,
      image_url?: string | null
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### unsubscribeContact

`contacts.unsubscribeContact`

Unsubscribe contacts from a list by contact ID or by email address.

**Risk:** `write`

```ts theme={null}
await corsair.campayn.api.contacts.unsubscribeContact({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `id` | `string \| number` | No | — |
| `email` | `string` | No | — |

**Output:** `object`

<AccordionGroup>
  <Accordion title="Output full type">
    ```ts theme={null}
    {
      success: boolean | 1 | 0
    } | {
      contactCount: number | string,
      success: boolean,
      msg: string,
      unsubscribeCount: number | string
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Lists

### deleteList

`lists.deleteList`

Delete a contact list by list ID.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.campayn.api.lists.deleteList({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean \| 1 \| 0` | Yes | — |

***

### getLists

`lists.getLists`

List all contact lists visible to the authenticated user.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.lists.getLists({});
```

**Input:** *empty object*

**Output:** `object[]`

<AccordionGroup>
  <Accordion title="Output full type">
    ```ts theme={null}
    {
      id: string,
      list_name: string,
      tags?: string,
      contact_count: number | string
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### updateList

`lists.updateList`

Update a contact list name or tags by list ID.

**Risk:** `write`

```ts theme={null}
await corsair.campayn.api.lists.updateList({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `list_name` | `string` | No | — |
| `tags` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `list_name` | `string` | Yes | — |
| `tags` | `string` | No | — |
| `contact_count` | `number \| string` | Yes | — |

***

## Messages

### getMessages

`messages.getMessages`

List messages visible to the authenticated user.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.messages.getMessages({});
```

**Input:** *empty object*

**Output:** `object[]`

<AccordionGroup>
  <Accordion title="Output full type">
    ```ts theme={null}
    {
      id?: string,
      name?: string,
      scheduled_date?: string | null,
      send_now?: string | number,
      send_count?: string | number,
      campaign_title?: string | null,
      status?: string,
      unique_views?: number | string,
      unique_responses?: number | string,
      percent_views?: number | string,
      percent_responses?: number | string,
      preview_url?: string,
      preview_thumb?: string,
      report_url?: string | null
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### getMessageStatistics

`messages.getMessageStatistics`

Get message statistics for a specific message ID.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.messages.getMessageStatistics({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `messageId` | `string \| number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `scheduled_date` | `string` | No | — |
| `send_now` | `string \| number` | No | — |
| `send_count` | `string \| number` | No | — |
| `campaign_title` | `string` | No | — |
| `status` | `string` | No | — |
| `unique_views` | `number \| string` | No | — |
| `unique_responses` | `number \| string` | No | — |
| `percent_views` | `number \| string` | No | — |
| `percent_responses` | `number \| string` | No | — |
| `preview_url` | `string` | No | — |
| `preview_thumb` | `string` | No | — |
| `report_url` | `string` | No | — |

***

## Reports

### getReports

`reports.getReports`

Get report calendar entries for sent and scheduled emails, optionally filtered by Unix timestamp range.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.reports.getReports({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `from` | `number` | No | — |
| `to` | `number` | No | — |

**Output:** `object[]`

<AccordionGroup>
  <Accordion title="Output full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      scheduled_date?: string | null,
      status: string,
      preview_url: string,
      report_url?: string | null
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

## Signup

### signup

`signup.signup`

Create a Campayn account via POST /signup on the site root (not /api/v1).

**Risk:** `write`

```ts theme={null}
await corsair.campayn.api.signup.signup({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `email` | `string` | Yes | — |
| `first_name` | `string` | Yes | — |
| `last_name` | `string` | Yes | — |
| `password` | `string` | Yes | — |
| `subdomain` | `string` | No | — |
| `site` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `number \| boolean` | Yes | — |
| `msg` | `string` | Yes | — |
| `errorCode` | `string` | No | — |

***

## Webforms

### deleteWebform

`webforms.deleteWebform`

Delete a webform by list ID and webform ID.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.campayn.api.webforms.deleteWebform({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `webformId` | `string \| number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean \| 1 \| 0` | Yes | — |

***

### getWebform

`webforms.getWebform`

Get a webform by list ID and webform ID.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.webforms.getWebform({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `webformId` | `string \| number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `contact_list_id` | `string` | Yes | — |
| `form_title` | `string` | Yes | — |
| `form_type` | `string` | Yes | — |
| `form_html` | `string` | Yes | — |
| `signup_count` | `string \| number` | Yes | — |

***

### getWebforms

`webforms.getWebforms`

List webforms for a contact list, with optional form type filter.

**Risk:** `read`

```ts theme={null}
await corsair.campayn.api.webforms.getWebforms({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `listId` | `string \| number` | Yes | — |
| `form_type` | `0 \| 1 \| 2 \| 3` | No | — |

**Output:** `object[]`

<AccordionGroup>
  <Accordion title="Output full type">
    ```ts theme={null}
    {
      id: string,
      contact_list_id: string,
      form_title: string,
      form_type: string,
      form_html: string,
      signup_count: string | number
    }[]
    ```
  </Accordion>
</AccordionGroup>

***


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