Send transactional email with 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.
nodenaijamailA 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.comkeeps 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
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:
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:
Sending to delivered@, bounced@ or [email protected] 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.
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:
nc_live_ key you just createdAcme <[email protected]>, on the domain you verifiedClick 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.