Overview

• Paid plans. Free accounts get “Free account is not eligible to use API!” from several calls, and the campaign API is for paid accounts only. Free accounts can insert 50 subscribers a day; paid accounts 10,000.
• Errors. The REST API answers HTTP 200 even when a call fails and puts the result in Result.StatusCode. The plugin throws when that code is not 2xx, with Enginemailer’s message (“API Key Not Found!”, “Email Existed”, “Campaign Not Found”).
• Subcategories and custom fields. Subscriber calls take subcategory ids from subscribers.getSubcategories and custom fields as { customfield_key, customfield_value } pairs keyed by subscribers.getCustomFields. Dates are dd MMM yyyy, checkbox values are joined with |, phone numbers carry the country code.
• Batch updates. subscribers.batchUpdateSubscribers takes up to 5,000 subscribers and returns a job ID; pass it to subscribers.batchUpdateStatus until the status is Completed.
• Campaigns. An account holds at most 200 campaigns. campaigns.listCampaigns lists undelivered campaigns only. campaigns.assignRecipientList assigns everyone (FilterBy: 1) or the subscribers in a set of subcategories (FilterBy: 2 with data). campaigns.sendCampaign mails the whole list at once and cannot be undone.
• N8N polling. n8n.newSubscribers, n8n.unsubscribedSubscribers and the other subscriber feeds return up to 50 records (limit) changed since lastpollingdate (yyyy-MM-dd HH:mm:ss, UTC). A filter set to All is left out of the request.
• N8N lookups. In live tests on a free account, n8n.findSubscriber, n8n.tagSubscriber, n8n.untagSubscriber, n8n.deactivateSubscriber and n8n.deleteN8nSubscriber answered “Email not exists.” for subscribers the REST API returned, even ones n8n.addOrUpdateSubscriber had just created. The subscribers operations worked for the same addresses.
• Transactional email. n8n.sendEmail sends one email right away, either html with a subject or a template_id. substitution_tags is a list of { Key, Value } pairs and cc_emails takes up to 10 addresses.
• No local sync. Data is read from Enginemailer on each call; nothing is stored in the Corsair database.

• 38 typed API operations

​

Setup

npm install corsair @corsair-dev/enginemailer

yarn add corsair @corsair-dev/enginemailer

pnpm install corsair @corsair-dev/enginemailer

bun add corsair @corsair-dev/enginemailer

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

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

enginemailer()

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

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.enginemailer.api.subscribers.get({ email: 'ada@example.com' });

const tenant = corsair.withTenant('acme');
await tenant.enginemailer.api.subscribers.insert({
	email: 'ada@example.com',
	subcategories: [12],
	customfields: [{ customfield_key: 'first_name', customfield_value: 'Ada' }],
	sourcetype: 'Website sign-up',
});

​

What’s next