`lumail@2.1.0` · [`lumail.emails`](/docs/sdk/v2/emails)

```typescript
emails.send(params: SendEmailParams, options?: { idempotencyKey?: string }): Promise<LumailResult<{ id: string }>>
```

Queues one transactional email. Exactly one of `html`, `tiptap`, or `markdown`. Unsupported: `attachments`, `template`, `topic_id`, `scheduled_at`, `react`, `content`, `contentType`.

## Body Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `from` | string | **Required.** Sender. Display name is allowed: `Acme <hello@yourdomain.com>`. Domain must be verified. |
| `to` | string or `[string]` | **Required.** One recipient. A one-address array is accepted. |
| `subject` | string | **Required.** Subject line. |
| `html` | string | HTML body. Provide exactly one of `html`, `tiptap`, or `markdown`. |
| `tiptap` | string or object | TipTap JSON. Rendered to HTML on send. |
| `markdown` | string | Markdown body. Rendered to HTML on send. |
| `text` | string | Plain-text body. Omit to generate from HTML. Empty string skips generation. |
| `reply_to` | string or string[] | Reply-To addresses. Stored as an array. SES uses the first address. |
| `cc` | string or string[] | Carbon copies. |
| `bcc` | string or string[] | Blind carbon copies. |
| `headers` | object | Extra MIME headers. |
| `tags` | `{ name, value }[]` | Metadata tags stored on the email. |
| `preview` | string | Preview / preheader text. |

## Options

| Name | Type | Description |
| ---- | ---- | ----------- |
| `idempotencyKey` | string | Second-argument option. Mapped to the `Idempotency-Key` header. Repeat the same key to reuse the queued email id. |

## Response Fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `id` | string | Queued email id (`eml_...`). Fetch the body and `last_event` with [`emails.get`](/docs/sdk/v2/emails-get). |

`data` is `{ id }`. Failures return `{ data: null, error: { name, message, statusCode } }`.


## API Reference
**Method:** POST
**Endpoint:** /api/v2/emails

### SDK
```ts
import { Lumail } from "lumail";

const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY });
const { data, error } = await lumail.emails.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Welcome",
  html: "<p>Hello</p>",
});
if (error) {
  throw error;
}
console.log(data.id);
```

### cURL
```bash
curl -X POST https://lumail.io/api/v2/emails \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "subject": "Welcome",
    "html": "<p>Hello</p>"
  }'
```

### JavaScript
```javascript
const response = await fetch("https://lumail.io/api/v2/emails", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@yourdomain.com",
    to: "user@example.com",
    subject: "Welcome",
    html: "<p>Hello</p>",
  }),
});
const data = await response.json();
```

### Success Response
```json
{ "id": "eml_abc123def456" }
```

### Error Response
```json
{
  "name": "validation_error",
  "message": "Provide exactly one of html, tiptap, or markdown",
  "statusCode": 422
}
```