Skip to main content
The official AutoSend Node.js SDK provides a simple and intuitive way to send transactional and marketing emails from your Node.js applications. It includes full TypeScript support and handles authentication, request formatting, and error handling for you.

Prerequisites

Verified Domain

Make sure you have a verified domain added in AutoSend to send emails from.

API Key

Create an API key to authenticate your SDK requests.

Installation

Install the SDK using your preferred package manager:
npm install autosendjs
yarn add autosendjs
pnpm add autosendjs

Quick Start

Initialize the SDK with your API key:
import { Autosend } from 'autosendjs';

const autosend = new Autosend('AS_xxxxxxxxxxxx');
Store your API key in an environment variable (e.g., AUTOSEND_API_KEY) rather than hardcoding it in your source code.

Configuration Options

The SDK accepts optional configuration parameters:
const autosend = new Autosend('AS_xxxxxxxxxxxx', {
	baseUrl: 'https://api.autosend.com/v1',
	timeout: 30000,
	maxRetries: 3,
	debug: false,
});
OptionTypeDefaultDescription
baseUrlstringhttps://api.autosend.com/v1API base URL
timeoutnumber30000Request timeout in milliseconds
maxRetriesnumber3Number of retry attempts for failed requests
debugbooleanfalseEnable debug logging

Sending Emails

Plain Text Email

await autosend.emails.send({
	from: { email: '[email protected]' },
	to: { email: '[email protected]' },
	subject: 'Hello World',
	text: 'Welcome to AutoSend!',
});

HTML Email

await autosend.emails.send({
	from: { email: '[email protected]', name: 'Your Company' },
	to: { email: '[email protected]', name: 'John Doe' },
	subject: 'Welcome to Our Platform',
	html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
});

Using Templates

Send emails using a pre-built template with dynamic variables:
await autosend.emails.send({
	from: { email: '[email protected]' },
	to: { email: '[email protected]' },
	subject: 'Your Order Confirmation',
	templateId: 'your_template_id',
	dynamicData: {
		name: 'Johnrao',
		orderNumber: '12345',
		orderTotal: '$99.00',
	},
});
Learn more about creating and managing templates in the Email Templates documentation.

React Email

Pass a React Email component to the react option and the SDK renders it to HTML for you before sending:
import { WelcomeEmail } from './emails/welcome';

await autosend.emails.send({
	from: { email: '[email protected]' },
	to: { email: '[email protected]' },
	subject: 'Welcome',
	react: <WelcomeEmail name="Ada" />,
});
Rendering React components requires the optional @react-email/render peer dependency. Install it (along with react and your @react-email/components) with npm install @react-email/render. If it is missing when you pass react, the SDK throws an error.
The react option also works with autosend.emails.bulk, and {{...}} dynamic-data placeholders still work for per-recipient personalization. If you provide both html and react, the explicit html takes precedence.

Bulk Emails

Send multiple emails in a single API call:
await autosend.emails.bulk({
	from: { email: '[email protected]' },
	subject: 'Hello',
	html: '<p>Welcome!</p>',
	recipients: [{ email: '[email protected]' }, { email: '[email protected]' }],
});
Bulk sending is more efficient than sending emails individually. Use it when you need to send the same or similar emails to multiple recipients.

Receiving Emails (Inbound)

The inboundEmails module lets you work with emails received on your inbound-enabled domain. You can list and read messages, download their attachments, and reply to them directly from your code.

List Messages

Retrieve received messages with optional filters and pagination. The response returns matching items along with pagination metadata.
const result = await autosend.inboundEmails.list({
	from: '[email protected]',
	search: 'invoice',
	page: 1,
	limit: 25,
});

console.log(result.data.items); // matched messages
console.log(result.data.pagination); // { page, limit, total, pages }
Supported filters: from, to, threadId, search, dateFrom, dateTo, page, and limit.

Get a Message

Fetch a single message by its ID. This returns the full message, including its text and html body, attachments, headers, thread details, and spam, SPF, DKIM, and DMARC verdicts.
const message = await autosend.inboundEmails.get('60d5ec49f1b2c72d9c8b1234');
console.log(message.data);

Download an Attachment

Generate a signed, time-limited URL to download an attachment. The attachmentRef can be a numeric index or the stable attachmentId from the message.
const attachment = await autosend.inboundEmails.getAttachmentDownloadUrl(
	'60d5ec49f1b2c72d9c8b1234',
	0,
);

console.log(attachment.data.downloadUrl); // signed URL
console.log(attachment.data.expiresIn); // seconds until it expires
console.log(attachment.data.filename);

Reply to a Message

Send a reply to a received message. The reply is threaded to the original message automatically.
const reply = await autosend.inboundEmails.reply('60d5ec49f1b2c72d9c8b1234', {
	from: { email: '[email protected]', name: 'Support' },
	subject: 'Re: Hello',
	html: '<p>Thanks for reaching out!</p>',
});

console.log(reply.data.emailId);
console.log(reply.data.status); // 'QUEUED'
console.log(reply.data.totalRecipients);
Learn more in the Inbound Email guide and the API reference for listing, retrieving, downloading attachments from, and replying to inbound messages.

Sync user data to Contacts on AutoSend

The SDK lets you create, retrieve, update, and delete contacts directly from your code—useful for syncing users from your app, updating contact properties, or managing unsubscribe preferences.

Create a Contact

Add a new contact to your AutoSend account. You can assign them to one or more lists and include custom fields for segmentation.
await autosend.contacts.create({
	email: '[email protected]',
	firstName: 'John',
	lastName: 'Doe',
	listIds: ['list_abc123'],
	customFields: {
		company: 'Acme Inc',
		plan: 'pro',
	},
});

Get a Contact

Retrieve a contact’s details by their ID. This returns their email, name, list memberships, custom fields, and subscription status.
const contact = await autosend.contacts.get('contact_id');
console.log(contact);

Create or Update a Contact

Use upsert when you’re not sure if a contact already exists. If the email exists, it updates the contact; otherwise, it creates a new one. This is ideal for syncing users from your application.
await autosend.contacts.upsert({
	email: '[email protected]',
	firstName: 'Jane',
	customFields: {
		plan: 'enterprise',
	},
});

Delete a Contact

Permanently remove a contact from your account. This removes them from all lists and deletes their data.
await autosend.contacts.delete('contact_id');
Learn more about lists, segments, and custom fields in the Contacts documentation.

Resend Adapter

If you’re migrating from Resend, the SDK provides a compatibility adapter that mirrors the Resend API patterns:
import { Resend } from 'autosendjs/resend';

// Use your AutoSend API key
const resend = new Resend('AS_xxxxxxxxxxxx');

// Or use the RESEND_API_KEY environment variable
const resend = new Resend();
The Resend adapter uses properties instead of customFields for contacts, and remove() instead of delete() to match Resend’s API conventions.

TypeScript Support

The SDK is written in TypeScript and provides full type definitions out of the box. All methods, parameters, and responses are fully typed for better developer experience and IDE support.
import { Autosend, SendEmailRequest } from 'autosendjs';

const autosend = new Autosend('AS_xxxxxxxxxxxx');

const emailRequest: SendEmailRequest = {
	from: { email: '[email protected]' },
	to: { email: '[email protected]' },
	subject: 'Type-safe email',
	html: '<p>This request is fully typed!</p>',
};

await autosend.emails.send(emailRequest);

Troubleshooting

Possible causes:
  • Invalid or expired API key
  • API key not included in the request
Solutions:
  • Verify your API key in the Dashboard
  • Ensure you’re passing the API key correctly when initializing the SDK
  • Check that your API key hasn’t been revoked
Possible causes:
  • Network connectivity issues
  • Request payload too large
Solutions:
  • Increase the timeout in configuration options
  • Check your network connection
  • For bulk emails, reduce the batch size
Possible causes:
  • Sending from an unverified domain
  • DNS records not properly configured
Solutions:
  • Verify your sending domain in the Dashboard
  • Ensure SPF and DKIM records are properly set up
  • Check the Domain Configuration guide
Possible causes:
  • Too many requests in a short period
Solutions:
  • Implement exponential backoff in your application
  • Use bulk sending instead of individual requests
  • Check the Rate Limits documentation for your plan’s limits

Resources

GitHub

View source code, report issues, and contribute.

NPM

View package details and version history.

Next Steps

https://mintcdn.com/autosend-13920f5c/nx_wYfWx3qeZwg1C/icons/api.svg?fit=max&auto=format&n=nx_wYfWx3qeZwg1C&q=85&s=a257e726f0f001df70664b740dcd5af6

API Reference

Explore the complete API reference for advanced use cases
https://mintcdn.com/autosend-13920f5c/nx_wYfWx3qeZwg1C/icons/email-templates.svg?fit=max&auto=format&n=nx_wYfWx3qeZwg1C&q=85&s=461e1cf135b49bcb45ed4373269d54b9

Email Templates

Create reusable email templates with dynamic variables
https://mintcdn.com/autosend-13920f5c/nx_wYfWx3qeZwg1C/icons/webhook.svg?fit=max&auto=format&n=nx_wYfWx3qeZwg1C&q=85&s=14ad6675c71731ac04f786559a813ee1

Webhooks

Set up webhooks to track email events in real-time
https://mintcdn.com/autosend-13920f5c/nx_wYfWx3qeZwg1C/icons/contacts.svg?fit=max&auto=format&n=nx_wYfWx3qeZwg1C&q=85&s=93b686fb3cb253812d2ab70168336374

Contact Management

Learn how to manage contacts and lists
https://mintcdn.com/autosend-13920f5c/BvBuJTZLIsxccP1g/icons/inbound.svg?fit=max&auto=format&n=BvBuJTZLIsxccP1g&q=85&s=8e5973147776986adbab19f7b68fffe8

Inbound Email API

Receive incoming emails on your domain and process them programmatically