AutoSend Node.js SDK

A simplified Node.js SDK for the AutoSend API that focuses on the core functionality: sending single emails and bulk emails with support for React components.

Features

• ✅ Send single emails - Send individual emails to recipients
• ✅ Send bulk emails - Send emails to up to 100 recipients in one request
• ✅ React component support - Render React components directly into emails
• ✅ Template support - Use AutoSend templates with dynamic data
• ✅ TypeScript support - Full TypeScript definitions included
• ✅ Simple API - Clean, easy-to-use interface without unnecessary complexity

Installation

bun add autosend-node
# or
npm install autosend-node
# or
yarn add autosend-node

Quick Start

Initialize the Client

import { AutoSend } from "autosend-node";

// Initialize with API key
const autosend = new AutoSend("AS_your_api_key_here");

// Or use environment variable AUTOSEND_API_KEY
const autosend = new AutoSend();

Send a Single Email

const result = await autosend.send({
  to: {
    email: "[email protected]",
    name: "John Doe",
  },
  from: {
    email: "[email protected]",
    name: "Your Company",
  },
  subject: "Welcome to our platform!",
  html: "<h1>Welcome {{name}}!</h1><p>Thanks for signing up.</p>",
  dynamicData: {
    name: "John Doe",
  },
});

if (result.success) {
  console.log("Email sent successfully! ID:", result.data.emailId);
} else {
  console.error("Failed to send email:", result.error.message);
}

Send Bulk Emails

const result = await autosend.sendBulk({
  recipients: [
    {
      email: "[email protected]",
      name: "Alice",
      dynamicData: { firstName: "Alice", orderTotal: "$99.99" },
    },
    {
      email: "[email protected]",
      name: "Bob",
      dynamicData: { firstName: "Bob", orderTotal: "$149.99" },
    },
  ],
  from: {
    email: "[email protected]",
    name: "Your Store",
  },
  subject: "Your order has shipped!",
  html: "<h1>Hi {{firstName}}!</h1><p>Your order totaling {{orderTotal}} has been shipped.</p>",
});

if (result.success) {
  console.log(`Bulk email sent! Batch ID: ${result.data.batchId}`);
  console.log(`Successfully sent to ${result.data.successCount} recipients`);
} else {
  console.error("Failed to send bulk email:", result.error.message);
}

Use React Components

import React from "react";
import { AutoSend } from "autosend-node";

const autosend = new AutoSend("AS_your_api_key");

// Define a React email component
const WelcomeEmail = ({ name, verificationUrl }) => (
  <div
    style={{
      fontFamily: "Arial, sans-serif",
      maxWidth: "600px",
      margin: "0 auto",
    }}
  >
    <header
      style={{
        backgroundColor: "#f8f9fa",
        padding: "20px",
        textAlign: "center",
      }}
    >
      <h1 style={{ color: "#343a40", margin: 0 }}>Welcome to Our Platform</h1>
    </header>
    <main style={{ padding: "20px" }}>
      <p>Hello {name},</p>
      <p>
        Thank you for signing up! Please verify your email address by clicking
        the button below:
      </p>
      <div style={{ textAlign: "center", margin: "30px 0" }}>
        <a
          href={verificationUrl}
          style={{
            backgroundColor: "#007bff",
            color: "white",
            padding: "12px 30px",
            textDecoration: "none",
            borderRadius: "5px",
            display: "inline-block",
          }}
        >
          Verify Email
        </a>
      </div>
      <p>
        Best regards,
        <br />
        The Team
      </p>
    </main>
  </div>
);

// Send email with React component
const result = await autosend.send({
  to: { email: "[email protected]", name: "John Doe" },
  from: { email: "[email protected]", name: "Your Company" },
  subject: "Welcome! Please verify your email",
  react: React.createElement(WelcomeEmail, {
    name: "John Doe",
    verificationUrl: "https://yourapp.com/verify?token=abc123",
  }),
});

Use AutoSend Templates

// Send email using an AutoSend template
const result = await autosend.send({
  to: { email: "[email protected]", name: "John Doe" },
  from: { email: "[email protected]", name: "Your Company" },
  templateId: "tmpl_abc123",
  dynamicData: {
    firstName: "John",
    lastName: "Doe",
    orderNumber: "ORD-12345",
  },
});

// Send bulk emails with template
const result = await autosend.sendBulk({
  recipients: [
    {
      email: "[email protected]",
      name: "Alice",
      dynamicData: { firstName: "Alice" },
    },
    {
      email: "[email protected]",
      name: "Bob",
      dynamicData: { firstName: "Bob" },
    },
  ],
  from: { email: "[email protected]", name: "Your Company" },
  templateId: "tmpl_abc123",
  dynamicData: {
    // Global data for all recipients
    companyName: "Your Company",
    supportEmail: "[email protected]",
  },
});

API Reference

Constructor Options

new AutoSend(apiKey?, options?)

• apiKey (string, optional): Your AutoSend API key. If not provided, will look for AUTOSEND_API_KEY environment variable
• options.baseUrl (string, optional): Custom API base URL. Defaults to https://api.autosend.com/v1

Send Single Email

autosend.send(options);

Options

| Field | Type | Required | Description | | -------------------- | ------------------------- | -------- | ------------------------------------------------------------ | | to | EmailAddress | ✅ | Recipient email and name | | from | EmailAddress | ✅ | Sender email and name (must be from verified domain) | | subject | string | ❌* | Email subject (required if not using templateId) | | html | string | ❌* | HTML content (required if not using templateId or react) | | text | string | ❌ | Plain text version | | react | React.ReactNode | ❌ | React component to render as HTML | | templateId | string | ❌ | AutoSend template ID | | dynamicData | Record<string, unknown> | ❌ | Template variables | | replyTo | EmailAddress | ❌ | Reply-to address | | attachments | Attachment[] | ❌ | File attachments | | unsubscribeGroupId | string | ❌ | Unsubscribe group ID |

*Required if not using templateId

EmailAddress Type

interface EmailAddress {
  email: string;
  name?: string;
}

Attachment Type

interface Attachment {
  filename: string;
  content?: string; // Base64 encoded content
  contentType?: string;
  fileUrl?: string; // Alternative to content
  description?: string;
}

Send Bulk Email

autosend.sendBulk(options);

Bulk Email Options

Same as single email options, but with:

• recipients (required): Array of BulkRecipient objects (max 100)
• to field is replaced by recipients

BulkRecipient Type

interface BulkRecipient {
  email: string;
  name?: string;
  dynamicData?: Record<string, unknown>; // Per-recipient template data
}

Response Format

All methods return a standardized response:

interface AutoSendResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    message: string;
    code: string;
    details?: Array<{
      field: string;
      message: string;
    }>;
  };
}

Single Email Response Data

interface SendEmailResponseData {
  emailId: string;
}

Bulk Email Response Data

interface SendBulkEmailResponseData {
  batchId: string;
  totalRecipients: number;
  successCount: number;
  failedCount: number;
}

Error Handling

The SDK handles errors gracefully and returns them in a consistent format:

const result = await autosend.send(emailOptions);

if (!result.success) {
  switch (result.error.code) {
    case "VALIDATION_FAILED":
      console.log("Validation errors:", result.error.details);
      break;
    case "UNAUTHORIZED":
      console.log("Invalid API key");
      break;
    case "RATE_LIMIT_EXCEEDED":
      console.log("Rate limit exceeded, try again later");
      break;
    default:
      console.log("Error:", result.error.message);
  }
}

Environment Variables

• AUTOSEND_API_KEY: Your AutoSend API key (used when not passed to constructor)

TypeScript Support

This package includes full TypeScript definitions. All types are exported for your convenience:

import {
  AutoSend,
  SendEmailOptions,
  SendBulkEmailOptions,
  SendEmailResponse,
  SendBulkEmailResponse,
  EmailAddress,
  Attachment,
  BulkRecipient,
} from "autosend-node";

Examples

Example with Attachments

const result = await autosend.send({
  to: { email: "[email protected]", name: "John Doe" },
  from: { email: "[email protected]", name: "Your Company" },
  subject: "Your invoice is ready",
  html: "<p>Please find your invoice attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: "base64-encoded-pdf-content",
      contentType: "application/pdf",
    },
  ],
});

Example with Reply-To

const result = await autosend.send({
  to: { email: "[email protected]", name: "John Doe" },
  from: { email: "[email protected]", name: "Your Company" },
  replyTo: { email: "[email protected]", name: "Support Team" },
  subject: "Need help? Reply to this email",
  html: "<p>If you need assistance, just reply to this email.</p>",
});

Development

# Install dependencies
bun install

# Run tests
bun run test

# Build the package
bun run build

# Format code
bun run format

# Type check
bun run typecheck

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

If you encounter any issues or have questions, please open an issue on GitHub.