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 and Sendy’s SMTP server. Start with a plain-text email, then try HTML, multiple recipients, and attachments.

Before you begin

You need:

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 <[email protected]>";
const to = "[email protected]";

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 to follow delivery, or use the job ID from the response with Get 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 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, "[email protected]"],
  cc: "[email protected]",
  bcc: "[email protected]",
  replyTo: "[email protected]",
  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.

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 directly with its SMTP envelope option. Sendy requires verified domains for the visible From address and any nonempty envelope sender. See SMTP message requirements.

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 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.