The emiit SDK

Quickstart#

Three steps to your first email.

npm install @emiit/sdk resend

await emiit.send({
  templateId: "tmpl_welcome",
  from: "Emiit <hello@emiit.dev>",
  to: "timi@emiit.dev",
  subject: "Welcome to Emiit",
  data: { name: "Jane" },
});

Get your API key#

Open Settings → API keys in your workspace and create a key. It's the only thing you need to start sending, so keep it private and store it as an environment variable.

export EMIIT_API_KEY="emiit_sk_live_..."

Send an email#

Pick a template, say who it's for, and emiit builds and sends the email. Use the Node SDK, or call the HTTP API from anything else.

import { Emiit } from "@emiit/sdk";
import { resend } from "@emiit/sdk/providers";
import { Resend } from "resend";

const emiit = new Emiit({
  apiKey: process.env.EMIIT_API_KEY,
  provider: resend(new Resend(process.env.RESEND_API_KEY)),
});

await emiit.send({
  templateId: "tmpl_welcome",
  from: "Emiit <hello@emiit.dev>",
  to: "timi@emiit.dev",
  subject: "Welcome to Emiit",
  data: { name: "Jane", plan: "Pro" },
});

You can send to one person or a whole list, add people on copy, set a reply-to address, or write the preview line. See sending options for everything you can include.

The Node client#

The SDK gives you typed options, readable errors, and no hand-written requests. Add it to your project:

npm install @emiit/sdk

These are the settings you give the client once, when you create it:

Set a default from on the client and you can leave it out of every send() call.

Delivery#

emiit renders your template; an email service delivers it. Plug in the one you already use with your own account and keys, so nothing about your sending reputation changes. These are the supported services:

You set the service up with your own account details, then hand it to emiit. Here it is with Nodemailer over plain SMTP:

import { Emiit } from "@emiit/sdk";
import { nodemailer } from "@emiit/sdk/providers";
import nm from "nodemailer";

const transport = nm.createTransport({
  host: "smtp.emiit.dev",
  port: 587,
  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
});

const emiit = new Emiit({
  apiKey: process.env.EMIIT_API_KEY,
  provider: nodemailer(transport),
});

Sending with emiit

Prefer not to bring a provider? Leave provider out and emiit delivers the mail itself. First connect the domain you want to send from:

import { Emiit } from "@emiit/sdk";

const emiit = new Emiit({ apiKey: process.env.EMIIT_API_KEY });

await emiit.send({
  templateId: "tmpl_welcome",
  from: "Emiit <hello@emiit.dev>",
  to: "timi@emiit.dev",
  subject: "Welcome to Emiit",
  data: { name: "Jane" },
});

Want to try it before touching DNS? Send from welcome@emiit.dev today. It needs no setup, but it only delivers to the email addresses of your workspace's members, so it's for testing rather than real traffic. Anything else comes back as recipient_not_allowed.

Sending options#

Everything you can include when you send an email, whether over the API or the SDK:

Filling in data#

Most emails have parts that change for each person, like a name, an order total, or a list of items. Whatever you pass as data fills in those blanks in your design, matched by name. The subject line can use variables too.

{
  "templateId": "tmpl_welcome",
  "to": "timi@emiit.dev",
  "subject": "Welcome, {{ name }}",
  "data": {
    "name": "Jane",
    "plan": "Pro",
    "items": [
      { "label": "Unlimited templates" },
      { "label": "Priority support" }
    ]
  }
}

If a required variable is missing or has the wrong type, the send fails with an invalid_data error that lists exactly which fields to fix, so a broken email never goes out.

Opens & clicks#

Tracking is on by default and needs no setup. Every send is logged per template, links are rewritten to count clicks, and opens are measured automatically. See it all under Analytics in your workspace.

Add tags to a send to label it, so you can tell campaigns apart in the dashboard:

await emiit.send({
  templateId: "tmpl_receipt",
  to: "timi@emiit.dev",
  subject: "Your receipt",
  tags: { campaign: "q3-launch" },
});

Errors#

When an email can't be sent, the SDK throws an EmiitError with a stable code, the HTTP status, and a readable message, so you can show a friendly message or retry.

import { Emiit, EmiitError } from "@emiit/sdk";

try {
  await emiit.send({
    templateId: "tmpl_welcome",
    to: "timi@emiit.dev",
    subject: "Welcome",
  });
} catch (err) {
  if (err instanceof EmiitError) {
    // e.g. "invalid_data" 422 "Missing or invalid variables: name (string)."
    console.error(err.code, err.status, err.message);
  }
  throw err;
}

The codes you might see: