> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to eSputnik

The eSputnik connector lets your AI agent act in each user's eSputnik account. Each user connects their own eSputnik API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 59 tools.

**Authentication:** API Key
**Categories:** Marketing, Communication
**Tools:** 59: 31 read, 21 write, 7 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=ESPUTNIK)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the eSputnik connection

   In **AgentKit > Connections**, create an eSputnik connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'esputnik_account_info_get',
  toolInput: {},
  connector: 'esputnik',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="esputnik_account_info_get",
    tool_input={},
    connection_name="esputnik",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `esputnik_account_info_get`

Get Account Info · Read-only

Get account details. Returns the organization name, account email and settings. Use this to confirm the connection.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_additional_fields_list`

List Additional Fields · Read-only

List contact additional field groups and fields. Returns fields with id, name and type. Use this to fill contact fields.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_address_books_list`

List Address Books · Read-only

List address books (catalogs). Returns address books with id, name and field groups. Use this to find the address book ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_balance_get`

Get Balance · Read-only

Get the organization balance. Returns balance, currency and credit. Use this before large sends.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_balance_history_get`

Get Billing History · Read-only

Get the organization billing history for a date range. Returns charges and payments. Use this for spend reporting.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `date_from` (`string`, optional): The initial date for the billing history. The date values are passed in the ISO_8061 format. Date format: YYYY-MM-DD. Defaults to Beginning of today. Example: 2026-01-01.
- `date_to` (`string`, optional): The end date for the billing history. The date values are passed in the ISO_8061 format. Date format: YYYY-MM-DD. Defaults to Now. Example: 2026-01-01.

Example input: `{}`

### `esputnik_broadcast_get`

Get Broadcast · Read-only

Get one broadcast. Returns its message, segments, schedule and status. Use this to check a campaign.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): Broadcast ID. Example: 6789012.

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `esputnik_broadcasts_list`

List Broadcasts · Read-only

List broadcasts (campaign sends). Returns broadcasts with id, name, message, segments, status and send date. Use esputnik_broadcast_get for one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): Maximum number of messages to return (maximum 500). Defaults to 10. Example: 1.
- `startindex` (`integer`, optional): Index of the first message to return from search results Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_contact_get`

Get Contact · Read-only

Get one contact by ID. Returns the contact with names, channels, address, additional fields and segments. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): id. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_contact_messages_get`

Get Contact Message History · Read-only

Get the messages sent to one contact. Returns messages with id, channel, subject, status and send time. Use this to see what a contact received.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `date_from` (`string`, required): The initial date or date and time of the history period. The date/time values are passed in the ISO_8061 format. Date format: YYYY-MM-DD Date with time format: YYYY-MM-DDTHH:mm. Example: 2026-01-01.
- `date_to` (`string`, required): The final date or date amd time of the history period. The date/time values are passed in the ISO_8061 format. Date format: YYYY-MM-DD Date with time format: YYYY-MM-DDTHH:mm. Example: 2026-01-01.
- `channel_types` (`string`, optional): Comma separated list of user messages channel types that will be included to the response. Example: email,sms.
- `contact_id` (`integer`, optional): Contact ID number (either contactId, or externalCustomerId, or email, or phone number must be specified). Example: 1.
- `email` (`string`, optional): Contact's email address (either contactId, or externalCustomerId, or email, or phone number must be specified). Example: jane@example.com.
- `external_customer_id` (`string`, optional): External Customer ID (either contactId, or externalCustomerId, or email, or phone number must be specified). Example: CUST-1001.
- `maxrows` (`integer`, optional): Max number of items in the response. Default value is 10. Maximum value is 100. Example: 1.
- `offset` (`integer`, optional): Offset from the first item. For pagination purposes. Defaults to 0. Example: 0.
- `phone` (`string`, optional): Contact's phone number (either contactId, or externalCustomerId, or email, or phone number must be specified). Example: 380501234567.

Example input: `{"date_from":"<date_from>","date_to":"<date_to>"}`

### `esputnik_contact_subscriptions_get`

Get Contact Subscriptions · Read-only

Get the subscription categories a contact is subscribed to. Returns the list of subscription keys. Use this before esputnik_contact_subscriptions_update.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Contact ID. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_contacts_activity_get`

Get Contacts Activity · Read-only

Get message activity (delivered, opened, clicked, unsubscribed...) of contacts over a date range. Returns activity rows with contact, channel, status and timestamps. Use this for engagement reporting.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `date_from` (`string`, required): Initial date and time of the period you want to get the contact activity for. Example: 2026-01-01.
- `date_to` (`string`, required): Final date and time of the period you want to get the contact activity for. Example: 2026-01-01.
- `activity_status` (`string`, optional): Activity status (DELIVERED, UNDELIVERED, READ, UNSUBSCRIBED, CLICKED, SPAM). One of: DELIVERED, UNDELIVERED, READ, UNSUBSCRIBED, CLICKED, SPAM. Example: DELIVERED. One of: `DELIVERED`, `UNDELIVERED`, `READ`, `UNSUBSCRIBED`, `CLICKED`, `SPAM`.
- `email` (`string`, optional): Email address. Example: jane@example.com.
- `maxrows` (`integer`, optional): Max number of activity entries in response. Defaults to 25000. Example: 1.
- `message_tag` (`string`, optional): Message tag. Example: promo.
- `mob_push_token` (`string`, optional): Mob Push token. Example: apns-token-123.
- `offset` (`string`, optional): Last found contact activity offset in previous search results. It is used to continue search. Example: 0.
- `sms` (`string`, optional): Contact's phone number. Example: 380501234567.
- `telegram_token` (`string`, optional): Telegram token. Example: tg-123456.
- `web_push_token` (`string`, optional): Web Push token. Example: fcm-token-123.

Example input: `{"date_from":"<date_from>","date_to":"<date_to>"}`

### `esputnik_contacts_import_status_get`

Get Contact Import Status · Read-only

Get the status of a bulk contact import. Returns status and counts of processed and failed contacts. Use this after esputnik_contacts_upsert.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `session_id` (`string`, required): Async session identifier. Example: 8f2c1a3e-5b7d-4e9f-a1c2-3d4e5f6a7b8c.

Example input: `{"session_id":"<session_id>"}`

### `esputnik_contacts_search`

Search Contacts · Read-only

Search contacts by email, phone, name or external ID, or list them page by page. Returns contacts with id, firstName, lastName, channels, fields, groups and addressBookId. Use this to find a contact. Use esputnik_contact_get for one by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `email` (`string`, optional): Contact's email address. Example: jane@example.com.
- `external_customer_id` (`string`, optional): External contact ID. Example: CUST-1001.
- `firstname` (`string`, optional): Contact first name. Example: Jane.
- `lastname` (`string`, optional): Contact last name. Example: Doe.
- `maxrows` (`integer`, optional): Maximum number of returned contacts (max 500). Defaults to 500. Example: 1.
- `sms` (`string`, optional): Contact's phone number. Example: 380501234567.
- `sort_by` (`string`, optional): Possible value is 'contactId'. Only actual for searches without conditions. By default, the date of contact update is used for the search. If this parameter is used, sorting is done by contactId. Using this parameter allows you to upload contacts faster. Example: contactId.
- `startindex` (`integer`, optional): The number of the first contact returned in the search results. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_email_interfaces_list`

List Email Senders · Read-only

List the email sender addresses configured for the organization. Returns sender emails and names. Use this for the from field of esputnik_email_send.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_email_message_get`

Get Email Message · Read-only

Get one saved email message template. Returns the template's content and settings. Use this to read a template.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Email message id. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_email_message_view_link_get`

Get Email View Link · Read-only

Get a web link that shows an email template. Returns the view URL. Use this to preview a template.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Message ID. Example: 123456789.

Example input: `{"id":"<id>"}`

### `esputnik_email_messages_search`

Search Email Messages · Read-only

Search saved email message templates by name or tag. Returns messages with id, name, tags and (for email) subject. Use this to find a template ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): Maximum number of messages to return (max. 500). Defaults to 500. Example: 1.
- `search` (`string`, optional): Search condition (a part of the message name or a tag). Defaults to. Example: welcome.
- `startindex` (`integer`, optional): The index of the first message to return from the search result. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_message_status_get`

Get Message Status · Read-only

Get the delivery status of sent messages by request IDs. Returns status (e.g. DELIVERED, OPENED, CLICKED, FAILED) per request ID. Use this after a send tool.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`string`, optional): ID of sent message. This field is present if message was successfully queued for sending. Example: c2b4f2a1-1111-2222-3333-444455556666.

Example input: `{}`

### `esputnik_mobilepush_message_get`

Get Mobile Push Message · Read-only

Get one saved mobile push message template. Returns the template's content and settings. Use this to read a template.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Mobile push message id. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_mobilepush_messages_search`

Search Mobile Push Messages · Read-only

Search saved mobile push message templates by name or tag. Returns messages with id, name, tags and (for email) subject. Use this to find a template ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): Maximum number of messages to return (not more than 500). Defaults to 500. Example: 1.
- `search` (`string`, optional): Search condition (part of the message name or a tag). Example: welcome.
- `startindex` (`integer`, optional): Index of the first returned message from the search results. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_promocodes_count`

Count Promo Codes · Read-only

Count available promotional codes. Returns the number of available codes. Use this to check the pool.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `active_due_days` (`integer`, optional): The number of days left for the promo codes to remain active (activeDueDays=7 means the promo code remains active during the next 7 days, starting from tomorrow). Example: 1.
- `discount` (`integer`, optional): Promo code discount amount. Example: 1.
- `type` (`string`, optional): Promo code type. Example: PERCENT.

Example input: `{}`

### `esputnik_promocodes_get`

Get Promo Codes · Read-only

Get promotional codes, optionally reserving them for use. Returns promo codes with type, discount and expiration. Use this to hand out codes.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `active_due_days` (`integer`, optional): The days left for promo codes to remain active (activeDueDays=7 means: the promo code remains active for the following 7 days, starting from tomorrow). Example: 1.
- `discount` (`integer`, optional): Discount received with the promo code. Example: 1.
- `in_use` (`boolean`, optional): When 'true', the promo code has been used, when 'false', the promo code has not been used. Example: true.
- `type` (`string`, optional): Promo code type. Example: PERCENT.

Example input: `{}`

### `esputnik_segment_contacts_list`

List Segment Contacts · Read-only

List contacts in a segment. Returns contacts with id, channels and fields. Use this to read a segment's members.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Segment ID. Example: 123456789.
- `asc` (`boolean`, optional): Sort in ascending (ASC) or descending (DESC) order. Defaults to true. Example: true.
- `maxrows` (`integer`, optional): Maximum number of contacts to return (max. 500). Defaults to 500. Example: 1.
- `order_by_ts` (`boolean`, optional): Order by the time of addition to the segment. Defaults to false. Example: true.
- `startindex` (`integer`, optional): The index of the first contact returned from the search result. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{"id":123456789}`

### `esputnik_segments_list`

List Segments · Read-only

List contact segments (groups). Returns segments with id, name and type (static or dynamic). Use this for segment IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): Maximum number of segments to be returned (max. 500). Defaults to 500. Example: 1.
- `name` (`string`, optional): name. Example: sk-test welcome.
- `startindex` (`integer`, optional): The index of the first segment returned from the search result. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_sms_interfaces_list`

List SMS Senders · Read-only

List the SMS sender names (alpha names). Returns sender names. Use this for esputnik_sms_send.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_sms_message_get`

Get SMS Message · Read-only

Get one saved SMS message template. Returns the template's content and settings. Use this to read a template.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): SMS message ID. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_sms_messages_search`

Search SMS Messages · Read-only

Search saved SMS message templates by name or tag. Returns messages with id, name, tags and (for email) subject. Use this to find a template ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): maxrows. Defaults to 500. Example: 1.
- `search` (`string`, optional): Search condition (a part of the message name or a tag). Example: welcome.
- `startindex` (`integer`, optional): startindex. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_subscriptions_list`

List Subscription Categories · Read-only

List the organization's subscription categories. Returns subscription keys and names. Use this for esputnik_contact_subscriptions_update.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `esputnik_viber_message_get`

Get Viber Message · Read-only

Get one saved Viber message template. Returns the template's content and settings. Use this to read a template.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Viber message ID. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_viber_messages_search`

Search Viber Messages · Read-only

Search saved Viber message templates by name or tag. Returns messages with id, name, tags and (for email) subject. Use this to find a template ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): Maximum number of messages to return (not more than 500). Defaults to 500. Example: 1.
- `search` (`string`, optional): Search condition (part of the message name or a tag). Example: welcome.
- `startindex` (`integer`, optional): Index of the first returned message from the search results. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_workflows_list`

List Workflows · Read-only

List automation workflows. Returns workflows with id, name and status. Use this to see automations.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `maxrows` (`integer`, optional): Maximum number of workflows to be returned (max. 500). Defaults to 500. Example: 1.
- `name` (`string`, optional): name. Example: sk-test welcome.
- `startindex` (`integer`, optional): The index of the first workflow returned from the search result. Numbering starts at 1. Defaults to 1. Example: 1.

Example input: `{}`

### `esputnik_broadcast_create`

Create Broadcast · Write

Create a broadcast that sends a saved message to segments now or at a scheduled time. Returns the broadcast id. Use this to send a campaign. Use esputnik_broadcast_cancel to cancel a scheduled one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `groups` (`array`, required): groups. Example: [201234567]
- `message_id` (`string`, required): Message ID. Example: AB2489300.
- `app_id` (`string`, optional): Application ID. For mob push and telegram messages. Example: 8182a34b-9c87-4777-8de1-598f2df9de4f.
- `batch_interval_unit` (`string`, optional): The broadcasting speed management parameter—the time interval. One of: MINUTE, HOUR, DAY, MONTH. Example: MINUTE. One of: `MINUTE`, `HOUR`, `DAY`, `MONTH`.
- `batch_size` (`integer`, optional): The broadcasting speed management parameter, the number of messages per specified time interval. Example: 50.
- `domain` (`string`, optional): Broadcast domain. For web push messages. Example: SportsNewsUpdates.
- `excluded_groups` (`array`, optional): excluded groups. Example: [201234568]
- `start_date` (`string`, optional): The broadcast start date. Use the following format: "YYYY-MM-DDTHH:mm". If not specified, the broadcast starts immediately. Example: 2023-10-28T14:00.
- `title` (`string`, optional): Broadcast title. Example: Season's discounts.

Example input: `{"groups":[201234567],"message_id":"<message_id>"}`

### `esputnik_contact_subscribe`

Subscribe Contact · Write

Subscribe a contact (adds or updates it and triggers the subscription workflow, e.g. double opt-in). Returns the contact id. Use this for sign-up forms. Use esputnik_contact_upsert to save without the subscription event.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contact` (`object`, required): Contact for subscription. Example: {"firstName": "Jane", "lastName": "Doe", "channels": [{"type": "email", "value": "jane@example.com"}]}
- `form_type` (`string`, optional): The subscription form name. It allows you to use several independent subscription forms. All characters are acceptable, except: < ; ’ \ / | " ' ^ ? ! , >. Example: Newsletter subscription.
- `groups` (`array`, optional): The list of segment names where a new/updated contact will be added. Example: ["sk-test VIP"]
- `subscriptions` (`array`, optional): Subscription categories added for a contact. Example: ["newsletter", "promotions"]

Example input: `{"contact":{}}`

### `esputnik_contact_subscriptions_update`

Update Contact Subscriptions · Write

Replace a contact's subscription categories. Returns an empty response on success. Use this to manage preferences.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Contact ID. Example: 123456789.
- `subscriptions` (`array`, required): Subscription category keys. Example: ["newsletter", "promotions"]

Example input: `{"id":123456789,"subscriptions":["newsletter","promotions"]}`

### `esputnik_contact_update`

Update Contact · Write

Update a contact by ID. Returns an empty response on success. Use this to change a contact's fields.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Contact ID. Example: 123456789.
- `address` (`object`, optional): Contact's full address. Example: {"region": "Kyiv", "town": "Kyiv", "address": "1 Khreshchatyk St", "postcode": "01001"}
- `address_book_id` (`integer`, optional): Catalog ID. You can get the value using the /v1/addressbooks GET method. Optional parameter. Example: 1.
- `channels` (`array`, optional): You can add maximum two channels of the same type. It is necessary to specify at least one channel. Example: [{"type": "email", "value": "jane@example.com"}, {"type": "sms", "value": "380501234567"}]
- `contact_key` (`string`, optional): contact key. Example: jane@example.com.
- `external_customer_id` (`string`, optional): external customer id. Example: CUST-1001.
- `fields` (`array`, optional): Values of the additional fields of a contact. Example: [{"id": 12345, "value": "Gold"}]
- `first_name` (`string`, optional): Contact's first name. Example: John.
- `id_body` (`integer`, optional): Contact ID. Example: 123456789.
- `language_code` (`string`, optional): Language code. Optional parameter. Example: en.
- `last_name` (`string`, optional): Contact's last name. Example: Smith.
- `market_id` (`string`, optional): Market ID. Optional parameter. Up to 64 characters. Allowed: [a–zA-Z0–9-_]. Example: ua-main.
- `time_zone` (`string`, optional): Time zone. Optional parameter. See TZ database name. Example: Europe/Kyiv.

Example input: `{"id":123456789}`

### `esputnik_contact_upsert`

Add or Update Contact · Write

Add a contact or update the existing one with the same email, phone or external ID. Returns the contact id. Use this to save one contact. Use esputnik_contact_subscribe to subscribe with double opt-in.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `address` (`object`, optional): Contact's full address. Example: {"region": "Kyiv", "town": "Kyiv", "address": "1 Khreshchatyk St", "postcode": "01001"}
- `address_book_id` (`integer`, optional): You can get the info about catalogs using the /v1/addressbooks GET method. Example: 7200.
- `channels` (`array`, optional): The list of media channels. Example: [{"type": "email", "value": "jane@example.com"}, {"type": "sms", "value": "380501234567"}]
- `contact_key` (`string`, optional): Contact's key. Example: jane@example.com.
- `external_customer_id` (`string`, optional): External contact id. Example: CUST-1001.
- `fields` (`array`, optional): Values of the additional fields for a contact. Example: [{"id": 12345, "value": "Gold"}]
- `first_name` (`string`, optional): Contact’s first name. The following rules apply to character usage: - Max length: 40 symbols. - Letters from any alphabet are allowed (Unicode characters). - Three words longer than 3 characters and three words with a maximum of 3 characters are allowed. - Up to 3 digits are allowed. - Special characters are not allowed, except for: -- Apostrophes ''ʼ´ʹʻʽʾʿˈˊˮʹ΄՚᾽᾿'‛′‵Ꞌꞌ＇ (only inside words) -- Hyphen - (only inside words) -- One dot at the end of words having max 3 characters. Example: Jr. - Names consisting only of numbers and special characters are not allowed.
- `groups` (`array`, optional): The list of the static segments where the contact is present. Used only when receiving contacts. Example: [{"name": "sk-test VIP"}]
- `id` (`integer`, optional): Contact ID. Example: 123456789.
- `language_code` (`string`, optional): Language code for the contact. Example: en.
- `last_name` (`string`, optional): Contact’s last name. The following rules apply to character usage: - Max length: 40 symbols. - Letters from any alphabet are allowed (Unicode characters). - Three words longer than 3 characters and three words with a maximum of 3 characters are allowed. - Up to 3 digits are allowed. - Special characters are not allowed, except for: -- Apostrophes ''ʼ´ʹʻʽʾʿˈˊˮʹ΄՚᾽᾿'‛′‵Ꞌꞌ＇ (only inside words) -- Hyphen - (only inside words) -- One dot at the end of words having max 3 characters. Example: Jr. - Names consisting only of numbers and special characters are not allowed.
- `market_id` (`string`, optional): Market ID. Optional parameter. Up to 64 characters. Allowed: [a–zA-Z0–9-_]. Example: ua-main.
- `time_zone` (`string`, optional): The contact's time zone. See TZ database name. Example: Europe/Kyiv.

Example input: `{}`

### `esputnik_contacts_upsert`

Add or Update Contacts · Write

Add or update up to 3000 contacts in one request, deduplicating by a chosen key, and optionally add them to segments. Returns asyncSessionId to check with esputnik_contacts_import_status_get. Use this for bulk sync. Use esputnik_contact_upsert for one contact.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contacts` (`array`, required): The list of contacts that will be added or updated (max. 3000). If this array of objects contains externalCustomerId, the search uses externalCustomerId and ignores dedupeOn. Example: [{"firstName": "Jane", "lastName": "Doe", "channels": [{"type": "email", "value": "jane@example.com"}], "externalCustomerId": "CUST-1001"}]
- `dedupe_on` (`string`, required): The field for determining the contact uniqueness. Important the field set as dedupeOn will not be updated. One of: email, sms, push, email_or_sms, id, externalCustomerId, fieldId. Example: email. One of: `email`, `sms`, `push`, `email_or_sms`, `id`, `externalCustomerId`, `fieldId`.
- `contact_fields` (`array`, optional): The list of contacts’ fields to be updated. All the contact fields will be updated if this parameter is not specified. The fields will be updated with the ‘null’ value if no data for updating is transmitted. Example: ["firstName", "lastName", "email"]
- `custom_fields_ids` (`array`, optional): The list of the custom field IDs to be updated. The custom fields are updated if their IDs are in this list. This field is required when a contact is updated. Example: [12345]
- `event_key_for_new_contacts` (`string`, optional): The event type identification key. An event of corresponding type is generated for each contact. If the system does not have an event type with such a key, a new event type is created. All characters are allowed, except < ; ’ \ / | " ' ^ ? ! , > Max length: 100 symbols. Example: contactImported.
- `field_id` (`integer`, optional): The field for determining the contact uniqueness. This field is taken into account when dedupeOnProperty has the fieldId value. Example: 1.
- `group_names` (`array`, optional): The list of the segment names where the new/updated contacts will be added to. Example: ["sk-test VIP"]
- `group_names_exclude` (`array`, optional): The list of the segment names where the new/updated contacts will be excluded from. Example: ["Inactive"]
- `restore_deleted` (`boolean`, optional): Choose either to restore the previously deleted contacts or not. Example: true.

Example input: `{"contacts":[],"dedupe_on":"email"}`

### `esputnik_email_message_create`

Create Email Message · Write

Create a email message template. Returns the created message with its id. Use this to add a reusable template.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Required parameter. Sender name and email address, e.g. "from": "\"name\" <info@test.com>". Example: "Acme Store" <info@example.com>.
- `html_text` (`string`, required): Message HTML code. Example: <html><body>Welcome, $!data.get('firstName')!
</body></html>.
- `name` (`string`, required): Message name. Example: sk-test welcome.
- `subject` (`string`, required): Message subject. Example: Thanks for signing up.
- `amp_html` (`string`, optional): Message AMP code. Example: <!doctype html><html amp4email><head></head><body>Hi</body></html>.
- `css` (`string`, optional): Message styles. Example: p { color: #333; }
- `id` (`integer`, optional): Message ID. Example: 123456789.
- `language_code` (`string`, optional): Language code. Example: en.
- `languages` (`array`, optional): An array with the language codes for multilingual messages. Available for the GET method only. Example: ["en"]
- `raw_html` (`string`, optional): Message HTML code without styles. Example: Welcome to Acme!
.
- `subscriptions_keys` (`array`, optional): Subscription categories keys, assigned to a message. Example: ["newsletter"]
- `tags` (`array`, optional): List of tags. Example: ["welcome", "sk-test"]
- `template` (`boolean`, optional): template. Example: true.
- `translations` (`array`, optional): The array of the language versions for the current message. Available for the GET method only. Example: [{"languageCode": "uk", "subject": "Ласкаво просимо"}]
- `updated_date` (`string`, optional): Message updated date. Example: 2026-01-01T00:00:00Z.

Example input: `{"from":"from","html_text":"<html_text>","name":"<name>","subject":"<subject>"}`

### `esputnik_email_message_update`

Update Email Message · Write

Update a email message template. Returns an empty response on success. Use this to change a template.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Required parameter. Sender name and email address, e.g. "from": "\"name\" <info@test.com>". Example: "Acme Store" <info@example.com>.
- `html_text` (`string`, required): Message HTML code. Example: <html><body>Welcome, $!data.get('firstName')!
</body></html>.
- `id` (`integer`, required): Email message id. Example: 123456789.
- `name` (`string`, required): Message name. Example: sk-test welcome.
- `subject` (`string`, required): Message subject. Example: Thanks for signing up.
- `amp_html` (`string`, optional): Message AMP code. Example: <!doctype html><html amp4email><head></head><body>Hi</body></html>.
- `css` (`string`, optional): Message styles. Example: p { color: #333; }
- `id_body` (`integer`, optional): Message ID. Example: 123456789.
- `language_code` (`string`, optional): Language code. Example: en.
- `languages` (`array`, optional): An array with the language codes for multilingual messages. Available for the GET method only. Example: ["en"]
- `raw_html` (`string`, optional): Message HTML code without styles. Example: Welcome to Acme!
.
- `subscriptions_keys` (`array`, optional): Subscription categories keys, assigned to a message. Example: ["newsletter"]
- `tags` (`array`, optional): List of tags. Example: ["welcome", "sk-test"]
- `template` (`boolean`, optional): template. Example: true.
- `translations` (`array`, optional): The array of the language versions for the current message. Available for the GET method only. Example: [{"languageCode": "uk", "subject": "Ласкаво просимо"}]
- `updated_date` (`string`, optional): Message updated date. Example: 2026-01-01T00:00:00Z.

Example input: `{"from":"from","html_text":"<html_text>","id":123456789,"name":"<name>","subject":"<subject>"}`

### `esputnik_email_send`

Send Email · Write

Send a one-off email (your own HTML and subject) to one or more addresses. Returns results with a requestId per recipient for esputnik_message_status_get. Use this for transactional emails you compose. Use esputnik_message_send_prepared for a saved template.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `emails` (`array`, required): The list of recipients. Example: ["jane@example.com"]
- `from` (`string`, required): Sender address (enter one of the valid sender addresses). Address format: "\"name\" <test@mail.com>". Example: "Acme Store" <info@example.com>.
- `html_text` (`string`, required): Message HTML code. Example: <html><body>Welcome, $!data.get('firstName')!
</body></html>.
- `subject` (`string`, required): Message subject. Example: Seasonal sale.
- `amp_html_text` (`string`, optional): Message AMP HTML code. Example: <!doctype html><html amp4email><head></head><body>Hi</body></html>.
- `external_request_id` (`string`, optional): External request ID. It is the same for all the recipients. Example: order-1001-confirmation.
- `plain_text` (`string`, optional): Version of the message in plain text. Example: Explore our new collection.
- `skip_personalisation` (`boolean`, optional): Skip the application of personalization to the message. Example: true.
- `subscriptions_keys` (`array`, optional): Array of subscription category keys added to the message. Example: ["newsletter"]
- `tags` (`array`, optional): The list of tags assigned to the message. Example: ["welcome", "sk-test"]
- `track_urls` (`boolean`, optional): The parameter determines whether to track links in the message or not. The default value is ‘true’. Example: true.

Example input: `{"emails":["jane@example.com"],"from":"Acme Store","html_text":"<html_text>","subject":"<subject>"}`

### `esputnik_event_generate`

Generate Event · Write

Send a custom event (e.g. a cart abandonment or a password reset) for a contact to trigger workflows. Returns an empty response on success. Use this to trigger automations.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `event_type_key` (`string`, required): Unique identifier for the event type, e.g., PageViewed. Example: EventName.
- `params` (`object`, optional): An objects — key-value pairs containing contact identifiers (required) and event-specific parameters (optional). Example: {"email": "jane@example.com", "cartTotal": "49.90"}

Example input: `{"event_type_key":"<event_type_key>"}`

### `esputnik_message_send_prepared`

Send Prepared Message · Write

Send a saved message template (email, SMS, Viber, push...) to recipients, filling template parameters per recipient. Returns results with a requestId per recipient. Use this to send a template from esputnik_email_messages_search or similar.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`integer`, required): Message ID. Example: 123456789.
- `recipients` (`array`, required): recipients. Example: [{"locator": "jane@example.com", "jsonParam": "{\"orderNumber\": \"1001\"}"}]
- `email` (`boolean`, optional): Message type. true for email, false for other media-channels. Example: true.
- `from_name` (`string`, optional): Sender name. For email, indicate the sender name only, without an email address. The sender's email address selected in the message is used. For SMS, use the alphanumeric sender ID. If the parameter is not indicated, the sender name selected in the message is used. Example: Acme Store.

Example input: `{"id":123456789,"recipients":[{"locator":"jane@example.com","jsonParam":"{\"orderNumber\": \"1001\"}"}]}`

### `esputnik_orders_add`

Add Orders · Write

Add or update orders (with items, status and totals) for revenue reporting and order-based workflows. Returns results per order. Use this to sync orders from your store.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `orders` (`array`, optional): orders. Example: [{"externalOrderId": "1001", "externalCustomerId": "CUST-1001", "totalCost": 49.9, "status": "INITIALIZED", "date": "2026-01-15T10:00:00", "currency": "EUR",...

Example input: `{}`

### `esputnik_products_upsert`

Add or Update Products · Write

Add or update products in the product feed. Returns results per product. Use this to sync the catalog used in recommendations.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `language_code` (`string`, optional): Default language for top-level product fields. Example: en.
- `products` (`array`, optional): Products to create or update. Example: [{"id": "SKU-123"}]

Example input: `{}`

### `esputnik_segment_contacts_attach`

Add Contacts to Segment · Write

Add contacts to a static segment. Returns an empty response on success. Use esputnik_segment_contacts_detach to remove them.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`integer`, required): id. Example: 123456789.
- `contact_ids` (`array`, optional): The list of attach/detach contact ids to static group (max. 500). Example: [123456789, 123456790]
- `external_customer_ids` (`array`, optional): The list of attach/detach external contacts ids to static group (max. 500). Example: ["CUST-1001", "CUST-1002"]

Example input: `{"id":123456789}`

### `esputnik_segment_contacts_detach`

Remove Contacts from Segment · Write

Remove contacts from a static segment. Returns an empty response on success. Use this to clean up a segment.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`integer`, required): Segment ID. Example: 123456789.
- `contact_ids` (`array`, optional): The list of attach/detach contact ids to static group (max. 500). Example: [123456789, 123456790]
- `external_customer_ids` (`array`, optional): The list of attach/detach external contacts ids to static group (max. 500). Example: ["CUST-1001", "CUST-1002"]

Example input: `{"id":123456789}`

### `esputnik_sms_message_create`

Create SMS Message · Write

Create a SMS message template. Returns the created message with its id. Use this to add a reusable template.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Sender name. Example: "Acme Store" <info@example.com>.
- `name` (`string`, required): Message name. Example: sk-test welcome.
- `text` (`string`, required): Message text. Example: Your order 1001 has shipped.
- `id` (`integer`, optional): Message ID. Example: 123456789.
- `language_code` (`string`, optional): Language code. Example: en.
- `languages` (`array`, optional): An array with the language codes for multilingual messages. Available for the GET method only. Example: ["en"]
- `subscriptions_keys` (`array`, optional): Subscription categories keys, assigned to a message. Example: ["newsletter"]
- `tags` (`array`, optional): List of tags. Example: ["welcome", "sk-test"]
- `track_urls` (`boolean`, optional): The parameter determines whether to track links in a message or not. The default value is ‘false’. Example: true.
- `translations` (`array`, optional): An array with translations to other languages. Available for the GET method only. Example: [{"languageCode": "uk", "subject": "Ласкаво просимо"}]

Example input: `{"from":"Acme Store","name":"<name>","text":"<text>"}`

### `esputnik_sms_message_update`

Update SMS Message · Write

Update a SMS message template. Returns an empty response on success. Use this to change a template.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Sender name. Example: "Acme Store" <info@example.com>.
- `id` (`integer`, required): Sms message ID. Example: 123456789.
- `name` (`string`, required): Message name. Example: sk-test welcome.
- `text` (`string`, required): Message text. Example: Your order 1001 has shipped.
- `id_body` (`integer`, optional): Message ID. Example: 123456789.
- `language_code` (`string`, optional): Language code. Example: en.
- `languages` (`array`, optional): An array with the language codes for multilingual messages. Available for the GET method only. Example: ["en"]
- `subscriptions_keys` (`array`, optional): Subscription categories keys, assigned to a message. Example: ["newsletter"]
- `tags` (`array`, optional): List of tags. Example: ["welcome", "sk-test"]
- `track_urls` (`boolean`, optional): The parameter determines whether to track links in a message or not. The default value is ‘false’. Example: true.
- `translations` (`array`, optional): An array with translations to other languages. Available for the GET method only. Example: [{"languageCode": "uk", "subject": "Ласкаво просимо"}]

Example input: `{"from":"Acme Store","id":123456789,"name":"<name>","text":"<text>"}`

### `esputnik_sms_send`

Send SMS · Write

Send an SMS with your own text to one or more phone numbers from an SMS sender (alpha name). Returns results with a requestId per recipient. Use this for one-off SMS. Use esputnik_sms_interfaces_list for sender names.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Sender name. Enter one of the valid sender names. Example: "Acme Store" <info@example.com>.
- `text` (`string`, required): Message text. Example: Your order 1001 has shipped.
- `external_request_id` (`string`, optional): External request ID. It is the same for all the recipients. Example: order-1001-confirmation.
- `group_id` (`integer`, optional): Required parameter, if "phoneNumbers" is not specified. Segment ID to which the message will be sent. Example: 201234567.
- `phone_numbers` (`array`, optional): Required parameter, if "groupId" is not specified. Example: ["380501234567"]
- `subscriptions_keys` (`array`, optional): subscriptions keys. Example: ["newsletter"]
- `tags` (`array`, optional): The list of tags to be assigned to a message. Example: ["welcome", "sk-test"]
- `track_urls` (`boolean`, optional): The parameter determines whether to track links in a message or not. The default value is ‘false’. Example: true.

Example input: `{"from":"Acme Store","text":"<text>"}`

### `esputnik_unsubscribed_add`

Add Emails to Unsubscribed · Write

Add email addresses to the unsubscribed list. Returns an empty response on success. Use this to honor opt-outs.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `emails` (`array`, required): emails. Example: ["jane@example.com"]

Example input: `{"emails":["jane@example.com"]}`

### `esputnik_unsubscribed_remove`

Remove Emails from Unsubscribed · Write

Remove email addresses from the unsubscribed list. Returns an empty response on success. Use this only with the contact's consent.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `emails` (`array`, required): emails. Example: ["jane@example.com"]

Example input: `{"emails":["jane@example.com"]}`

### `esputnik_viber_send`

Send Viber Message · Write

Send a Viber message with your own text to one or more phone numbers. Returns results with a requestId per recipient. Use this for one-off Viber messages.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `text` (`string`, required): Message text. Example: Your order 1001 has shipped.
- `action` (`string`, optional): A clickable link embedded in a picture or in a button. Example: https://example.com/.
- `caption` (`string`, optional): caption. Example: Shop now.
- `carousel_items` (`array`, optional): Carousel items (2-5 items). When provided, img/action/caption are used only for SMS fallback. Example: [{"title": "Sneakers", "image": "https://example.com/1.png", "action": "https://example.com/p/1"}]
- `external_request_id` (`string`, optional): External request ID. It is the same for all the recipients. Example: order-1001-confirmation.
- `from` (`string`, optional): Sender's name. Required parameter if more than one sender is available. Example: "Acme Store" <info@example.com>.
- `group_id` (`integer`, optional): Required parameter . If "phoneNumbers" are not specified. Example: 2345678.
- `img` (`string`, optional): img. Example: https://example.com/promo.png.
- `phone_numbers` (`array`, optional): The list of the recipient phone numbers. Required parameter , if "groupId" is not specified. Example: ["380501234567"]
- `subscriptions_keys` (`array`, optional): subscriptions keys. Example: ["newsletter"]
- `tags` (`array`, optional): The list of tags to be assigned to a message. Example: ["welcome", "sk-test"]
- `template_id` (`string`, optional): Provider template ID for a transactional Viber message. Example: viber-tpl-001.
- `track_urls` (`boolean`, optional): The parameter determines whether to track links in a message or not. The default value is ‘true’. Example: true.
- `transactional` (`boolean`, optional): Whether the message is transactional. Defaults to false. Example: true.
- `ttl_seconds` (`integer`, optional): Message lifetime in seconds, the default value is day. Example: 36000.

Example input: `{"text":"<text>"}`

### `esputnik_broadcast_cancel`

Cancel Broadcast · Destructive

Cancel a scheduled broadcast. Returns an empty response on success. Use this before the scheduled send time.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): Broadcast ID. Example: 6789012.

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `esputnik_contact_delete`

Delete Contact · Destructive

Delete a contact by ID, optionally erasing all its data (GDPR). Returns an empty response on success. Use esputnik_contact_delete_by_external_id when you only have your own customer ID.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Contact ID. Example: 123456789.
- `erase` (`boolean`, optional): Permanent deletion of all contact's data: contact profile attributes, contact activity, web- and mobile tracking. It is not possible to recover the deleted data. Defaults to false. Example: true.

Example input: `{"id":123456789}`

### `esputnik_contact_delete_by_external_id`

Delete Contact by External ID · Destructive

Delete a contact by your external customer ID. Returns an empty response on success. Use this when you only have your own customer ID.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `erase` (`boolean`, optional): Permanent deletion of all contact data: contact profile attributes, contact activity, web- and mobile tracking. It is not possible to recover deleted data. Defaults to false. Example: true.
- `external_customer_id` (`string`, optional): external customer id. Example: CUST-1001.

Example input: `{}`

### `esputnik_email_message_delete`

Delete Email Message · Destructive

Delete a email message template. Returns an empty response on success. Use this to remove a template.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Email message id. Example: 123456789.

Example input: `{"id":123456789}`

### `esputnik_orders_delete`

Delete Orders · Destructive

Delete orders by external order IDs. Returns an empty response on success. Use this to remove test orders.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `external_order_id` (`string`, optional): ID of an order in the external system. Example: 1001.
- `from` (`string`, optional): Start date (inclusively). Example: "Acme Store" <info@example.com>.
- `to` (`string`, optional): End date (inclusively). Example: 2026-01-31.

Example input: `{}`

### `esputnik_products_delete`

Delete Products · Destructive

Delete products from the product feed. Returns an empty response on success. Use this to remove products.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `products` (`array`, optional): Products to delete. Example: [{"id": "SKU-123"}]
- `site_id` (`string`, optional): Client site/account identifier. Example: my_store.

Example input: `{}`

### `esputnik_sms_message_delete`

Delete SMS Message · Destructive

Delete a SMS message template. Returns an empty response on success. Use this to remove a template.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Sms message ID. Example: 123456789.

Example input: `{"id":123456789}`

## Related

Other Marketing connectors ([all 190](/agentkit/connectors/?category=marketing)):

- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools
- [Twitter / X](/agentkit/connectors/twitteroauth/): Scalekit connector, OAuth, 92 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
