Kit API reference

New to Corsair? See API access, authentication, and error handling.

Account

get

account.get The account and its user: plan, primary address, timezone and the sending addresses with their verification and DMARC status Risk: read

await corsair.kit.api.account.get({});

Input: empty object Output

Name	Type	Required	Description
`user`	`object \| null`	No	—
`account`	`object`	Yes	—

user full type

{
  id?: number | null,
  email?: string | null
} | null

account full type

{
  id?: number | null,
  name?: string | null,
  plan_type?: string | null,
  primary_email_address?: string | null,
  created_at?: string | null,
  timezone?: {
    name?: string | null,
    friendly_name?: string | null,
    utc_offset?: string | null
  } | null,
  sending_addresses?: {
    email_address?: string | null,
    from_name?: string | null,
    status?: string | null,
    is_default?: boolean | null,
    is_verified?: boolean | null,
    is_dmarc_configured?: boolean | null
  }[] | null,
  plan?: {
    plan_type?: string | null,
    interval?: string | null,
    subscriber_limit?: number | null,
    on_trial?: boolean | null,
    trial_lapse_date?: string | null,
    renews_at?: string | null,
    cancels_at?: string | null
  } | null
}

Custom Fields

create

customFields.create Create a custom field; Kit derives its key from the label Risk: write

await corsair.kit.api.customFields.create({ label: 'Last name' });

Input

Name	Type	Required	Description
`label`	`string`	Yes	The field label. Kit derives its `key` from this.

Output

Name	Type	Required	Description
`custom_field`	`object`	Yes	—

custom_field full type

{
  id: number,
  name?: string | null,
  key?: string | null,
  label?: string | null
}

list

customFields.list Every custom field with the key a subscriber’s fields map uses Risk: read

await corsair.kit.api.customFields.list({});

Input

Name	Type	Required	Description
`after`	`string`	No	The `end_cursor` of the page before, for the next page.
`before`	`string`	No	The `start_cursor` of the page after, for the previous page.
`per_page`	`number`	No	Items per page, up to 1000. Kit’s default is 500.
`include_total_count`	`boolean`	No	—

Output

Name	Type	Required	Description
`custom_fields`	`object[]`	Yes	—
`pagination`	`object \| null`	No	—

custom_fields full type

{
  id: number,
  name?: string | null,
  key?: string | null,
  label?: string | null
}[]

pagination full type

{
  has_previous_page?: boolean | null,
  has_next_page?: boolean | null,
  start_cursor?: string | null,
  end_cursor?: string | null,
  per_page?: number | null
} | null

update

customFields.update Change a custom field’s label Risk: write

await corsair.kit.api.customFields.update({ customFieldId: 7, label: 'Surname' });

Input

Name	Type	Required	Description
`customFieldId`	`number`	Yes	The custom field ID.
`label`	`string`	Yes	—

Output

Name	Type	Required	Description
`custom_field`	`object`	Yes	—

custom_field full type

{
  id: number,
  name?: string | null,
  key?: string | null,
  label?: string | null
}

Forms

list

forms.list Forms by status, cursor-paged, optionally with each one’s subscriber count Risk: read

await corsair.kit.api.forms.list({ include: ['subscriber_count'], status: 'active' });

Input

Name	Type	Required	Description
`after`	`string`	No	The `end_cursor` of the page before, for the next page.
`before`	`string`	No	The `start_cursor` of the page after, for the previous page.
`per_page`	`number`	No	Items per page, up to 1000. Kit’s default is 500.
`include`	`subscriber_count[]`	No	Also return each form’s active subscriber count.
`status`	`active \| archived \| trashed \| all`	No	Defaults to `active`.

Output

Name	Type	Required	Description
`forms`	`object[]`	Yes	—
`pagination`	`object \| null`	No	—

forms full type

{
  id: number,
  name?: string | null,
  created_at?: string | null,
  type?: string | null,
  format?: string | null,
  embed_js?: string | null,
  embed_url?: string | null,
  archived?: boolean | null,
  uid?: string | null,
  subscriber_count?: number | null
}[]

pagination full type

{
  has_previous_page?: boolean | null,
  has_next_page?: boolean | null,
  start_cursor?: string | null,
  end_cursor?: string | null,
  per_page?: number | null
} | null

forms.subscribe Add an existing subscriber to a form, which applies the form’s incentive and records when they were added. Create the subscriber first Risk: destructive

await corsair.kit.api.forms.subscribe({ form_id: 12, email_address: 'jordan@acme.example', referrer: 'https://acme.example/blog' });

Input

Name	Type	Required	Description
`form_id`	`number`	Yes	The form ID.
`email_address`	`string`	Yes	An email address. Kit normalizes its case, and returns an existing subscriber rather than creating a duplicate.
`referrer`	`string`	No	Where the signup came from.

The subscriber must already exist; call subscribers.create first, then this to record the signup against the form, apply its incentive and set added_at. Output

Name	Type	Required	Description
`subscriber`	`object`	Yes	—

subscriber full type

{
  id: number,
  first_name?: string | null,
  email_address: string,
  state?: string | null,
  created_at?: string | null,
  canceled_at?: string | null,
  fields?: Record<string, string | null> | null,
  attribution?: {
    referrer?: string | null,
    utm_source?: string | null,
    utm_medium?: string | null,
    utm_campaign?: string | null,
    utm_term?: string | null,
    utm_content?: string | null,
    source_type?: string | null,
    source_name?: string | null,
    source_mechanism?: string | null,
    source_mechanism_id?: number | null
  } | null,
  location?: {
    city?: string | null,
    state?: string | null,
    country?: string | null,
    latitude?: number | null,
    longitude?: number | null,
    timezone?: string | null
  } | null,
  tags?: {
    id?: number | null,
    name?: string | null
  }[] | null,
  added_at?: string | null
}

Subscribers

create

subscribers.create Create a subscriber, or return the existing one for an address already on the list. Unknown custom field keys are ignored and named in warnings Risk: write

await corsair.kit.api.subscribers.create({ email_address: 'jordan@acme.example', first_name: 'Jordan', fields: { last_name: 'Lee' } });

Input

Name	Type	Required	Description
`email_address`	`string`	Yes	An email address. Kit normalizes its case, and returns an existing subscriber rather than creating a duplicate.
`first_name`	`string`	No	—
`state`	`active \| cancelled \| bounced \| complained \| inactive`	No	Defaults to `active`.
`fields`	`Record<string, string>`	No	Custom field values keyed by the field’s `key`, such as `last_name`. An unknown key is ignored and named in `warnings`.

An address already on the list returns the existing subscriber. An unknown custom field key is ignored and named in warnings. Output

Name	Type	Required	Description
`subscriber`	`object`	Yes	—
`warnings`	`string[] \| null`	No	Custom field keys Kit ignored because it did not recognise them.

subscriber full type

{
  id: number,
  first_name?: string | null,
  email_address: string,
  state?: string | null,
  created_at?: string | null,
  canceled_at?: string | null,
  fields?: Record<string, string | null> | null,
  attribution?: {
    referrer?: string | null,
    utm_source?: string | null,
    utm_medium?: string | null,
    utm_campaign?: string | null,
    utm_term?: string | null,
    utm_content?: string | null,
    source_type?: string | null,
    source_name?: string | null,
    source_mechanism?: string | null,
    source_mechanism_id?: number | null
  } | null,
  location?: {
    city?: string | null,
    state?: string | null,
    country?: string | null,
    latitude?: number | null,
    longitude?: number | null,
    timezone?: string | null
  } | null,
  tags?: {
    id?: number | null,
    name?: string | null
  }[] | null
}

get

subscribers.get One subscriber with their custom field values and location Risk: read

await corsair.kit.api.subscribers.get({ subscriberId: 1001 });

Input

Name	Type	Required	Description
`subscriberId`	`number`	Yes	The subscriber ID, from `subscribers.list`.

Output

Name	Type	Required	Description
`subscriber`	`object`	Yes	—

subscriber full type

{
  id: number,
  first_name?: string | null,
  email_address: string,
  state?: string | null,
  created_at?: string | null,
  canceled_at?: string | null,
  fields?: Record<string, string | null> | null,
  attribution?: {
    referrer?: string | null,
    utm_source?: string | null,
    utm_medium?: string | null,
    utm_campaign?: string | null,
    utm_term?: string | null,
    utm_content?: string | null,
    source_type?: string | null,
    source_name?: string | null,
    source_mechanism?: string | null,
    source_mechanism_id?: number | null
  } | null,
  location?: {
    city?: string | null,
    state?: string | null,
    country?: string | null,
    latitude?: number | null,
    longitude?: number | null,
    timezone?: string | null
  } | null,
  tags?: {
    id?: number | null,
    name?: string | null
  }[] | null
}

list

subscribers.list Subscribers by state, address or date, cursor-paged, with optional attribution, tags and location Risk: read

await corsair.kit.api.subscribers.list({ per_page: 25, status: 'active', include: ['tags'] });

Input

Name	Type	Required	Description
`after`	`string`	No	The `end_cursor` of the page before, for the next page.
`before`	`string`	No	The `start_cursor` of the page after, for the previous page.
`per_page`	`number`	No	Items per page, up to 1000. Kit’s default is 500.
`status`	`active \| cancelled \| bounced \| complained \| inactive \| all`	No	Defaults to `active`. `all` widens it to every state.
`email_address`	`string`	No	Only the subscriber with this exact address.
`include`	`(attribution \| tags \| location \| canceled_at)[]`	No	Embed these extra fields on each subscriber. `canceled_at` needs `status: "cancelled"`.
`include_total_count`	`boolean`	No	Also return the total number of matching subscribers.
`slim`	`boolean`	No	Omit the `fields` object for a smaller, faster response.
`sort_field`	`id \| created_at \| updated_at \| cancelled_at \| canceled_at \| engagement__sent \| engagement__opens \| engagement__clicks \| engagement__open_rate \| engagement__click_rate`	No	Field to order by. `cancelled_at` needs `status: "cancelled"`. An `engagement__<metric>` sort orders by the trailing 90 days and cannot be combined with `email_address`.
`sort_order`	`asc \| desc`	No	—
`created_after`	`string`	No	A date, `yyyy-mm-dd`.
`created_before`	`string`	No	A date, `yyyy-mm-dd`.
`updated_after`	`string`	No	A date, `yyyy-mm-dd`.
`updated_before`	`string`	No	A date, `yyyy-mm-dd`.

Pages by cursor: pass pagination.end_cursor back as after. Only active subscribers are returned unless status says otherwise. Output

Name	Type	Required	Description
`subscribers`	`object[]`	Yes	—
`pagination`	`object \| null`	No	—

subscribers full type

{
  id: number,
  first_name?: string | null,
  email_address: string,
  state?: string | null,
  created_at?: string | null,
  canceled_at?: string | null,
  fields?: Record<string, string | null> | null,
  attribution?: {
    referrer?: string | null,
    utm_source?: string | null,
    utm_medium?: string | null,
    utm_campaign?: string | null,
    utm_term?: string | null,
    utm_content?: string | null,
    source_type?: string | null,
    source_name?: string | null,
    source_mechanism?: string | null,
    source_mechanism_id?: number | null
  } | null,
  location?: {
    city?: string | null,
    state?: string | null,
    country?: string | null,
    latitude?: number | null,
    longitude?: number | null,
    timezone?: string | null
  } | null,
  tags?: {
    id?: number | null,
    name?: string | null
  }[] | null
}[]

pagination full type

{
  has_previous_page?: boolean | null,
  has_next_page?: boolean | null,
  start_cursor?: string | null,
  end_cursor?: string | null,
  per_page?: number | null
} | null

unsubscribe

subscribers.unsubscribe Unsubscribe a subscriber, which stops every future send to them; re-subscribing takes their own action, not a call Risk: destructive · Irreversible

await corsair.kit.api.subscribers.unsubscribe({ subscriberId: 1001 });

Input

Name	Type	Required	Description
`subscriberId`	`number`	Yes	The subscriber ID, from `subscribers.list`.

Stops every future send to that person. Only they can resubscribe. Output

Name	Type	Required	Description
`success`	`true`	Yes	—
`subscriber_id`	`number`	Yes	—

update

subscribers.update Change a subscriber’s address, first name or custom field values Risk: write

await corsair.kit.api.subscribers.update({ subscriberId: 1001, email_address: 'jordan@acme.example', first_name: 'Jordy' });

Input

Name	Type	Required	Description
`subscriberId`	`number`	Yes	The subscriber ID, from `subscribers.list`.
`email_address`	`string`	Yes	An email address. Kit normalizes its case, and returns an existing subscriber rather than creating a duplicate.
`first_name`	`string \| null`	No	—
`fields`	`Record<string, string>`	No	—

Output

Name	Type	Required	Description
`subscriber`	`object`	Yes	—
`warnings`	`string[] \| null`	No	Custom field keys Kit ignored because it did not recognise them.

subscriber full type

{
  id: number,
  first_name?: string | null,
  email_address: string,
  state?: string | null,
  created_at?: string | null,
  canceled_at?: string | null,
  fields?: Record<string, string | null> | null,
  attribution?: {
    referrer?: string | null,
    utm_source?: string | null,
    utm_medium?: string | null,
    utm_campaign?: string | null,
    utm_term?: string | null,
    utm_content?: string | null,
    source_type?: string | null,
    source_name?: string | null,
    source_mechanism?: string | null,
    source_mechanism_id?: number | null
  } | null,
  location?: {
    city?: string | null,
    state?: string | null,
    country?: string | null,
    latitude?: number | null,
    longitude?: number | null,
    timezone?: string | null
  } | null,
  tags?: {
    id?: number | null,
    name?: string | null
  }[] | null
}

Overview

Plugins

Kit API reference

Account

get

Custom Fields

create

list

update

Forms

list

Subscribers

create

get

list

unsubscribe

update

Tags

create

list

tagSubscriber

untagSubscriber

update