Send email with TypeScript

Types catch the bug before the bounce

Untyped email code fails at runtime, in production, on the send that mattered. A typed client moves those failures to the compiler: a missing from, a misnamed field, an html body passed as a number, all caught before deploy.

One POST, and the send is handled

import { Nitrosend } from "@nitrosend/sdk"
const ns = new Nitrosend(process.env.NITROSEND_API_KEY!)

const { id } = await ns.messages.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome",
  html: "<p>You're in.</p>",
})

The response is typed too: destructure the message ID and hand it to your logs or your tests. First sends require a ready sender: prepare and explicitly select the brand’s protected Nitrosend subdomain, or verify a customer-owned domain. The API never falls back to an unverified shared sender.

The key in that env var is a server-side credential. Our API keys exist for server-side integration of applications, so keep them out of browser bundles and client code. Key scopes bite in practice too. George, our CEO, hit this from the provider side: our own SendGrid connection test used to probe an endpoint that requires the Sender Authentication scope, so a valid least-privilege Mail-Send key 403'd and was reported invalid. He swapped the probe to GET /v3/scopes, which any valid key can read while an invalid key still 401s, and backed it with a regression test that runs 5 for 5 green.

Types are half the tooling story. The other half: there's a design.md file structured specifically for AI agents. Drop it into Claude, Cursor, or ChatGPT and it designs better emails based on what the best brands are doing. George uses it himself and calls the quality difference obvious.

And if you care about what a platform is made of: our MCP server, our CLI, and our AI SDK are all TypeScript. The agent surface of the product is written in the language you're reading this page for.

That AI SDK is @nitrosend/ai-sdk on npm, a TypeScript package built for Vercel AI SDK agents specifically. And the typed thinking runs through the API itself: upload an oversized CSV and you get a 422 with a validation_errors array you can act on, not an opaque 413 from some edge proxy. Errors are part of the type contract too.

Full parameters, responses, and error codes live in the REST API docs and the API reference.

import requests

requests.post(
  "https://api.nitrosend.com/v1/messages",
  headers={"Authorization": f"Bearer {KEY}"},
  json={"to": to, "subject": subj,
        "html": body})

{ "id": "msg_9f2c",
  "status": "accepted" }

And the part no library gives you

The same account exposes an MCP server, so the agent writing your code can also run your email. Point Claude, Cursor, or Codex at api.nitrosend.com/mcp and it composes, previews, and stages sends, with a human approving every one. The API is for your code. The MCP is for your agent. One platform either way.

Every send comes back with a message ID, and delivery events follow on your webhook: delivered, opened, bounced. No dashboard required to know what happened. If you are staying on SMTP, how to set up SMTP is the setup to follow, and SPF, DKIM and DMARC authentication is what stops those sends landing in spam.

Either path lands on hardened infrastructure. On our relay, TCP 2525 is firewall-restricted to our API host, TLS and exact SMTP authentication are mandatory, and every one-recipient route snapshot is HMAC-signed. Arbitrary destinations, unsigned or replayed requests, and multiple forwarding hops are rejected outright.

The typing is nice. The zero dependencies are nice. Neither is the real change. The real change is that Claude, Cursor, or Codex can point at our MCP server, compose the send, and ask you to approve it before anything leaves, with no TypeScript in the loop at all. That's where email sending is actually heading, and it's why Nitrosend is a listed app in the ChatGPT app marketplace rather than just another well-typed SDK.

Go deeper

FAQ

How do I send email with TypeScript?

Use @nitrosend/sdk: new Nitrosend(key) then await ns.messages.send({ from, to, subject, html }). Fully typed request and response, message ID back.

What is the benefit over plain JavaScript?

The compiler catches malformed sends before runtime: missing fields, wrong types, typo'd properties. Email failures move from production logs to your editor.