npm package: @hiveku-apps/email
Description: Official Node.js SDK for the Hiveku Transactional Email Service
Author: Hiveku
Latest version: 1.0.1

# @hiveku/email

Official Node.js / TypeScript SDK for the **Hiveku Transactional Email Service**.

Send transactional emails, manage sending domains, and track delivery stats — all through a simple API.

## Installation

```bash
npm install @hiveku-apps/email
```

## Quick start

```typescript
import HivekuEmail from '@hiveku-apps/email';

const email = new HivekuEmail('hk_live_YOUR_KEY');

await email.send({
  from: 'Acme <hello@notifications.acme.com>',
  to: 'user@example.com',
  subject: 'Welcome to Acme!',
  html: '<p>Thanks for signing up.</p>',
});
```

Or set `HIVEKU_EMAIL_API_KEY` in your environment and call the module-level helper:

```typescript
import { sendEmail } from '@hiveku-apps/email';

await sendEmail({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello World',
  html: '<p>Welcome!</p>',
});
```

## Usage with curl

```bash
curl -X POST https://api.hiveku.com/v1/email/send \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@notifications.acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme!",
    "html": "<p>Thanks for signing up.</p>"
  }'
```

## API

### `new HivekuEmail(apiKeyOrConfig?)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `apiKey` | `string` | Your Hiveku API key (`hk_live_...` or `hk_test_...`) |
| `baseUrl` | `string` | Override the API base URL |
| `timeout` | `number` | Request timeout in ms (default: `30000`) |

### Methods

| Method | Description |
|--------|-------------|
| `send(options)` | Send a single email |
| `sendBatch(emails[])` | Send up to 50 emails in one request |
| `listDomains()` | List all sending domains |
| `addDomain(domain)` | Add a domain and get DNS records |
| `verifyDomain(domainId)` | Re-check domain DNS verification |
| `deleteDomain(domainId)` | Remove a domain |
| `getUsage(options?)` | Get delivery stats |
| `generateSmtpCredentials()` | Generate SMTP credentials |

### `send(options)` options

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | `string` | ✓ | Sender — `"Name <email>"` or plain address |
| `to` | `string \| string[]` | ✓ | Recipient(s) |
| `subject` | `string` | ✓ | Subject line |
| `html` | `string` | | HTML body |
| `text` | `string` | | Plain-text body |
| `replyTo` | `string` | | Reply-to address |
| `cc` | `string[]` | | CC recipients |
| `bcc` | `string[]` | | BCC recipients |
| `headers` | `Record<string,string>` | | Custom headers |
| `tags` | `Record<string,string>` | | Tracking tags |
| `attachments` | `Attachment[]` | | File attachments (base64) |
| `scheduledAt` | `string` | | Schedule delivery (ISO 8601) |

## Environment variables

| Variable | Description |
|----------|-------------|
| `HIVEKU_EMAIL_API_KEY` | API key used by the default client |
| `HIVEKU_API_URL` | Override the API base URL |

## Links

- Dashboard: [app.hiveku.com](https://app.hiveku.com)
- API Docs: [app.hiveku.com/docs](https://app.hiveku.com/docs)
- Status: [status.hiveku.com](https://status.hiveku.com)

## License

MIT