Send emails with Node.js

Learn how to send your first email using the YourSend Node.js SDK.

Prerequisites

To get the most out of this guide, you'll need to:

1. Install

Get the YourSend Node.js SDK.

npm install yoursend

2. Send email using HTML

The easiest way to send an email is by using the html parameter.

index.ts

import { YourSend } from 'yoursend';

const ys = new YourSend({ apiKey: 'ys_live_...' });

// send() returns the message directly and throws on failure
try {
  const message = await ys.send({
    channel: 'email',
    to: 'user@example.com',
    subject: 'Hello from YourSend',
    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  });
  console.log('Message sent:', message.message_id);
} catch (err) {
  console.error('Failed to send:', err);
}

3. Send using a template

Use pre-built templates with merge tags for dynamic content. Pass merge-tag values in the data object (these fill {{name}}-style placeholders in your template).

send-template.ts

const message = await ys.send({
  channel: 'email',
  to: 'user@example.com',
  template_id: '8f14e45f-ceea-467a-9b3a-1d2c3e4f5a6b',
  data: {
    name: 'Alex',
    company: 'Acme Inc',
  },
});

4. Try it yourself

You can also test the API directly using cURL:

curl -X POST https://api.yoursend.dev/v1/send \
  -H "Authorization: Bearer ys_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "user@example.com",
    "subject": "Test email",
    "html": "<h1>It works!</h1>"
  }'