# @maillog/node-sdk

Node SDK and MCP server for the [Maillog](https://maillog.nl) email API.
Other languages: [Python](https://github.com/maillog-dev/sdk-python) ·
[Go](https://github.com/maillog-dev/sdk-go) ·
[Ruby](https://github.com/maillog-dev/sdk-ruby) ·
[PHP](https://github.com/maillog-dev/sdk-php) ·
[Rust](https://github.com/maillog-dev/sdk-rust)

## Install

```sh
npm install @maillog/node-sdk
```

## Get a key without an account

```sh
curl -X POST https://api.maillog.nl/v1/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
```

The key it returns may only send to that address and expires after 24 hours.
For your own domains, sign up at https://maillog.nl/signup.

## Send

```js
import { Maillog } from "@maillog/node-sdk";

const maillog = new Maillog(process.env.MAILLOG_API_KEY);

const { id } = await maillog.emails.send({
  from: "Acme <noreply@acme.nl>",
  to: ["you@example.com"],
  subject: "hello",
  html: "<p>it works</p>",
});
```

`emails.sendBatch(emails)` takes 1 to 100 at a time. `emails.list({ limit, offset, status })`
returns what was sent, with delivery status and open/click counts.

## Errors

Failures throw `MaillogError` with `.status` and `.body`, so a 422 from validation
and a 403 from an expired key can be handled apart.

```js
import { MaillogError } from "@maillog/node-sdk";

try {
  await maillog.emails.send(params);
} catch (err) {
  if (err instanceof MaillogError && err.status === 422) {
    // body carries errors[] with the offending field
  }
}
```

There is no retry logic, on purpose: a client that silently resends produces
duplicate mail, and only you know whether that is acceptable.

## MCP server

The package ships an MCP server so an assistant can send mail directly.

```sh
claude mcp add maillog --env MAILLOG_API_KEY=ma_xxx -- npx -y maillog-mcp
```

Tools: `send_email`, `list_emails`.

## Options

```js
new Maillog(apiKey, {
  baseUrl: "http://localhost:3086",  // default https://api.maillog.nl
  timeoutMs: 30_000,
});
```

## Develop

```sh
npm run build          # tsc to dist/
node --test src/*.test.ts
```

MIT.