Official JavaScript & TypeScript SDK for MisarMail — works in Node.js, Next.js, Bun, and any JS runtime

The @misarmail/sdk npm package is the official JavaScript SDK for MisarMail. It ships with full TypeScript types, works in Node.js ≥18, Bun, Deno, and any runtime with native fetch.

Installation

npm install @misarmail/sdk
# or
pnpm add @misarmail/sdk
# or
yarn add @misarmail/sdk

Quick Start

import { MisarMailClient } from "@misarmail/sdk";

const client = new MisarMailClient("msk_your_key_here");

const result = await client.email.send({
  from: { email: "hello@yourapp.com", name: "Your App" },
  to: [{ email: "user@example.com" }],
  subject: "Welcome!",
  html: "<p>Welcome aboard!</p>",
});

console.log(result.message_id);

Configuration

The client takes the API key as the first argument and an options object as the second:

const client = new MisarMailClient(process.env.MISARMAIL_API_KEY!, {
  baseURL: "https://api.misar.io/mail/v1",
  maxRetries: 3,
  timeoutMs: 30_000,
});

Add the key to .env.local:

MISARMAIL_API_KEY=msk_your_key_here

Available Methods

Method	Description
`client.email.send(request)`	Send a transactional email
`client.contacts.list({params})`	List contacts with filters
`client.contacts.create(request)`	Create a contact
`client.contacts.delete(id)`	Delete a contact
`client.contacts.import(request)`	Bulk import/upsert contacts
`client.campaigns.list({params})`	List campaigns
`client.campaigns.create(request)`	Create a draft campaign
`client.campaigns.get(id)`	Get a campaign
`client.campaigns.update(id, request)`	Update a campaign
`client.campaigns.send(id)`	Send/schedule a campaign
`client.campaigns.delete(id)`	Delete a campaign
`client.templates.list({params})`	List email templates
`client.templates.create(request)`	Create a template
`client.templates.render(request)`	Render a template with merge data
`client.automations.list({params})`	List automation workflows
`client.automations.create(request)`	Create an automation
`client.automations.get(id)`	Get an automation
`client.automations.update(id, request)`	Update an automation
`client.automations.delete(id)`	Delete an automation
`client.automations.activate(id)`	Activate/deactivate an automation
`client.domains.list()`	List sending domains
`client.domains.create(request)`	Add a sending domain
`client.domains.get(id)`	Get a domain
`client.domains.verify(id)`	Trigger domain DNS verification
`client.domains.delete(id)`	Delete a domain
`client.aliases.list({params})`	List email aliases
`client.aliases.create(request)`	Create an alias
`client.aliases.get(id)`	Get an alias
`client.aliases.update(id, request)`	Update an alias
`client.aliases.delete(id)`	Delete an alias
`client.dedicatedIps.list()`	List dedicated IPs
`client.dedicatedIps.get(id)`	Get a dedicated IP
`client.dedicatedIps.create(request)`	Purchase a dedicated IP
`client.dedicatedIps.update(id, request)`	Update IP pool assignment
`client.abTests.list({params})`	List A/B tests
`client.abTests.create(request)`	Create an A/B test
`client.abTests.setWinner(id, variant)`	Manually set the winning variant
`client.abTests.selectWinner(id)`	Let MisarMail pick the winner
`client.sandbox.list({params})`	List sandbox sent messages
`client.sandbox.clear()`	Clear all sandbox messages
`client.inbound.list({params})`	List inbound routing rules
`client.inbound.create(request)`	Create an inbound route
`client.inbound.delete(id)`	Delete an inbound route
`client.inbound.delete(id)`	Delete an inbound route
`client.analytics.get(query)`	Get send/open/click/bounce analytics
`client.track.event(request)`	Track a custom event
`client.track.purchase(request)`	Track a purchase event
`client.keys.list()`	List API keys
`client.keys.create(request)`	Create an API key
`client.keys.delete(id)`	Delete an API key
`client.validate.email(address)`	Validate an email address
`client.webhooks.list({params})`	List webhooks
`client.webhooks.create(request)`	Create a webhook endpoint
`client.webhooks.get(id)`	Get a webhook
`client.webhooks.update(id, request)`	Update a webhook
`client.webhooks.delete(id)`	Delete a webhook
`client.webhooks.test(id)`	Send a test event to a webhook
`client.usage.get({params})`	Get API usage stats
`client.billing.subscription()`	Get current subscription details
`client.billing.checkout(request)`	Create a billing checkout session
`client.workspaces.list()`	List workspaces
`client.workspaces.create(request)`	Create a workspace
`client.workspaces.get(id)`	Get a workspace
`client.workspaces.update(id, request)`	Update a workspace
`client.workspaces.delete(id)`	Delete a workspace
`client.workspaces.listMembers(id)`	List workspace members
`client.workspaces.inviteMember(id, request)`	Invite a member to workspace
`client.workspaces.updateMember(id, userId, request)`	Update member role
`client.workspaces.removeMember(id, userId)`	Remove a member from workspace

Examples

Send email

await client.email.send({
  from: { email: "no-reply@yourapp.com", name: "Your App" },
  to: [{ email: "user@example.com" }],
  subject: "Your receipt",
  html: "<p>Thanks for your order!</p>",
});

Webhooks

// Register a webhook endpoint
const webhook = await client.webhooks.create({
  url: "https://yourapp.com/webhooks/mail",
  events: ["email.delivered", "email.opened", "email.bounced"],
});

// Send a test payload to verify
await client.webhooks.test(webhook.id);

Error Handling

import { MisarMailClient, MisarMailError, MisarMailNetworkError } from "@misarmail/sdk";

try {
  await client.email.send({ /* ... */ });
} catch (err) {
  if (err instanceof MisarMailError) {
    console.error(err.status, err.message);
  } else if (err instanceof MisarMailNetworkError) {
    console.error("network error", err.message);
  }
}

JavaScript / TypeScript