> ## 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',
smtpKey: 'https://autosend.com/settings/smtp',
logoKit: 'https://asend.email/logo',
contactsPage: 'https://autosend.com/contacts/list-and-segments',
accountBilling: 'https://autosend.com/account/billing',
accountUsage: 'https://autosend.com/account/usage',
terms: 'https://autosend.com/legal/terms',
inbound: 'https://autosend.com/email-activities/inbound'
};
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/contact-properties',
contactsContactProperties: '/marketing-emails/contacts/contact-properties',
createContactPropertyApiRef: '/api-reference/contact-properties/create',
listContactPropertiesApiRef: '/api-reference/contact-properties/list',
getContactPropertyApiRef: '/api-reference/contact-properties/get-by-name',
deleteContactPropertyApiRef: '/api-reference/contact-properties/delete',
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',
events: '/automations/events',
sendEventApi: '/api-reference/events/send-event',
smtpIntroduction: '/quickstart/smtp',
betterAuth: '/guides/better-auth',
convexGuide: '/guides/convex',
templateVariables: '/transactional-emails/variables',
suppressions: '/others/suppressions',
rateLimit: '/api-reference/rate-limit',
nodejsSdk: '/sdk/nodejs',
smtpIntegrationGuides: '/guides/smtp',
apiKeys: '/api-keys',
encryptedPayloads: '/others/encrypted-payloads',
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',
migrationSendgrid: '/migration/sendgrid',
migrationResend: '/migration/resend',
auth0CustomAction: '/guides/auth0-custom-action',
accountBilling: '/others/account/billing',
accountUsage: '/others/account/usage',
inboundIntroduction: '/inbound/introduction',
listInboundMessagesApi: '/api-reference/inbound-emails/list-messages',
getInboundMessageApi: '/api-reference/inbound-emails/get-message',
downloadInboundAttachmentApi: '/api-reference/inbound-emails/download-attachment',
replyToInboundMessageApi: '/api-reference/inbound-emails/reply-to-message',
wikiDailySendingLimit: '/wiki/daily-sending-limit'
};
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.
### React Email
Pass a [React Email](https://react.email) component to the `react` option and the SDK renders it to HTML for you before sending:
```tsx theme={null}
import { WelcomeEmail } from './emails/welcome';
await autosend.emails.send({
from: { email: 'hello@yourdomain.com' },
to: { email: 'user@example.com' },
subject: 'Welcome',
react: ,
});
```
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:
```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.
## 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.
```typescript theme={null}
const result = await autosend.inboundEmails.list({
from: 'sender@example.com',
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.
```typescript theme={null}
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.
```typescript theme={null}
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.
```typescript theme={null}
const reply = await autosend.inboundEmails.reply('60d5ec49f1b2c72d9c8b1234', {
from: { email: 'support@yourdomain.com', name: 'Support' },
subject: 'Re: Hello',
html: 'Thanks for reaching out!
',
});
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](/marketing-emails/contacts/contact-properties), 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 contact properties 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, contact properties, 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 contact properties 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
Receive incoming emails on your domain and process them programmatically