Retently plugin

• Read permission allows GET only. Write permission adds POST and DELETE. A read-only key on a write route returns a 403 that the plugin reports as isPermissionError, which is a different problem from a 401 (a wrong or deleted key) and needs a new key rather than a retry.

• survey.send sends real email. It queues a survey through a transactional campaign and returns only status: 'queued'; there is no survey ID to cancel. A non-transactional campaign is a 400, an inactive one a 403, and an unknown one a 404. delay overrides the campaign’s own scheduling, so omit it to respect the campaign’s sending time frame.
• feedback.import changes your scores. Imported responses count toward NPS and trends, bucketed by response_date, so set it on a historical import or every response lands on the import day. They do not consume send quota and never fire webhooks. Only 200 responses go in one call, and a bad item fails alone: read details.failed for the reason instead of treating a 200 as all-or-nothing.
• The main comment and additional questions collide. A top-level comment fills the template’s isMain question, so also answering that question in additional_questions fails the item as ambiguous. Get question UUIDs from templates.get.
• RATING answers need their metric. An additional_questions entry of type RATING is scored on a metric (nps, csat, ces, star, thumbs, xsat or pmf); the plugin rejects one that omits it before the request is sent.
• Dates are not uniform. customers.list, feedback.list and outbox.list accept YYYY-MM-DD, an ISO 8601 date-time, or UNIX seconds - milliseconds silently resolve to a far-future date. reports.get is the exception: it takes YYYY-MM-DD only and rejects a full timestamp. feedback.import dates are ISO 8601 only.
• Paging stops at 1,000. limit is capped there, and data.pages tells you how many pages exist, so walk them rather than asking for everything at once.
• Unsubscribing and resubscribing are not symmetric. customers.resubscribe is idempotent and reports a status per contact: only resubscribed means a change, skipped means Retently refused for compliance (self-unsubscribed or hard-bounced), and suppressed: true warns that an account-level suppression still blocks delivery.
• Rate limit. 150 requests a minute. No Retry-After is documented, so the plugin backs off exponentially on a 429.

• 18 typed API operations

​

Setup

npm install corsair @corsair-dev/retently better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/retently better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/retently better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/retently better-sqlite3
bun add --dev @types/better-sqlite3

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

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

retently()

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

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.retently.api.feedback.list({ limit: 25, sort: '-createdDate' });

const tenant = corsair.withTenant('acme');
await tenant.retently.api.survey.send({
	campaign: '5a9d595701c85b37224ab2d0',
	subscribers: [{ email: 'john.smith@example.com', first_name: 'John', company: 'ACME' }],
});

​

What’s next