# Send transactional email with Naijamail

Source: https://naijacloud.com/guides/send-email-naijamail

This guide sends transactional email from a Node.js app with Naijamail, Naijacloud’s email API. At the end your app sends a welcome email from your own domain, signed with your domain’s DKIM key, with a sandboxed test key for development so nothing reaches a real inbox until you mean it to. The stack is Node.js 20 and the @naijacloud/email SDK; the REST API underneath works from any language.

_15 min · Beginner · Last verified 2026-10-07 · Stack: node, naijamail_

**What you'll have at the end:** A sendWelcome() function in your app that sends from hello@your-domain through Naijamail, tested end to end with a sandbox key before it ever mails a customer.

## Before you start

- A Node.js app, deployed on Naijacloud or anywhere else that can reach `https://api.naijacloud.com`.
- A domain you can add DNS records to. Using a subdomain such as `mail.example.com` keeps your sending reputation apart from your main domain’s mail.
- A Naijacloud account. Each workspace can send 1,000 emails a month free.

## Install the SDK

```sh
$ npm install @naijacloud/email
```

It has no runtime dependencies and reads the key from `NAIJAMAIL_API_KEY` when you don’t pass one.

## Write the send

Keep sending in one place, so every email goes through the same code:

```js title="lib/email.mjs"
import { Naijamail } from "@naijacloud/email";

const nm = new Naijamail(); // reads NAIJAMAIL_API_KEY

export async function sendWelcome(to, name) {
  const { id, status } = await nm.emails.send({
    from: process.env.EMAIL_FROM,
    to,
    subject: "Welcome aboard",
    html: `<p>Hi ${name}, your account is ready.</p>`,
    text: `Hi ${name}, your account is ready.`,
    // A retry with the same key returns the first send instead of sending twice.
    idempotencyKey: `welcome-${to}`,
  });
  return { id, status };
}
```

Call `sendWelcome(user.email, user.name)` wherever your app creates an account.

## Test it with a sandbox key

In the dashboard, open **Email** → **API keys**, click **Create email key**, give it a **Key name** such as `Development`, choose **Test** under **Mode** ("Nothing is sent") and click **Create key**. Test keys start with `nmail_test_`. A send with one is accepted, recorded and given a real id, but never handed to a mail server.

With a test key you can send from any address at `test.mail.naijacloud.dev`, before your own domain is set up:

```sh
$ export NAIJAMAIL_API_KEY=nmail_test_…
$ export EMAIL_FROM="Acme <hello@test.mail.naijacloud.dev>"
$ node -e 'import("./lib/email.mjs").then((m) => m.sendWelcome("delivered@test.mail.naijacloud.dev", "Ada")).then(console.log)'
{ id: '9ea2b10f-bf7a-4c65-8391-e60cf64a7dc0', status: 'delivered' }
```

Sending to `delivered@`, `bounced@` or `complained@test.mail.naijacloud.dev` gives you that outcome, so you can test how your app handles each. In **Email** → **Emails**, sandbox sends read **Test · not sent**.

## Add and verify your sending domain

Open **Email** → **Domains**, enter `mail.example.com` under **Add a sending domain** and click **Add domain**. Naijacloud generates a DKIM key for the domain and shows the records to publish, each with its **Host** and **Value**.

Add them at your DNS provider. If the domain’s DNS is on Naijacloud, **Add records for me** publishes them in one step. The domain reads **Waiting…** until the records resolve, then **Verified**.

> **Note: Records the dashboard marks Optional**
>
> They improve deliverability but don’t block sending. Publish them anyway when you can.

## Send for real

Create the live key. The simplest is a workspace key: **Settings** → **API keys** → **Create API key**, tick **Email send** under **Scopes**, and copy it when it says **Copy your key now**. It starts with `nc_live_`.

On your web service, open **Variables** and add:

- **NAIJAMAIL_API_KEY**: The `nc_live_` key you just created
- **EMAIL_FROM**: `Acme <hello@mail.example.com>`, on the domain you verified

Click **Save variables**, then **Deploy now** so the running app picks them up. The next account your app creates gets its welcome email, and **Email** → **Emails** shows it with its delivery status.

> **Warning: New domains start with a daily limit**
>
> A new sending domain can send 200 emails on its first day, and the limit doubles every day it sends cleanly. Plan a launch email list around it, or verify the domain a few days early.

## Reference

- [Sending email (API)](https://naijacloud.com/docs/api/email.md)
- [API keys](https://naijacloud.com/docs/workspace/api-keys.md)
- [Environment variables](https://naijacloud.com/docs/deploy/environment-variables.md)

All guides: https://naijacloud.com/guides · Index for agents: https://naijacloud.com/llms.txt