Integrations

# Email SDK

Send email with @opencoredev/email-sdk through Sendy’s SMTP server.

Send email from your Node.js application with [OpenCore’s Email SDK](https://github.com/opencoredev/email-sdk) and Sendy’s SMTP server. Start with a plain-text email, then try HTML, multiple recipients, and attachments.

## Before you begin

You need:

*   Node.js 20 or later on your application server.
*   A verified sending domain in [Domains](https://usesendy.com/domains).
*   A full [API key](https://usesendy.com/docs/authentication).
*   Available [email credits](https://usesendy.com/billing).

## 1\. Install Email SDK

In your Node.js project directory, run:

Email SDK · install

```
npm install @opencoredev/email-sdk
```

## 2\. Export your API key

Replace `API_KEY` with your full key, including `snd_key_`, then run this command in your terminal:

Email SDK · API key

```
export SENDY_API_KEY='API_KEY'
```

Use this same terminal to run the example. The variable lasts for this shell session.

## 3\. Send your first email

Save this complete example as `send-email.mjs`. Replace `from` with an address on your verified domain and `to` with your test address:

send-email.mjs · Email SDK · plain text

```
import { createEmailClient } from "@opencoredev/email-sdk";
import { smtp } from "@opencoredev/email-sdk/smtp";
import { readFile } from "node:fs/promises";

const apiKey = process.env.SENDY_API_KEY;
if (!apiKey) throw new Error("Set SENDY_API_KEY before sending.");

const from = "My App <noreply@example.com>";
const to = "recipient@example.com";

const email = createEmailClient({
  adapters: [
    smtp({
      host: "smtp.usesendy.com",
      port: 2525,
      secure: false,
      requireTLS: true,
      auth: { user: "apikey", pass: apiKey },
    }),
  ],
});

// Replace this send block to try the examples below.
const result = await email.send({
  from,
  to,
  subject: "Welcome",
  text: "Your account is ready.",
});

console.log(result.raw.response);
```

In the same terminal, run:

Email SDK · run

```
node send-email.mjs
```

Use the literal username `apikey`. `secure: false` selects STARTTLS, and `requireTLS: true` requires encryption before authentication. Keep your API key in your server’s secret configuration when deploying this code.

## 4\. Check the result

A successful submission prints Sendy’s SMTP response:

Email SDK · SMTP response

```
250 2.0.0 Queued jobs 123
```

This confirms Sendy queued the email. Open [Emails](https://usesendy.com/emails) to follow delivery, or use the job ID from the response with [Get email status](https://usesendy.com/docs/api/email-status). Queue acceptance does not confirm inbox delivery.

Use the job IDs in `result.raw.response` for Sendy status lookups. The SDK’s `result.id` can be a generated message ID instead of a Sendy job ID.

If the script fails, check your exported variables, domain verification, and email credits. See [Errors](https://usesendy.com/docs/errors) for SMTP response codes.

## Send other message types

In `send-email.mjs`, replace the send block at the end of the file, from `const result = await email.send(...)` through `console.log(...)`, with one example below. Keep the imports, sender, recipient, and client setup. Run `node send-email.mjs` again to send that example.

### Send HTML with a text alternative

Provide `html` for HTML, `text` for plain text, or both for a multipart alternative:

Email SDK · HTML and plain text

```
const result = await email.send({
  from,
  to,
  subject: "Welcome",
  html: "<h1>Welcome</h1><p>Your account is ready.</p>",
  text: "Your account is ready.",
});

console.log(result.raw.response);
```

### Add recipients and a reply-to address

Replace all additional recipient and reply-to addresses before running this example. Use `replyTo` to direct replies to your support address:

Email SDK · recipients and reply-to

```
const result = await email.send({
  from,
  to: [to, "second@example.com"],
  cc: "team@example.com",
  bcc: "archive@example.com",
  replyTo: "support@example.com",
  subject: "Project update",
  text: "Your project is ready for review.",
});

console.log(result.raw.response);
```

Sendy creates one job per distinct envelope recipient, including Cc and Bcc, with up to 50 recipients per message. Bcc recipients receive the email without a visible Bcc header.

### Attach a file

Place `invoice.pdf` in the directory where you run the command, then use:

Email SDK · PDF attachment

```
const result = await email.send({
  from,
  to,
  subject: "Your invoice",
  text: "Your invoice is attached.",
  attachments: [
    {
      filename: "invoice.pdf",
      content: await readFile("./invoice.pdf"),
      contentType: "application/pdf",
    },
  ],
});

console.log(result.raw.response);
```

Sendy’s default message limit is 1 MiB, including MIME headers and encoded attachments. Encoding increases the size of attached files. See [SMTP message limits](https://usesendy.com/docs/smtp#message-heading).

### Embed an inline image

Place `logo.png` in the directory where you run the command. Match the HTML `cid:` reference to the attachment’s `contentId`:

Email SDK · inline image

```
const result = await email.send({
  from,
  to,
  subject: "Welcome",
  text: "Welcome to My App.",
  html: '<img src="cid:logo" alt="My App"><p>Welcome to My App.</p>',
  attachments: [
    {
      filename: "logo.png",
      content: await readFile("./logo.png"),
      contentType: "image/png",
      contentId: "logo",
      disposition: "inline",
    },
  ],
});

console.log(result.raw.response);
```

## SMTP envelope behavior

The SMTP envelope controls delivery separately from the visible email headers. The adapter uses `from` for `MAIL FROM` and all `to`, `cc`, and `bcc` addresses for `RCPT TO`. `replyTo` changes where replies go; it does not change the envelope sender.

The SDK’s `EmailEnvelope` type groups message fields. It does not expose a separate SMTP `envelope` override. For a different envelope sender, an empty reverse path, or recipients independent of the visible headers, use [Nodemailer](https://usesendy.com/docs/integrations/nodemailer) directly with its [SMTP envelope option](https://nodemailer.com/smtp/envelope). Sendy requires verified domains for the visible From address and any nonempty envelope sender. See [SMTP message requirements](https://usesendy.com/docs/smtp#message-heading).

## Retry safely

Sendy deduplicates submissions using the `Sendy-Idempotency-Key` message header. Add it to the message passed to `email.send()`:

Email SDK · idempotency header

```
headers: [
  { name: "Sendy-Idempotency-Key", value: "welcome/user-123" },
],
```

Use a key unique to the logical email and reuse it only for retries of that email. The SDK’s `idempotencyKey` send option sets a message ID, not Sendy’s deduplication header. See [SMTP idempotency requirements](https://usesendy.com/docs/smtp#smtp-idempotency-heading) for key limits and conflict responses.

Multipart messages and attachments also need stable MIME bytes across retries. The SDK rebuilds their MIME boundaries on each send, so reusing a key alone does not make those retries match. To preserve a composed raw message, use [Nodemailer](https://usesendy.com/docs/integrations/nodemailer).
