@graph8/sdk 0.308.1 → 0.357.0

package/blocks/mailboxes/components/mailbox-list.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+/**
+ * MailboxList: the sending mailboxes in the workspace, with connection health and per-mailbox actions.
+ *
+ * SDK operations, in order:
+ *   1. listMailboxes          GET  /mailboxes                              (read; id, status, provider, warmup)
+ *   2. testMailboxConnection  POST /mailboxes/{mailbox_id}/test-connection (write; checks SMTP and IMAP, no spend)
+ *   3. archiveMailbox         POST /mailboxes/{mailbox_id}/archive         (destructive: confirmed)
+ *   4. deleteMailbox          DELETE /mailboxes/{mailbox_id}               (destructive: confirmed)
+ *
+ * Tiers: 3 and 4 are destructive, so each opens ConfirmSpendDialog first. Sequences that send from a
+ * deleted mailbox stop being able to send. Archiving only hides the mailbox and is reversible (restore with
+ * `is_archived: false`); it does not cancel a purchased mailbox's billing.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { listOf, objectOf, statusClass } from "../lib/mailboxes-utils";
+import type { MailboxRow } from "../lib/mailboxes-utils";
+
+export interface MailboxListProps {
+  includeArchived?: boolean;
+  /** Called when a row is opened (for example to show WarmupHealth for it). */
+  onSelect?: (mailbox: MailboxRow) => void;
+  /** Rendered when there are no mailboxes: usually a ConnectMailbox trigger. */
+  emptyAction?: React.ReactNode;
+  className?: string;
+}
+
+type Pending = { kind: "archive" | "delete"; mailbox: MailboxRow };
+
+interface TestResult {
+  success?: boolean;
+  smtp?: { success?: boolean; error?: string };
+  imap?: { success?: boolean; error?: string };
+}
+
+export function MailboxList({ includeArchived = false, onSelect, emptyAction, className }: MailboxListProps) {
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [tests, setTests] = useState<Record<string, string>>({});
+  const [testing, setTesting] = useState<ReadonlySet<string>>(new Set());
+  const list = useG8Query(
+    (signal) => g8Get("/mailboxes", { limit: 200, include_archived: includeArchived }, { signal }),
+    [includeArchived],
+  );
+
+  const test = useG8Mutation(async (m: MailboxRow) => {
+    setTesting((t) => new Set(t).add(m.id));
+    try {
+      const res = await g8Post(`/mailboxes/${m.id}/test-connection`, {});
+      const r = objectOf(res) as TestResult;
+      const msg = r.success
+        ? "SMTP and IMAP both work"
+        : [
+            r.smtp?.success === false && `SMTP: ${r.smtp.error ?? "failed"}`,
+            r.imap?.success === false && `IMAP: ${r.imap.error ?? "failed"}`,
+          ]
+            .filter(Boolean)
+            .join("; ") || "Connection failed";
+      setTests((t) => ({ ...t, [m.id]: msg }));
+      await list.refetch();
+    } finally {
+      setTesting((t) => {
+        const next = new Set(t);
+        next.delete(m.id);
+        return next;
+      });
+    }
+  });
+  const act = useG8Mutation(async (p: Pending) => {
+    if (p.kind === "archive") await g8Post(`/mailboxes/${p.mailbox.id}/archive`, { is_archived: true });
+    else await g8Delete(`/mailboxes/${p.mailbox.id}`);
+    await list.refetch();
+  });
+
+  const rows = listOf<MailboxRow>(list.data);
+  if (list.error) return <ApiError error={list.error} onRetry={() => void list.refetch()} className={className} />;
+  if (list.loading && !list.data) return <Skeleton className={`h-40 w-full ${className ?? ""}`} />;
+  if (rows.length === 0)
+    return (
+      <EmptyState
+        className={className}
+        title="No mailboxes yet"
+        description="Connect a mailbox you own, or buy new ones, to start sending."
+        action={emptyAction}
+      />
+    );
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      {act.error ? <ApiError error={act.error} onRetry={act.reset} /> : null}
+      {test.error ? <ApiError error={test.error} onRetry={test.reset} /> : null}
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Mailbox</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead>Warmup</TableHead>
+            <TableHead>Daily limit</TableHead>
+            <TableHead />
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((m) => (
+            <TableRow key={m.id}>
+              <TableCell>
+                <button type="button" className="text-left font-medium hover:underline" onClick={() => onSelect?.(m)}>
+                  {m.email ?? `Mailbox ${m.id}`}
+                </button>
+                <div className="text-xs text-gray-500">
+                  {m.display_name ?? ""}
+                  {m.provider ? ` - ${m.provider}` : ""}
+                  {m.is_archived ? " - archived" : ""}
+                </div>
+                {tests[m.id] ? (
+                  <div role="status" className="text-xs text-gray-700">
+                    {tests[m.id]}
+                  </div>
+                ) : null}
+              </TableCell>
+              <TableCell>
+                <span className={`rounded px-2 py-0.5 text-xs ${statusClass(m.connection_status)}`}>
+                  {m.connection_status ?? "unknown"}
+                </span>
+              </TableCell>
+              <TableCell>{m.warmup_status ?? "off"}</TableCell>
+              <TableCell>{m.daily_limit ?? "-"}</TableCell>
+              <TableCell className="space-x-1 text-right">
+                <Button
+                  size="sm"
+                  variant="outline"
+                  disabled={testing.has(m.id)}
+                  aria-label={`Test ${m.email}`}
+                  onClick={() => void test.mutate(m)}
+                >
+                  Test
+                </Button>
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  aria-label={`Archive ${m.email}`}
+                  onClick={() => setPending({ kind: "archive", mailbox: m })}
+                >
+                  Archive
+                </Button>
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  aria-label={`Delete ${m.email}`}
+                  onClick={() => setPending({ kind: "delete", mailbox: m })}
+                >
+                  Delete
+                </Button>
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      {pending ? (
+        <ConfirmSpendDialog
+          open
+          tier="destructive"
+          title={`${pending.kind === "delete" ? "Delete" : "Archive"} ${pending.mailbox.email ?? "this mailbox"}`}
+          description={
+            pending.kind === "delete"
+              ? "Sequences that send from it can no longer send. This cannot be undone."
+              : "It disappears from pickers. History is kept and you can restore it."
+          }
+          confirmLabel={pending.kind === "delete" ? "Delete mailbox" : "Archive mailbox"}
+          affected={1}
+          confirming={act.loading}
+          onCancel={() => setPending(null)}
+          onConfirm={() => void act.mutate(pending).then(() => setPending(null))}
+        />
+      ) : null}
+    </div>
+  );
+}

package/blocks/mailboxes/components/warmup-health.tsx

@@ -0,0 +1,232 @@
+"use client";
+
+/**
+ * WarmupHealth: is it safe to send? Fleet deliverability at a glance, the mailboxes in trouble, and warmup
+ * analytics (with start/stop and an inbox-placement test) for one mailbox.
+ *
+ * SDK operations, in order:
+ *   1. getFleetSummary           GET  /deliverability/fleet-summary          (read; counts by health, inbox rate)
+ *   2. getSafeToSend             GET  /deliverability/safe-to-send           (read; one verdict and why)
+ *   3. listDegradedMailboxes     GET  /deliverability/degraded               (read; worst first)
+ *   4. getMailboxWarmupAnalytics GET  /mailboxes/{mailbox_id}/warmup         (read; only when `mailboxId` is set)
+ *   5. enableWarmup / disableWarmup POST /warmup/{mailbox_id}/enable|disable (write; enabling starts SENDING warmup mail)
+ *   6. runMailboxPlacementTest   POST /mailboxes/{mailbox_id}/health/placement-test
+ *                                (billable: 20 credits, confirmed first; charged when created, not when done)
+ *
+ * Tiers: only 6 spends credits, so only it opens ConfirmSpendDialog. Show this before a launch; a `false`
+ * verdict with a live sequence running is the signal to pause rather than push.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { listOf, objectOf, PLACEMENT_TEST_CREDITS, scalars, statusClass } from "../lib/mailboxes-utils";
+
+export interface WarmupHealthProps {
+  /** Show warmup analytics and controls for this mailbox (an id from MailboxList). */
+  mailboxId?: string | number;
+  className?: string;
+}
+
+interface DegradedRow {
+  id?: string | number;
+  email?: string;
+  mailbox_email?: string;
+  severity?: string;
+  status?: string;
+  reason?: string;
+  reasons?: string[];
+}
+
+interface WarmupAnalytics {
+  warmup_enabled?: boolean | null;
+  provider?: string | null;
+  error?: string;
+  analytics?: {
+    status?: string;
+    total_sent?: number;
+    total_inbox?: number;
+    total_spam?: number;
+    inbox_rate?: number;
+    reputation?: number | null;
+    daily_stats?: Array<{ date: string; sent: number; inbox: number; spam: number }>;
+  } | null;
+}
+
+function Fleet() {
+  const summary = useG8Query((signal) => g8Get("/deliverability/fleet-summary", undefined, { signal }), []);
+  const verdict = useG8Query((signal) => g8Get("/deliverability/safe-to-send", undefined, { signal }), []);
+  const degraded = useG8Query((signal) => g8Get("/deliverability/degraded", { min_severity: "watch" }, { signal }), []);
+  if (summary.error) return <ApiError error={summary.error} onRetry={() => void summary.refetch()} />;
+  if (summary.loading && !summary.data) return <Skeleton className="h-24 w-full" />;
+
+  const v = objectOf(verdict.data);
+  // A verdict that failed or has not arrived is UNKNOWN, whatever else says: never fall back to the summary's flag.
+  const safe = verdict.error || verdict.loading ? undefined : (v.safe_to_send ?? v.safe ?? objectOf(summary.data).safe_to_send);
+  const rows = listOf<DegradedRow>(degraded.data);
+  return (
+    <div className="space-y-3">
+      <div
+        className={`rounded border p-3 ${safe === false ? "border-red-200 bg-red-50" : safe === true ? "border-green-200 bg-green-50" : "border-amber-200 bg-amber-50"}`}
+        role="status"
+        data-testid="send-verdict"
+      >
+        <p className="font-medium">
+          {safe === false ? "Not safe to send right now" : safe === true ? "Safe to send" : "Send status unknown"}
+        </p>
+        {verdict.error ? (
+          <p className="text-sm text-amber-900">
+            The deliverability check failed, so sending is not confirmed safe. Retry before you send.
+          </p>
+        ) : null}
+        {typeof v.reason === "string" ? <p className="text-sm text-gray-700">{v.reason}</p> : null}
+      </div>
+      <dl className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+        {scalars(objectOf(summary.data))
+          .filter(([k]) => k !== "safe to send")
+          .map(([k, val]) => (
+            <div key={k} className="rounded border border-gray-200 p-2">
+              <dt className="text-xs capitalize text-gray-500">{k}</dt>
+              <dd className="text-lg font-semibold">{val}</dd>
+            </div>
+          ))}
+      </dl>
+      {rows.length > 0 ? (
+        <ul className="divide-y rounded border border-gray-200" aria-label="Degraded mailboxes">
+          {rows.map((r, i) => (
+            <li key={String(r.id ?? i)} className="flex items-center justify-between px-3 py-2 text-sm">
+              <span>
+                {r.email ?? r.mailbox_email ?? `Mailbox ${r.id}`}
+                <span className="ml-2 text-xs text-gray-500">{r.reason ?? r.reasons?.join(", ")}</span>
+              </span>
+              <span className={`rounded px-2 py-0.5 text-xs ${statusClass(r.severity ?? r.status)}`}>
+                {r.severity ?? r.status ?? "watch"}
+              </span>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}
+
+function MailboxWarmup({ mailboxId }: { mailboxId: string | number }) {
+  const [confirm, setConfirm] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+  const warm = useG8Query((signal) => g8Get<WarmupAnalytics>(`/mailboxes/${mailboxId}/warmup`, undefined, { signal }), [mailboxId]);
+  const toggle = useG8Mutation(async (enable: boolean) => {
+    await g8Post(`/warmup/${mailboxId}/${enable ? "enable" : "disable"}`, {});
+    await warm.refetch();
+  });
+  const placement = useG8Mutation(async () => {
+    await g8Post(`/mailboxes/${mailboxId}/health/placement-test`, {});
+    setNote("Placement test started. Results appear in the mailbox's health.");
+  });
+
+  if (warm.error) return <ApiError error={warm.error} onRetry={() => void warm.refetch()} />;
+  if (warm.loading && !warm.data) return <Skeleton className="h-28 w-full" />;
+  const w = warm.data?.data;
+  const a = w?.analytics;
+  return (
+    <section className="space-y-3 rounded border border-gray-200 p-3" aria-label="Warmup">
+      <div className="flex items-center justify-between">
+        <h3 className="font-medium">
+          Warmup {w?.warmup_enabled ? "is on" : "is off"}
+          {w?.provider ? ` (${w.provider})` : ""}
+        </h3>
+        <div className="flex gap-2">
+          <Button
+            size="sm"
+            variant="outline"
+            disabled={toggle.loading || Boolean(w?.warmup_enabled)}
+            onClick={() => void toggle.mutate(true)}
+          >
+            Start warmup
+          </Button>
+          <Button size="sm" variant="outline" disabled={toggle.loading || !w?.warmup_enabled} onClick={() => void toggle.mutate(false)}>
+            Stop warmup
+          </Button>
+        </div>
+      </div>
+      {w?.error ? (
+        <p role="alert" className="text-sm text-amber-800">
+          The warmup provider did not answer: {w.error}
+        </p>
+      ) : null}
+      {a ? (
+        <>
+          <dl className="grid grid-cols-2 gap-2 sm:grid-cols-4 text-sm">
+            <div>
+              <dt className="text-xs text-gray-500">Sent</dt>
+              <dd className="font-semibold">{a.total_sent ?? 0}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-gray-500">Inbox rate</dt>
+              <dd className="font-semibold">
+                {a.inbox_rate != null ? `${Math.round(a.inbox_rate <= 1 ? a.inbox_rate * 100 : a.inbox_rate)}%` : "-"}
+              </dd>
+            </div>
+            <div>
+              <dt className="text-xs text-gray-500">Spam</dt>
+              <dd className="font-semibold">{a.total_spam ?? 0}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-gray-500">Reputation</dt>
+              <dd className="font-semibold">{a.reputation ?? "-"}</dd>
+            </div>
+          </dl>
+          {(a.daily_stats ?? []).length > 0 ? (
+            <div className="flex h-12 items-end gap-0.5" aria-label="Sent per day">
+              {a.daily_stats!.slice(-30).map((d) => (
+                <span
+                  key={d.date}
+                  title={`${d.date}: ${d.sent} sent, ${d.inbox} inbox`}
+                  className="w-2 rounded-t bg-blue-500"
+                  style={{ height: `${Math.max(4, Math.min(100, d.sent * 4))}%` }}
+                />
+              ))}
+            </div>
+          ) : null}
+        </>
+      ) : (
+        <p className="text-sm text-gray-500">No warmup analytics yet.</p>
+      )}
+      <Button size="sm" variant="outline" onClick={() => setConfirm(true)}>
+        Run placement test
+      </Button>
+      {toggle.error ? <ApiError error={toggle.error} onRetry={toggle.reset} /> : null}
+      {placement.error ? <ApiError error={placement.error} onRetry={placement.reset} /> : null}
+      {note ? (
+        <p role="status" className="text-sm text-green-700">
+          {note}
+        </p>
+      ) : null}
+      {confirm ? (
+        <ConfirmSpendDialog
+          open
+          tier="billable"
+          title="Run an inbox-placement test"
+          description="Sends test emails to see whether this mailbox reaches the inbox. Credits are charged when the test is created, even if it later fails."
+          estimatedCredits={PLACEMENT_TEST_CREDITS}
+          confirmLabel="Run test"
+          confirming={placement.loading}
+          onCancel={() => setConfirm(false)}
+          onConfirm={() => void placement.mutate(undefined).then(() => setConfirm(false))}
+        />
+      ) : null}
+    </section>
+  );
+}
+
+export function WarmupHealth({ mailboxId, className }: WarmupHealthProps) {
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <Fleet />
+      {mailboxId != null ? <MailboxWarmup mailboxId={mailboxId} /> : null}
+    </div>
+  );
+}

package/blocks/mailboxes/lib/mailboxes-utils.ts

@@ -0,0 +1,69 @@
+"use client";
+
+/** Types and helpers shared by the mailbox components. Open-shaped payloads: every field is optional. */
+
+/** Where the person connects a Google or Microsoft mailbox. OAuth consent can only run in the graph8 app. */
+export const GRAPH8_APP_MAILBOXES_URL = "https://app.graph8.com/studio/settings?tab=purchase&view=mailboxes";
+
+/** The API holds these when you buy (docs/developer-api-reference.md, Channel Purchase); the real rate can change. */
+export const DEFAULT_DOMAIN_CREDITS = 2500;
+export const DEFAULT_MAILBOX_CREDITS = 750;
+export const PLACEMENT_TEST_CREDITS = 20;
+
+export interface MailboxRow {
+  id: string;
+  email: string | null;
+  display_name?: string | null;
+  provider?: string | null;
+  connection_status?: string | null;
+  is_archived?: boolean | null;
+  daily_limit?: number | null;
+  warmup_provider?: string | null;
+  warmup_status?: string | null;
+  created_at?: string | null;
+}
+
+export interface DomainRow {
+  id: number;
+  domain: string;
+  source?: string;
+  status?: string | null;
+  provider_connected?: boolean;
+  mailbox_count?: number;
+  is_external?: boolean;
+}
+
+export function listOf<T>(envelope: unknown): T[] {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  if (Array.isArray(data)) return data as T[];
+  const items = (data as { items?: unknown } | null)?.items;
+  return Array.isArray(items) ? (items as T[]) : [];
+}
+
+export function objectOf(envelope: unknown): Record<string, unknown> {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+}
+
+/** Tailwind classes for a connection or health state. */
+export function statusClass(status: string | null | undefined): string {
+  const s = (status ?? "").toLowerCase();
+  if (["active", "connected", "healthy", "completed", "receiving"].includes(s)) return "bg-green-100 text-green-800";
+  if (["paused", "watch", "warming", "pending", "connecting", "provisioning"].includes(s)) return "bg-amber-100 text-amber-800";
+  if (s) return "bg-red-100 text-red-800";
+  return "bg-gray-100 text-gray-700";
+}
+
+/** Scalar fields of an open-shaped object, for a summary grid. */
+export function scalars(obj: Record<string, unknown>): Array<[string, string]> {
+  return Object.entries(obj)
+    .filter(([, v]) => ["string", "number", "boolean"].includes(typeof v))
+    .map(([k, v]) => [k.replace(/_/g, " "), typeof v === "number" && !Number.isInteger(v) ? v.toFixed(2) : String(v)]);
+}
+
+/** A fresh idempotency key for one confirmed purchase (reuse it if the same click is retried). */
+export function newIdempotencyKey(): string {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `g8-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}

package/blocks/mailboxes/recipes/buy-domain-and-mailboxes.ts

@@ -0,0 +1,64 @@
+/**
+ * @title Buy a sending domain, connect it, then buy mailboxes on it
+ * @when Provisioning sending infrastructure from scratch. THIS SPENDS REAL CREDITS and has no per-key cap
+ * (domains hold about 2,500 credits each, mailboxes about 750): get a human to approve the exact names and the
+ * estimate first. Both purchases use an Idempotency-Key DERIVED from the domain and usernames, so re-running this function after a
+ * failure (in polling, or in the connect step) finds the domain already owned and carries on from there, and the purchases use the same keys so nothing is bought twice; pass `attempt` only when you
+ * truly want a fresh purchase. 402 = hold could not
+ * clear, 422 = plan cannot fund purchases. Provisioning continues in the background: poll the domain list.
+ */
+import { createHash } from "node:crypto";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const key = (...parts: string[]): string => createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 40);
+
+export async function buyDomainAndMailbox(
+  domain: string,
+  usernames: string[],
+  registrant: { first_name: string; last_name: string; email: string },
+  humanApproved: boolean,
+  attempt = "1",
+) {
+  if (!humanApproved) throw new Error("Refusing to spend credits without approval");
+
+  const findDomain = async (): Promise<number | undefined> => {
+    const list = await g8.api.providerDomains.listProviderDomains({ query: { limit: 100 } });
+    return (list.data ?? []).find((d) => d.domain === domain)?.id;
+  };
+
+  // A re-run after a partial failure finds the domain already owned: skip the availability check (it is no
+  // longer available, because WE own it) and the domain purchase, and continue with connect and mailboxes.
+  let domainId = await findDomain();
+  if (domainId == null) {
+    const check = await g8.api.providerDomains.checkDomainAvailability({ body: { domain, provider: "registrar" } });
+    if (!(check.data as { available?: boolean } | undefined)?.available) throw new Error(`${domain} is not available`);
+
+    await g8.api.providerDomains.checkoutPurchaseDomains(
+      { body: { domains: [domain], period: 1, contact_info: registrant, provider: "registrar" } },
+      { idempotencyKey: key("domain", domain, attempt) },
+    );
+
+    // The purchase is asynchronous: wait for the domain to appear.
+    for (let i = 0; i < 20 && domainId == null; i++) {
+      await new Promise((resolve) => setTimeout(resolve, i === 0 ? 0 : 15000));
+      domainId = await findDomain();
+    }
+  }
+  if (domainId == null) throw new Error(`${domain} has not appeared yet; check again later`);
+
+  await g8.api.providerDomains.connectProvider({ path: { domain_id: domainId } });
+  return g8.api.providerDomains.checkoutPurchaseMailboxes(
+    {
+      path: { domain_id: domainId },
+      body: {
+        mailboxes: usernames.map((username) => ({ username, first_name: registrant.first_name, last_name: registrant.last_name })),
+        enable_warmup: true,
+        provider: "managed",
+        platform: "GOOGLE",
+      },
+    },
+    { idempotencyKey: key("mailboxes", domain, [...usernames].sort().join(","), attempt) },
+  );
+}

package/blocks/mailboxes/recipes/connect-imap-mailbox.ts

@@ -0,0 +1,38 @@
+/**
+ * @title Connect a mailbox you own over IMAP/SMTP and prove it works
+ * @when Adding an existing mailbox. Credentials are write-only: stored encrypted, never returned. Google and
+ * Microsoft mailboxes CANNOT be connected here (OAuth consent only runs in the graph8 app). Tier `write`:
+ * no spend, no email sent. Test right after creating; a failed test leaves the mailbox saved but unusable.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export interface ImapMailbox {
+  email: string;
+  smtpHost: string;
+  smtpPassword: string;
+  imapHost: string;
+  imapPassword: string;
+}
+
+export async function connectImapMailbox(m: ImapMailbox) {
+  const created = await g8.api.mailboxes.createMailbox({
+    body: {
+      email: m.email,
+      smtp_address: m.smtpHost,
+      smtp_username: m.email,
+      smtp_password: m.smtpPassword,
+      imap_address: m.imapHost,
+      imap_username: m.email,
+      imap_password: m.imapPassword,
+      daily_limit: 40,
+    },
+  });
+  const id = (created.data as { id?: number } | undefined)?.id;
+  if (id == null) throw new Error("graph8 did not return a mailbox id");
+
+  const test = await g8.api.mailboxes.testMailboxConnection({ path: { mailbox_id: id }, body: {} });
+  const ok = Boolean((test.data as { success?: boolean } | undefined)?.success);
+  return { mailboxId: id, connected: ok };
+}

package/blocks/mailboxes/recipes/is-it-safe-to-send.ts

@@ -0,0 +1,17 @@
+/**
+ * @title Check deliverability before a send
+ * @when Right before launching a sequence or a campaign. Reads only (no spend). A `false` verdict means do
+ * NOT enroll more contacts: list the degraded mailboxes, swap or pause them, and re-check later.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function safeToSend() {
+  const verdict = await g8.api.deliverability.getSafeToSend();
+  const v = (verdict.data ?? {}) as { safe_to_send?: boolean; reason?: string };
+  if (v.safe_to_send !== false) return { safe: true as const };
+
+  const degraded = await g8.api.deliverability.listDegradedMailboxes({ query: { min_severity: "watch" } });
+  return { safe: false as const, reason: v.reason, degraded: degraded.data };
+}

package/blocks/mailboxes/recipes/warmup-report.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Report warmup progress for every mailbox
+ * @when A daily report or before moving a mailbox into a sequence. Reads only. `warmup_enabled` and the live
+ * `analytics` come from the warmup provider, so a failed provider call comes back as `error`, not a throw.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface Warmup {
+  warmup_enabled?: boolean | null;
+  error?: string;
+  analytics?: { inbox_rate?: number; total_sent?: number; status?: string } | null;
+}
+
+export async function warmupReport() {
+  const mailboxes = await g8.api.gtmContext.listMailboxes({ query: { limit: 100 } });
+  const rows: Array<{ email: unknown; warmup: boolean; inboxRate?: number; sent?: number; error?: string }> = [];
+  for (const m of (mailboxes.data ?? []) as Array<{ id: string; email: string }>) {
+    const res = await g8.api.gtmContext.getMailboxWarmupAnalytics({ path: { mailbox_id: Number(m.id) } });
+    const w = (res.data ?? {}) as Warmup;
+    rows.push({
+      email: m.email,
+      warmup: Boolean(w.warmup_enabled),
+      inboxRate: w.analytics?.inbox_rate,
+      sent: w.analytics?.total_sent,
+      error: w.error,
+    });
+  }
+  return rows;
+}