> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> @gork/sdk — inboxes, messages, drafts, attachments, domains, webhooks.

```bash theme={null}
npm i @gork/sdk
```

## Client

```typescript theme={null}
import { Gork, GorkError, verifyGorkWebhook } from "@gork/sdk";

const gork = new Gork({
  apiKey: process.env.GORK_API_KEY, // falls back to GORK_KEY, then GORK_API_KEY
  baseUrl: process.env.GORK_BASE_URL, // default https://api.gork.email
});
```

## Inboxes

```typescript theme={null}
const inbox = await gork.inboxes.create({ username: "sdr-alex", name: "SDR Agent" });
const inboxes = await gork.inboxes.list();
const one = await gork.inboxes.get("inb_123");
await gork.inboxes.delete("inb_123");
```

## Messages & search

```typescript theme={null}
const msg = await gork.messages.send({
  inboxId: "inb_123",
  to: ["prospect@example.com"],
  subject: "Quick question",
  text: "Hi — got 10 minutes Thursday?",
});

// Idempotent send (safe retries)
await gork.messages.send(
  { inboxId: "inb_123", to: ["a@example.com"], subject: "Hi", text: "Hello" },
  { idempotencyKey: "campaign-1-user-42" }
);

const recent = await gork.messages.list({ inboxId: "inb_123", limit: 20 });
const hits = await gork.messages.search("invoice", { direction: "inbound" });
const full = await gork.messages.get("msg_123");
await gork.messages.cancelScheduled("msg_123"); // scheduled sends only
```

To reply in-thread, pass `inReplyTo` with the original message ID:

```typescript theme={null}
await gork.messages.send({
  inboxId: "inb_123",
  to: ["prospect@example.com"],
  subject: "Re: Quick question",
  text: "Bumping this up.",
  inReplyTo: "msg_original",
});
```

## Threads

```typescript theme={null}
const threads = await gork.threads.list({ inboxId: "inb_123" });
const thread = await gork.threads.get("thd_123");
```

## Drafts

```typescript theme={null}
const draft = await gork.drafts.create({ inboxId: "inb_123", to: ["a@example.com"], subject: "Hi" });
await gork.drafts.update(draft.id, { text: "Hello — final copy." });
await gork.drafts.send(draft.id); // idempotent per draft
const open = await gork.drafts.list({ status: "draft" });
await gork.drafts.discard(draft.id);
```

## Attachments

```typescript theme={null}
const bytes = await gork.attachments.download("att_123"); // ArrayBuffer
const csv = await gork.attachments.downloadText("att_123"); // decoded text
```

Send files with a message (`content` is base64 — max 10 files, 10MB each, 15MB total):

```typescript theme={null}
await gork.messages.send({
  inboxId: "inb_123",
  to: ["a@example.com"],
  subject: "Invoice attached",
  text: "See attached.",
  attachments: [{ filename: "invoice.pdf", contentType: "application/pdf", content: "<base64>" }],
});
```

## Domains

```typescript theme={null}
const domain = await gork.domains.create({ domain: "mail.example.com" });
await gork.domains.verify(domain.id);
await gork.domains.list();
await gork.domains.delete(domain.id);
```

## Suppressions

```typescript theme={null}
await gork.suppressions.create({ email: "bad@example.com", reason: "manual" });
await gork.suppressions.list({ reason: "hard_bounce" });
await gork.suppressions.delete("sup_123");
```

## API keys

```typescript theme={null}
const key = await gork.keys.create({ name: "agent-01", scopes: ["*"] });
await gork.keys.list();
await gork.keys.revoke("key_123");
```

## Webhooks

```typescript theme={null}
const hook = await gork.webhooks.create({
  url: "https://example.com/hooks/gork",
  subscribedEvents: ["email.received", "email.sent"],
});
await gork.webhooks.list();
await gork.webhooks.rotateSecret(hook.id);
await gork.webhooks.delete(hook.id);

// Verify X-Gork-Signature: t=<unix>,v1=<hex> (also exported standalone)
const ok = await gork.webhooks.verifySignature(rawBody, signatureHeader, secret);
const ok2 = await verifyGorkWebhook({ payload: rawBody, signature: signatureHeader, secret });
```

## Errors

```typescript theme={null}
try {
  await gork.messages.send({ inboxId: "inb_123", to: ["a@example.com"], subject: "Hi", text: "Hello" });
} catch (err) {
  if (err instanceof GorkError) {
    console.error(err.code, err.status, err.message); // err.details for field errors
  }
  throw err;
}
```