JavaScript SDK

import { MailBreeze } from "mailbreeze";

const mailbreeze = new MailBreeze({
  apiKey: process.env.MAILBREEZE_API_KEY!,
});

// Send an email
const result = await mailbreeze.emails.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<h1>Welcome to our platform!</h1>",
});

console.log(`Email sent: ${result.id}`);

const mailbreeze = new MailBreeze({
  apiKey: "sk_live_xxx",       // Required
  baseUrl: "https://api.mailbreeze.com", // Optional: custom API URL
  timeout: 30000,              // Optional: request timeout (ms)
  maxRetries: 3,               // Optional: max retry attempts
});

// Send email
const result = await mailbreeze.emails.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Hello!</p>",
});

// Send with template
const result = await mailbreeze.emails.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  templateId: "welcome-template",
  variables: { name: "John" },
});

// List emails
const { data, pagination } = await mailbreeze.emails.list({
  status: "delivered",
  page: 1,
  limit: 20,
});

// Get email
const email = await mailbreeze.emails.get("msg_xxx");

// Get stats
const stats = await mailbreeze.emails.stats();

// Create upload URL
const { attachmentId, uploadUrl, uploadToken } = await mailbreeze.attachments.createUpload({
  fileName: "report.pdf",
  contentType: "application/pdf",
  fileSize: 1024000,
});

// Upload file (use native fetch)
await fetch(uploadUrl, {
  method: "PUT",
  body: fileBuffer,
  headers: { "Content-Type": "application/pdf" },
});

// Confirm upload
await mailbreeze.attachments.confirm({ uploadToken });

// Use in email
await mailbreeze.emails.send({
  attachmentIds: [attachmentId],
  // ... other params
});

// Create list
const list = await mailbreeze.lists.create({
  name: "Newsletter",
  customFields: [
    { key: "company", label: "Company", type: "text" },
  ],
});

// List all
const { data } = await mailbreeze.lists.list();

// Get, update, delete
const list = await mailbreeze.lists.get("lst_xxx");
await mailbreeze.lists.update("lst_xxx", { name: "New Name" });
await mailbreeze.lists.delete("lst_xxx");

// Get stats
const stats = await mailbreeze.lists.stats("lst_xxx");

// Get contacts for a list
const contacts = mailbreeze.contacts("lst_xxx");

// Create contact
const contact = await contacts.create({
  email: "user@example.com",
  firstName: "John",
  customFields: { company: "Acme" },
});

// List, get, update, delete
const { data } = await contacts.list({ status: "active" });
const contact = await contacts.get("cnt_xxx");
await contacts.update("cnt_xxx", { firstName: "Jane" });
await contacts.delete("cnt_xxx");

// Suppress contact
await contacts.suppress("cnt_xxx", "bounced");

// Verify single email
const result = await mailbreeze.verification.verify({ email: "user@example.com" });
if (result.isValid) {
  console.log("Safe to send");
}

// Batch verify
const batch = await mailbreeze.verification.batch({
  emails: ["user1@example.com", "user2@example.com"],
});

// Poll for results
const status = await mailbreeze.verification.get(batch.verificationId);

// List and stats
const { data } = await mailbreeze.verification.list();
const stats = await mailbreeze.verification.stats();

import { MailBreeze, MailBreezeError } from "mailbreeze";

try {
  await mailbreeze.emails.send({ ... });
} catch (error) {
  if (error instanceof MailBreezeError) {
    console.log(error.code);    // e.g., "VALIDATION_ERROR"
    console.log(error.message); // Human-readable message
    console.log(error.status);  // HTTP status code

    // Handle specific errors
    switch (error.code) {
      case "DNS_VERIFICATION_FAILED":
        // Domain not verified
        break;
      case "RATE_LIMIT_EXCEEDED":
        // Retry after delay
        break;
    }
  }
}

import { MailBreeze, SendEmailParams, Email, EmailStats } from "mailbreeze";

const params: SendEmailParams = {
  from: "hello@yourdomain.com",
  to: ["user@example.com"],
  subject: "Hello",
  html: "<p>Hello!</p>",
};

const result = await mailbreeze.emails.send(params);
// result is typed as Email