> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AutoSend Node.js SDK
> Get started with the official AutoSend Node.js SDK to send emails programmatically.
export const AUTOSEND_PATHS = {
dashboard: 'https://autosend.com/dashboard',
apiKey: 'https://autosend.com/account/api-key',
faqs: 'https://autosend.com/faq',
marketingEmails: 'https://autosend.com/marketing-emails',
webhooks: 'https://autosend.com/webhooks',
composeByAutoSend: 'https://autosend.com/compose',
emailActivity: 'https://autosend.com/email-activities',
team: 'https://autosend.com/settings/team',
pricing: 'https://autosend.com/pricing',
verifyEmail: 'https://autosend.com/compose/email-builder?template=verify-email',
welcomeEmail: 'https://autosend.com/compose/email-builder?template=welcome-email',
productUpdate: 'https://autosend.com/compose/email-builder?template=product-update',
newsletter: 'https://autosend.com/compose/email-builder?template=newsletter',
automations: 'https://autosend.com/automations',
globalSuppressions: 'https://autosend.com/suppressions/global',
signup: 'https://autosend.com/signup',
domains: 'https://autosend.com/settings/domains',
logoKit: 'https://asend.email/logo',
contactsPage: 'https://autosend.com/contacts/list-and-segments'
};
export const APP_PATHS = {
home: '/',
quickstart: '/quickstart',
domainConfiguration: '/domain',
apiReference: '/api-reference',
sendEmail: '/api-reference/mails/send',
bulkSendEmail: '/api-reference/mails/bulk',
upsertContactApiRef: '/api-reference/contacts/upsert-contact',
transactional: '/transactional-emails',
emailActivity: '/transactional-emails/email-activity',
emailTemplates: '/transactional-emails/email-templates',
sendingEmail: '/quickstart/email-using-api',
transactionalTroubleshooting: '/transactional-emails/troubleshooting',
marketing: '/marketing-emails',
campaigns: '/marketing-emails/campaigns',
contacts: '/marketing-emails/contacts',
contactsIntroduction: '/marketing-emails/contacts/introduction',
contactsImportCsv: '/marketing-emails/contacts/import-csv',
contactsLists: '/marketing-emails/contacts/lists',
contactsSegments: '/marketing-emails/contacts/segments',
contactsCustomFields: '/marketing-emails/contacts/custom-fields',
sender: '/marketing-emails/sender',
unsubscribeGroups: '/others/unsubscribe-groups',
webhookIntroduction: '/others/webhooks/introduction',
webhookEventType: '/others/webhooks/event-type',
webhookRetries: '/others/webhooks/retries',
webhookVerifyRequests: '/others/webhooks/verify-requests',
dynamicTemplates: '/dynamic-templates',
guides: '/guides',
sitemap: '/sitemap.xml',
team: '/others/team',
automations: '/automations',
smtpIntroduction: '/quickstart/smtp',
betterAuth: '/guides/better-auth',
templateVariables: '/transactional-emails/variables',
suppressions: '/others/suppressions',
rateLimit: '/api-reference/rate-limit',
nodejsSdk: '/sdk/nodejs',
smtpIntegrationGuides: '/guides/smtp',
apiKeys: '/api-keys',
apiReferenceIntroduction: '/api-reference/introduction',
lovableGuide: '/ai/integrations/lovable',
aiIntroduction: '/ai/introduction',
aiSkills: '/ai/skills',
aiMcpServer: '/ai/mcp-server',
aiLovable: '/ai/integrations/lovable',
aiBolt: '/ai/integrations/bolt',
aiV0: '/ai/integrations/v0',
aiReplit: '/ai/integrations/replit',
mcpClaude: '/ai/mcp-clients/claude',
mcpCursor: '/ai/mcp-clients/cursor',
mcpCopilot: '/ai/mcp-clients/copilot',
mcpWindsurf: '/ai/mcp-clients/windsurf',
mcpCodex: '/ai/mcp-clients/codex',
mcpAntigravity: '/ai/mcp-clients/antigravity',
mcpChatgpt: '/ai/mcp-clients/chatgpt',
mcpRaycast: '/ai/mcp-clients/raycast',
domainWarmup: '/marketing-emails/domain-warmup',
projects: '/projects',
createAutomationApi: '/api-reference/automations/create-automation'
};
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
Make sure you have a verified domain added in AutoSend to send emails from.
Create an API key to authenticate your SDK requests.
## Installation
Install the SDK using your preferred package manager:
```bash npm theme={null}
npm install autosendjs
```
```bash yarn theme={null}
yarn add autosendjs
```
```bash pnpm theme={null}
pnpm add autosendjs
```
## Quick Start
Initialize the SDK with your API key:
```typescript theme={null}
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:
```typescript theme={null}
const autosend = new Autosend('AS_xxxxxxxxxxxx', {
baseUrl: 'https://api.autosend.com/v1',
timeout: 30000,
maxRetries: 3,
debug: false,
});
```
| Option | Type | Default | Description |
| ------------ | ------- | ----------------------------- | -------------------------------------------- |
| `baseUrl` | string | `https://api.autosend.com/v1` | API base URL |
| `timeout` | number | `30000` | Request timeout in milliseconds |
| `maxRetries` | number | `3` | Number of retry attempts for failed requests |
| `debug` | boolean | `false` | Enable debug logging |
## Sending Emails
### Plain Text Email
```typescript theme={null}
await autosend.emails.send({
from: { email: 'hello@yourdomain.com' },
to: { email: 'user@example.com' },
subject: 'Hello World',
text: 'Welcome to AutoSend!',
});
```
### HTML Email
```typescript theme={null}
await autosend.emails.send({
from: { email: 'hello@yourdomain.com', name: 'Your Company' },
to: { email: 'user@example.com', name: 'John Doe' },
subject: 'Welcome to Our Platform',
html: 'Welcome!
Thanks for signing up.
',
});
```
### Using Templates
Send emails using a pre-built template with dynamic variables:
```typescript theme={null}
await autosend.emails.send({
from: { email: 'hello@yourdomain.com' },
to: { email: 'user@example.com' },
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](/transactional-emails/email-templates) documentation.
## Bulk Emails
Send multiple emails in a single API call:
```typescript theme={null}
await autosend.emails.bulk({
from: { email: 'you@example.com' },
subject: 'Hello',
html: 'Welcome!
',
recipients: [{ email: 'user1@gmail.com' }, { email: 'user2@gmail.com' }],
});
```
Bulk sending is more efficient than sending emails individually. Use it when you need to send the
same or similar emails to multiple recipients.
## 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 [custom fields](/marketing-emails/contacts/custom-fields), or managing [unsubscribe](/others/unsubscribe-groups) 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.
```typescript theme={null}
await autosend.contacts.create({
email: 'user@example.com',
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.
```typescript theme={null}
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.
```typescript theme={null}
await autosend.contacts.upsert({
email: 'user@example.com',
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.
```typescript theme={null}
await autosend.contacts.delete('contact_id');
```
Learn more about lists, segments, and custom fields in the
[Contacts](/marketing-emails/contacts/introduction) documentation.
## Resend Adapter
If you're migrating from Resend, the SDK provides a compatibility adapter that mirrors the Resend API patterns:
```typescript theme={null}
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.
```typescript theme={null}
import { Autosend, SendEmailRequest } from 'autosendjs';
const autosend = new Autosend('AS_xxxxxxxxxxxx');
const emailRequest: SendEmailRequest = {
from: { email: 'hello@yourdomain.com' },
to: { email: 'user@example.com' },
subject: 'Type-safe email',
html: 'This request is fully typed!
',
};
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](/domain) 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](/api-reference/rate-limit) documentation for your plan's limits
## Resources
View source code, report issues, and contribute.
View package details and version history.
## Next Steps
Explore the complete API reference for advanced use cases
Create reusable email templates with dynamic variables
Set up webhooks to track email events in real-time
Learn how to manage contacts and lists