Overview

• Rate limits. Message reads (getEmail, getViberMessage and the like) allow 500 requests an hour. Contact writes allow 200 a second, and addContact rejects the same contact twice within a minute (409). Calls that hit 429 are retried with backoff.
• Acknowledgements. Deletes, updates and segment or unsubscribe changes return undefined: eSputnik answers them with an empty body or a sentence such as “Email with id=‘42’ has been deleted”. A failure throws, and the error message carries eSputnik’s explanation when it sends one (“Contact not found”).
• Lists. List operations always return an array, including when eSputnik sends a single match as a bare object (email template search does) or an empty body.
• Not set up yet. site.getScript and site.getWebPushScript fail until a domain is registered, productFeeds.getProductFeedsConfiguration answers 404 until a feed is configured, and contacts.getGroupContacts works on static segments only.
• Contact fields. Additional fields are { id, value } pairs. List the ids with contacts.getAdditionalFields.
• Activity. contacts.contactActivity has to be enabled by eSputnik support first and keeps 90 days. contacts.contactMessages needs a contact identifier and a dateFrom less than a year old.
• Broadcasts. Broadcast ids are strings. broadcasts.createBroadcast sends a prepared message (messageId) to segment ids (groups).
• Event tokens. account.generateApiToken returns a bearer token for eSputnik’s event endpoints. Treat the result as a secret.
• No local sync. Data is read from eSputnik on each call; nothing is stored in the Corsair database.

• 108 typed API operations

​

Setup

npm install corsair @corsair-dev/esputnik

yarn add corsair @corsair-dev/esputnik

pnpm install corsair @corsair-dev/esputnik

bun add corsair @corsair-dev/esputnik

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { esputnik } from '@corsair-dev/esputnik';

export const corsair = createCorsair({
	plugins: [
		esputnik(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

esputnik()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'esputnik',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.esputnik.api.contacts.searchContacts({ email: 'ada@example.com', maxrows: 10 });

const tenant = corsair.withTenant('acme');
await tenant.esputnik.api.contacts.addContact({
	firstName: 'Ada',
	channels: [{ type: 'email', value: 'ada@example.com' }],
	fields: [{ id: 79814, value: 'gold' }],
});

​

What’s next