@toobstudio/send-email/README.md

Secure SDK for sending emails using the TOOB Mail API

# @toobstudio/send-email

[![NPM Version](https://img.shields.io/npm/v/@toobstudio/send-email)](https://www.npmjs.com/package/@toobstudio/send-email)
[![License](https://img.shields.io/npm/l/@toobstudio/send-email)](LICENSE)

> Secure and minimal SDK to send emails via TOOB Mail API with HMAC signature. Built for server-side use in Next.js (App Router) and Node.js projects.

---

## 📦 Installation

```bash
npm install @toobstudio/send-email
```

---

## 🛠️ Setup

To use this package, you must be registered and have an active account at [mail.toob.com.br](https://mail.toob.com.br).

Create a `.env.local` file in the root of your project with your email credentials:

```env
MAIL_TOOB_API_KEY=your_project_api_key
MAIL_TOOB_SECRET_KEY=your_project_secret_key
```

> ⚠️ The environment variable names must be exactly:
>
> - `MAIL_TOOB_API_KEY`
> - `MAIL_TOOB_SECRET_KEY`

> These keys are sensitive and must be used **only in server-side code**. All requests to the TOOB Mail API must be made from server-side code, never from the browser, because the cryptographic signature is generated using your secret key and must not be exposed to the client.

---

## 🚀 Usage (in Next.js route handler or Node.js API)

### Next.js: Como enviar email via API Route

### Next.js: How to send email via API Route

On the frontend, make a request to the API endpoint using a function like this:

```ts
// Exemplo de chamada no frontend (React)
async function handleSend(e: React.FormEvent) {
  e.preventDefault();
  setLoading(true);

  try {
    const res = await fetch("/api/email", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ to, subject, message }),
    });

    if (!res.ok) throw new Error("Failed to send");

    toast.success("Email sent successfully!");
  } catch (err) {
    toast.error("Error sending email");
  } finally {
    setLoading(false);
  }
}
```

On the backend, create an endpoint at `app/api/email/route.ts` (Next.js 13/14 App Router):

```ts
import { NextRequest, NextResponse } from "next/server";
import { sendEmail } from "@toobstudio/send-email";

export async function POST(req: NextRequest) {
  const body = await req.json();
  const { to, subject, message } = body;

  try {
    await sendEmail({ to: [to], subject, message });
    return NextResponse.json({ success: true });
  } catch (err: any) {
    console.error("Error sending:", err);
    return NextResponse.json({ error: err.message }, { status: 500 });
  }
}
```

---

## ✉️ Parameters

```ts
interface SendEmailParams {
  to?: string[]; // Optional. If not provided, the email will be sent to the address registered on the site.
  subject: string; // Required
  message: string; // Required (HTML content)
  plain_text?: string; // Optional fallback for text-only clients
}
```

---

## 🧪 Example (Node.js with Express)

```ts
import express from "express";
import { sendEmail } from "@toobstudio/send-email";

const app = express();
app.use(express.json());

app.post("/contact", async (req, res) => {
  const { name, email, message } = req.body;

  await sendEmail({
    to: ["hello@yourdomain.com"],
    subject: `Contact from ${name}`,
    message: `<p>${message}</p><p>Email: ${email}</p>`,
  });

  res.status(200).json({ sent: true });
});
```

---

## 🔒 Security

All emails are signed with a secure HMAC SHA-256 signature using your secret key. The request is sent to the TOOB Mail API and verified server-side.

---

## 📄 License

MIT © [TOOB Creative Studio](https://www.toob.com.br)