Required dependencies

npm install superagent querystring

No native modules, no iOS pod install, no Android linking, no npx expo prebuild required. This is a pure Node.js library.

Project setup

1. Copy the source/ directory into your project, e.g. src/lib/sib-api-v3-sdk/.

2. No TypeScript declarations are shipped. If you use TypeScript, add a shim or install the community types:

   npm install --save-dev @types/superagent
   

   For the SDK itself, create src/lib/sib-api-v3-sdk/index.d.ts with declare const sdk: any; export = sdk; as a minimal workaround, or use // @ts-ignore on the require line.

3. Configure your API key via environment variable (do not hardcode):

   export SIB_API_KEY="your-sendinblue-api-key"
   

4. Wire the client in your entry point (CommonJS):

   const SibApiV3Sdk = require('./lib/sib-api-v3-sdk/index');
   const defaultClient = SibApiV3Sdk.ApiClient.instance;
   defaultClient.authentications['api-key'].apiKey = process.env.SIB_API_KEY;
   

5. For TypeScript projects using ts-node or compiled output, set "esModuleInterop": true and "allowSyntheticDefaultImports": true in tsconfig.json to avoid CJS/ESM interop issues.

6. If you use path aliases, add the following to tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "sib-sdk/*": ["src/lib/sib-api-v3-sdk/*"]
       }
     }
   }
   

Public API

ApiClient

const client: {
  instance: ApiClient;
  authentications: {
    'api-key': { apiKey: string; apiKeyPrefix?: string };
    'partner-key': { apiKey: string; apiKeyPrefix?: string };
  };
};

The singleton HTTP client that all API classes share. Set ApiClient.instance.authentications['api-key'].apiKey once at startup and every subsequent API call inherits the credential. Supports optional apiKeyPrefix for token-based auth schemes.

TransactionalEmailsApi

class TransactionalEmailsApi {
  sendTransacEmail(sendSmtpEmail: CreateSmtpEmail): Promise<CreateSmtpEmailResponse>;
  getEmailEventReport(opts?: object): Promise<GetEmailEventReport>;
  getSmtpTemplates(opts?: object): Promise<GetSmtpTemplates>;
}

Use this class to send one-off transactional emails (password resets, receipts, notifications) and to query SMTP delivery logs. Pass a CreateSmtpEmail model instance as the body. Returns a promise with the message ID on success.

ContactsApi

class ContactsApi {
  createContact(createContact: CreateContact): Promise<CreateUpdateContactModel>;
  getContacts(opts?: object): Promise<GetContacts>;
  updateContact(identifier: string, updateContact: UpdateContact): Promise<void>;
  deleteContact(identifier: string): Promise<void>;
  addContactToList(listId: number, contactEmails: AddContactToList): Promise<PostContactInfo>;
}

Use this class to manage the contacts database: create subscribers, update attributes, add to lists, and remove contacts. identifier is the contact's email address or numeric ID.

EmailCampaignsApi

class EmailCampaignsApi {
  createEmailCampaign(emailCampaigns: CreateEmailCampaign): Promise<CreateModel>;
  sendEmailCampaignNow(campaignId: number): Promise<void>;
  getEmailCampaigns(opts?: object): Promise<GetEmailCampaigns>;
  updateEmailCampaign(campaignId: number, emailCampaign: UpdateEmailCampaign): Promise<void>;
}

Use this class to build and dispatch bulk marketing campaigns. Create a campaign with template and recipient list IDs, then call sendEmailCampaignNow to dispatch immediately or schedule via scheduledAt in the create body.

Working examples

Scenario - Send a transactional email

Configure the client once, construct a CreateSmtpEmail model, and call sendTransacEmail. Suitable for triggered emails such as order confirmations.

const SibApiV3Sdk = require('./lib/sib-api-v3-sdk/index');

const defaultClient = SibApiV3Sdk.ApiClient.instance;
defaultClient.authentications['api-key'].apiKey = process.env.SIB_API_KEY!;

const api = new SibApiV3Sdk.TransactionalEmailsApi();
const sendSmtpEmail = new SibApiV3Sdk.SendSmtpEmail();

sendSmtpEmail.to = [{ email: 'recipient@example.com', name: 'Jane Doe' }];
sendSmtpEmail.sender = { name: 'My App', email: 'user@example.com' };
sendSmtpEmail.subject = 'Order Confirmed';
sendSmtpEmail.htmlContent = '<p>Your order has been confirmed.</p>';

api.sendTransacEmail(sendSmtpEmail)
  .then((data: any) => console.log('Sent, messageId:', data.messageId))
  .catch((err: any) => console.error('Error:', err.response?.text));

Scenario - Create a contact and add to a list

Create a new contact with custom attributes, then add them to an existing list by numeric list ID.

const SibApiV3Sdk = require('./lib/sib-api-v3-sdk/index');

const defaultClient = SibApiV3Sdk.ApiClient.instance;
defaultClient.authentications['api-key'].apiKey = process.env.SIB_API_KEY!;

const contactsApi = new SibApiV3Sdk.ContactsApi();

const createContact = new SibApiV3Sdk.CreateContact();
createContact.email = 'newuser@example.com';
createContact.attributes = { FIRSTNAME: 'Alice', LASTNAME: 'Smith' };
createContact.listIds = [5];

contactsApi.createContact(createContact)
  .then((data: any) => {
    console.log('Contact created, id:', data.id);
    const addToList = new SibApiV3Sdk.AddContactToList();
    addToList.emails = ['newuser@example.com'];
    return contactsApi.addContactToList(7, addToList);
  })
  .then(() => console.log('Added to list 7'))
  .catch((err: any) => console.error(err.response?.text));

Scenario - Create and send an email campaign

Build a campaign pointing to an existing template and recipient list, then dispatch it immediately.

const SibApiV3Sdk = require('./lib/sib-api-v3-sdk/index');

const defaultClient = SibApiV3Sdk.ApiClient.instance;
defaultClient.authentications['api-key'].apiKey = process.env.SIB_API_KEY!;

const campaignsApi = new SibApiV3Sdk.EmailCampaignsApi();
const campaignBody = new SibApiV3Sdk.CreateEmailCampaign();

campaignBody.name = 'Monthly Newsletter - June';
campaignBody.subject = 'June Update from MyApp';
campaignBody.sender = { name: 'MyApp Team', email: 'user@example.com' };
campaignBody.templateId = 12;
campaignBody.recipients = { listIds: [3] };

campaignsApi.createEmailCampaign(campaignBody)
  .then((data: any) => {
    console.log('Campaign created, id:', data.id);
    return campaignsApi.sendEmailCampaignNow(data.id);
  })
  .then(() => console.log('Campaign dispatched'))
  .catch((err: any) => console.error(err.response?.text));

File walkthrough

• index.js - Single barrel that requires and re-exports every API class and model; start every import from here.
• ApiClient.js - Handles HTTP transport, auth header injection, query param serialization, and superagent request lifecycle.
• api/AccountApi.js - Wraps GET /account to retrieve plan and usage information.
• api/ContactsApi.js - Full contact CRUD: create, read, update, delete, list management, and attribute definitions.
• api/TransactionalEmailsApi.js - Send SMTP emails, manage templates, query delivery events and statistics.
• api/TransactionalSMSApi.js - Send one-off SMS messages and retrieve SMS logs.
• api/EmailCampaignsApi.js - Campaign lifecycle: create, update, schedule, send, and fetch reports.
• api/SMSCampaignsApi.js - SMS campaign creation, scheduling, and statistics.
• api/SendersApi.js - Manage verified sender addresses and dedicated IPs.
• api/WebhooksApi.js - Register and manage event webhooks for email and SMS events.
• api/ResellerApi.js - Child account creation, credit allocation, and plan management for resellers.
• api/MasterAccountApi.js - Sub-account provisioning and SSO token generation.
• api/CompaniesApi.js - CRM company record CRUD.
• api/DealsApi.js - CRM deal pipeline CRUD.
• api/NotesApi.js - CRM note attachment to contacts, companies, or deals.
• api/TasksApi.js - CRM task creation and status tracking.
• api/FilesApi.js - Upload and retrieve files attached to CRM records.
• api/ConversationsApi.js - Push messages into live chat conversation threads.
• api/InboundParsingApi.js - Configure inbound email parsing routes.
• api/ProcessApi.js - Poll status of long-running asynchronous API processes.
• model/ - Plain JS classes with constructFromObject factory methods, matching every request and response schema in the API.

Common pitfalls and fixes

• SIB_API_KEY not set at startup: ApiClient.instance is a module-level singleton; set the key before constructing any API class, not after.
• CJS/ESM interop in TypeScript: The SDK uses module.exports; set "esModuleInterop": true in tsconfig.json and use require() or import * as SibApiV3Sdk from '...'.
• superagent version mismatch: The SDK was written against superagent v5/v6. If your project pins v8+, check for breaking changes in callback vs. promise API; downgrade to superagent@6 if errors appear.
• Unhandled promise rejections expose raw HTTP body: Wrap calls in .catch(err => err.response.text) to read the JSON error from SendinBlue rather than the raw Error object.
• listIds must be numeric arrays, not strings: Passing listIds: ['3'] silently fails validation; always use listIds: [3].
• Rate limiting (HTTP 429): The free tier allows 300 emails/day and limited API calls/minute. Implement exponential backoff; the response headers include Retry-After.

Vibe-coding prompt template

I have dropped the SendinBlue API v3 Node.js SDK source into `src/lib/sib-api-v3-sdk/`.
The entry point is `src/lib/sib-api-v3-sdk/index.js`.
The upstream npm package this source corresponds to is `user@example.com`.
There is a USAGE.md file in this block that documents all real exports, working code
examples, and setup steps.

Please help me integrate this SDK into my existing Node.js/TypeScript project step by step:

1. Read USAGE.md and the file listing under `src/lib/sib-api-v3-sdk/` to understand
   what is available.
2. Add `superagent` and `querystring` to my package.json dependencies.
3. Create a singleton setup module at `src/services/sibClient.ts` that reads
   `SIB_API_KEY` from `process.env` and configures `ApiClient.instance`.
4. Implement [describe your specific feature, e.g. "a function that sends a
   transactional email given a recipient address, subject, and HTML body"].
5. Use only the real classes from `src/lib/sib-api-v3-sdk/index.js` - do not
   invent class or method names. Refer to USAGE.md for correct signatures.
6. Add error handling that logs `err.response.text` for API errors.
7. Show me the final files and any tsconfig.json changes needed.

License and credit

The upstream SDK is published under the MIT License (see source/LICENSE if present, or refer to the npm package page).

Upstream package: user@example.com by SendinBlue. Migration target: @getbrevo/brevo on GitHub at github.com/getbrevo/brevo-node.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free