Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(auth): handle Microsoft admin approval when linking Outlook (#8432)

gbirmanf7cdcdd196f2
diff --git a/Cargo.lock b/Cargo.lock
index 5e17fe674b..f27100eeae 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2110,6 +2110,7 @@ dependencies = [
"secretsmanager_client",
"serde",
"serde_json",
+ "serde_urlencoded",
"serde_utils",
"ses_client",
"sha1 0.10.6",
diff --git a/apps/web/src/features/auth/EmailAuth.test.tsx b/apps/web/src/features/auth/EmailAuth.test.tsx
index 1d28e412bf..fa09eebfe4 100644
--- a/apps/web/src/features/auth/EmailAuth.test.tsx
+++ b/apps/web/src/features/auth/EmailAuth.test.tsx
@@ -16,11 +16,20 @@ const mocks = vi.hoisted(() => ({
failure: vi.fn(),
success: vi.fn(),
linkId: 'oauth-link',
+ searchParams: {} as Record<string, string>,
restore: vi.fn(),
+ openAddInbox: vi.fn(),
+ fetchProviders: vi.fn(),
}));
vi.mock('@solidjs/router', () => ({
useNavigate: () => mocks.navigate,
- useSearchParams: () => [{ link_id: mocks.linkId }],
+ useSearchParams: () => [mocks.searchParams],
+}));
+vi.mock('@app/features/inbox/AddInboxDialog', () => ({
+ openAddInboxDialog: mocks.openAddInbox,
+}));
+vi.mock('@queries/auth/outlook-link', () => ({
+ fetchEmailConnectionProviders: mocks.fetchProviders,
}));
vi.mock('@core/email-link', () => ({
useEmailLinks: () => ({
@@ -56,6 +65,22 @@ vi.mock('@ui', () => ({
<button {...props} />
),
}));
+vi.mock('@app/features/inbox/AdminConsentRequiredDialog', () => ({
+ AdminConsentRequiredDialog: (props: {
+ adminConsentUrl: string | undefined;
+ onConnectDifferentAccount: () => void;
+ onClose: () => void;
+ }) => (
+ <div>
+ <p>Admin approval required</p>
+ <output>{props.adminConsentUrl ?? 'loading'}</output>
+ <button onClick={props.onConnectDifferentAccount}>
+ Connect a different account
+ </button>
+ <button onClick={props.onClose}>Close approval</button>
+ </div>
+ ),
+}));
vi.mock('@app/features/inbox/ShareInboxConflictDialog', () => ({
ShareInboxConflictDialog: (props: {
onShare: () => void;
@@ -79,6 +104,13 @@ const { EmailLinkCallback } = makeEmailAuthComponents({
beforeEach(() => {
vi.clearAllMocks();
mocks.linkId = 'oauth-link';
+ mocks.searchParams = { link_id: mocks.linkId };
+ mocks.fetchProviders.mockResolvedValue({
+ gmail: true,
+ outlook: true,
+ outlook_admin_consent_url:
+ 'https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=app',
+ });
mocks.refetch.mockResolvedValue({});
mocks.restore.mockReturnValue({ url: '/calendar/week' });
mocks.init.mockReturnValue(okAsync(undefined));
@@ -164,3 +196,102 @@ describe('inbox consent callback', () => {
await waitFor(() => expect(mocks.navigate).toHaveBeenCalledOnce());
});
});
+
+describe('consent that ended without a grant', () => {
+ it('explains admin approval with the tenant-wide link and never provisions', async () => {
+ mocks.searchParams = {
+ link_id: 'oauth-link',
+ email_link_error: 'admin_consent_required',
+ provider: 'outlook',
+ };
+ render(() => <EmailLinkCallback />);
+ expect(await screen.findByText('Admin approval required')).toBeTruthy();
+ await waitFor(() =>
+ expect(screen.getByRole('status').textContent).toContain(
+ 'login.microsoftonline.com/organizations/v2.0/adminconsent'
+ )
+ );
+ expect(mocks.init).not.toHaveBeenCalled();
+ expect(mocks.navigate).not.toHaveBeenCalled();
+
+ await fireEvent.click(
+ screen.getByRole('button', { name: 'Close approval' })
+ );
+ expect(mocks.navigate).toHaveBeenCalledWith('/calendar/week', {
+ replace: true,
+ });
+ expect(mocks.restore).toHaveBeenCalledWith('oauth-link');
+ });
+
+ it('reopens the connect dialog for a different account', async () => {
+ mocks.searchParams = {
+ link_id: 'oauth-link',
+ email_link_error: 'admin_consent_required',
+ provider: 'outlook',
+ };
+ render(() => <EmailLinkCallback />);
+ await fireEvent.click(
+ await screen.findByRole('button', { name: 'Connect a different account' })
+ );
+ expect(mocks.openAddInbox).toHaveBeenCalledOnce();
+ expect(mocks.navigate).toHaveBeenCalledOnce();
+ });
+
+ it('leaves the copy action unavailable when the approval link cannot load', async () => {
+ mocks.fetchProviders.mockRejectedValue(new Error('offline'));
+ mocks.searchParams = {
+ link_id: 'oauth-link',
+ email_link_error: 'admin_consent_required',
+ provider: 'outlook',
+ };
+ render(() => <EmailLinkCallback />);
+ expect(await screen.findByText('Admin approval required')).toBeTruthy();
+ await waitFor(() => expect(mocks.fetchProviders).toHaveBeenCalledOnce());
+ expect(screen.getByRole('status').textContent).toBe('loading');
+ });
+
+ it('returns quietly when the user cancelled on the consent screen', async () => {
+ mocks.searchParams = {
+ link_id: 'oauth-link',
+ email_link_error: 'cancelled',
+ provider: 'outlook',
+ };
+ render(() => <EmailLinkCallback />);
+ await waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith('/calendar/week', {
+ replace: true,
+ })
+ );
+ expect(mocks.failure).not.toHaveBeenCalled();
+ expect(mocks.init).not.toHaveBeenCalled();
+ });
+
+ it('reports any other provider failure and returns', async () => {
+ mocks.searchParams = {
+ link_id: 'oauth-link',
+ email_link_error: 'failed',
+ provider: 'outlook',
+ };
+ render(() => <EmailLinkCallback />);
+ await waitFor(() => expect(mocks.failure).toHaveBeenCalledOnce());
+ expect(mocks.navigate).toHaveBeenCalledWith('/calendar/week', {
+ replace: true,
+ });
+ });
+
+ it('invites an administrator who just approved the tenant to connect again', async () => {
+ mocks.searchParams = {
+ email_link_notice: 'admin_consent_granted',
+ provider: 'outlook',
+ };
+ render(() => <EmailLinkCallback />);
+ await waitFor(() =>
+ expect(mocks.success).toHaveBeenCalledWith(
+ 'Approved. Try connecting again.'
+ )
+ );
+ expect(mocks.openAddInbox).toHaveBeenCalledOnce();
+ expect(mocks.restore).not.toHaveBeenCalled();
+ expect(mocks.navigate).toHaveBeenCalledOnce();
+ });
+});
diff --git a/apps/web/src/features/auth/EmailAuth.tsx b/apps/web/src/features/auth/EmailAuth.tsx
index ba74b05e69..33be4ad2c0 100644
--- a/apps/web/src/features/auth/EmailAuth.tsx
+++ b/apps/web/src/features/auth/EmailAuth.tsx
@@ -1,4 +1,6 @@
import { DEFAULT_ROUTE } from '@app/constants/defaultRoute';
+import { openAddInboxDialog } from '@app/features/inbox/AddInboxDialog';
+import { AdminConsentRequiredDialog } from '@app/features/inbox/AdminConsentRequiredDialog';
import { ShareInboxConflictDialog } from '@app/features/inbox/ShareInboxConflictDialog';
import { useAnalytics } from '@app/lib/analytics/analytics-context';
import { updateUserAuth } from '@core/auth';
@@ -15,13 +17,21 @@ import { fireAndForget } from '@core/util/fireAndForget';
import { whenSettled } from '@core/util/whenSettled';
import { Telemetry } from '@macro-inc/observability';
import SpinnerIcon from '@phosphor/spinner-gap.svg';
+import { fetchEmailConnectionProviders } from '@queries/auth/outlook-link';
import {
invalidateAllAfterLogin,
useUserInfoQuery,
} from '@queries/auth/user-info';
import { useNavigate, useSearchParams } from '@solidjs/router';
import { Button } from '@ui';
-import { createSignal, onCleanup, onMount, Show, Suspense } from 'solid-js';
+import {
+ createSignal,
+ Match,
+ onCleanup,
+ onMount,
+ Suspense,
+ Switch,
+} from 'solid-js';
type EmailAuthParams = {
callbackPath: string;
@@ -113,9 +123,31 @@ function EmailSignupCallback(props: Pick<EmailAuthParams, 'successPath'>) {
const POST_LINK_FALLBACK_ROUTE = `${DEFAULT_ROUTE}/~/settings/${settingsTabToSlug('Connected')}`;
/**
- * Handles the OAuth callback after an already-authenticated user adds another Gmail
- * inbox via /link/gmail. Reads `link_id` from the query string and invokes init to
- * provision the second `email_links` row. Falls back to a toast on failure.
+ * The `email_link_notice` the auth service sends an administrator back with
+ * after they approve Macro for their Microsoft 365 tenant.
+ */
+const ADMIN_CONSENT_GRANTED_NOTICE = 'admin_consent_granted';
+
+/**
+ * The `email_link_error` values the auth service redirects back with when a
+ * consent screen ends without a grant. Anything else is a generic failure.
+ */
+const ADMIN_CONSENT_REQUIRED_ERROR = 'admin_consent_required';
+const CONSENT_CANCELLED_ERROR = 'cancelled';
+
+const stringParam = (value: string | string[] | undefined) =>
+ typeof value === 'string' ? value : null;
+
+/**
+ * Handles the OAuth callback after an already-authenticated user adds another
+ * inbox via /link/gmail or /link/outlook. Reads `link_id` from the query string
+ * and invokes init to provision the second `email_links` row. Falls back to a
+ * toast on failure.
+ *
+ * A consent screen that ended without a grant arrives with `email_link_error`
+ * instead: a cancel goes straight back, a tenant that needs admin approval
+ * gets the dialog with the approval link, and anything else gets a toast.
+ * An administrator who approved the tenant arrives with `email_link_notice`.
*
* Web consent navigates the page; desktop returns from the system browser via
* a deep link. Both replace the split layout URL. The add-inbox flow stashed it
@@ -135,6 +167,10 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
emailAddress: string;
ownerEmail: string;
} | null>(null);
+ const [adminConsent, setAdminConsent] = createSignal<{
+ linkId: string | null;
+ url: string | undefined;
+ } | null>(null);
const navigateToSuccess = () => {
navigate(props.successPath, { replace: true });
@@ -157,7 +193,7 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
// onboarding for a first-run user, then the layout they left, then a
// form-factor default — the list view on mobile, where the desktop settings
// split doesn't exist and the toast is the confirmation.
- const navigateAfterLink = (linkId: string) => {
+ const navigateAfterLink = (linkId: string | null) => {
if (disposed) return;
// A first-run user connected this inbox from the onboarding flow:
// return straight to it. Landing in mail settings would mount the app
@@ -170,7 +206,7 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
navigate('/onboarding', { replace: true });
return;
}
- if (restoreLayoutBeforeConsent(linkId)) return;
+ if (linkId && restoreLayoutBeforeConsent(linkId)) return;
if (isMobile()) {
navigateToSuccess();
return;
@@ -232,11 +268,52 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
}
};
+ // The consent screen ended without a grant. The pending link is already
+ // released server-side; this only explains the outcome and hands off.
+ const handleConsentFailure = (error: string, linkId: string | null) => {
+ if (error === CONSENT_CANCELLED_ERROR) {
+ navigateAfterLink(linkId);
+ return;
+ }
+ if (error !== ADMIN_CONSENT_REQUIRED_ERROR) {
+ toast.failure('Failed to connect your account. Please try again.');
+ navigateAfterLink(linkId);
+ return;
+ }
+ setAdminConsent({ linkId, url: undefined });
+ fireAndForget(loadAdminConsentUrl(), 'email-auth');
+ };
+
+ // The approval link is built server-side so the client never carries the
+ // Microsoft client id. The dialog stays open while it loads; a failure
+ // leaves the copy action disabled with an explanation.
+ const loadAdminConsentUrl = async () => {
+ const providers = await fetchEmailConnectionProviders();
+ setAdminConsent((current) =>
+ current
+ ? { ...current, url: providers.outlook_admin_consent_url ?? undefined }
+ : current
+ );
+ };
+
// Completing consent does not depend on the old inbox list loading first.
// A paused or slow query must not prevent the new grant from being applied.
onMount(() => {
- const linkId =
- typeof searchParams.link_id === 'string' ? searchParams.link_id : null;
+ const linkId = stringParam(searchParams.link_id);
+ if (
+ stringParam(searchParams.email_link_notice) ===
+ ADMIN_CONSENT_GRANTED_NOTICE
+ ) {
+ toast.success('Approved. Try connecting again.');
+ openAddInboxDialog();
+ navigateAfterLink(linkId);
+ return;
+ }
+ const linkError = stringParam(searchParams.email_link_error);
+ if (linkError) {
+ handleConsentFailure(linkError, linkId);
+ return;
+ }
if (!linkId) {
toast.failure('Missing link id in callback URL');
navigateToSuccess();
@@ -247,8 +324,7 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
});
return (
- <Show
- when={conflict()}
+ <Switch
fallback={
<div class="flex size-full items-center justify-center p-6">
<div
@@ -266,14 +342,9 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
<Button
variant="outline"
size="sm"
- onClick={() => {
- const linkId =
- typeof searchParams.link_id === 'string'
- ? searchParams.link_id
- : undefined;
- if (linkId) navigateAfterLink(linkId);
- else navigateToSuccess();
- }}
+ onClick={() =>
+ navigateAfterLink(stringParam(searchParams.link_id))
+ }
>
Back to app
</Button>
@@ -281,24 +352,45 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {
</div>
}
>
- {(c) => (
- <ShareInboxConflictDialog
- open
- emailAddress={c().emailAddress}
- ownerEmail={c().ownerEmail}
- onCancel={() => {
- const linkId = c().linkId;
- setConflict(null);
- if (!restoreLayoutBeforeConsent(linkId)) navigateToSuccess();
- }}
- onShare={() => {
- const linkId = c().linkId;
- setConflict(null);
- fireAndForget(runInit(linkId, true), 'email-auth');
- }}
- />
- )}
- </Show>
+ <Match when={adminConsent()}>
+ {(consent) => (
+ <AdminConsentRequiredDialog
+ open
+ adminConsentUrl={consent().url}
+ onClose={() => {
+ const linkId = consent().linkId;
+ setAdminConsent(null);
+ navigateAfterLink(linkId);
+ }}
+ onConnectDifferentAccount={() => {
+ const linkId = consent().linkId;
+ setAdminConsent(null);
+ openAddInboxDialog();
+ navigateAfterLink(linkId);
+ }}
+ />
+ )}
+ </Match>
+ <Match when={conflict()}>
+ {(c) => (
+ <ShareInboxConflictDialog
+ open
+ emailAddress={c().emailAddress}
+ ownerEmail={c().ownerEmail}
+ onCancel={() => {
+ const linkId = c().linkId;
+ setConflict(null);
+ if (!restoreLayoutBeforeConsent(linkId)) navigateToSuccess();
+ }}
+ onShare={() => {
+ const linkId = c().linkId;
+ setConflict(null);
+ fireAndForget(runInit(linkId, true), 'email-auth');
+ }}
+ />
+ )}
+ </Match>
+ </Switch>
);
}
diff --git a/apps/web/src/features/inbox/AdminConsentRequiredDialog.test.tsx b/apps/web/src/features/inbox/AdminConsentRequiredDialog.test.tsx
new file mode 100644
index 0000000000..366163ad07
--- /dev/null
+++ b/apps/web/src/features/inbox/AdminConsentRequiredDialog.test.tsx
@@ -0,0 +1,101 @@
+import { cleanup, fireEvent, render, screen } from '@solidjs/testing-library';
+import type { JSX, ParentProps } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AdminConsentRequiredDialog } from './AdminConsentRequiredDialog';
+
+const mocks = vi.hoisted(() => ({
+ success: vi.fn(),
+ failure: vi.fn(),
+ writeText: vi.fn(),
+}));
+vi.mock('@core/component/Toast/Toast', () => ({
+ toast: { success: mocks.success, failure: mocks.failure },
+}));
+vi.mock('@ui', () => {
+ const Slot = (props: ParentProps) => <div>{props.children}</div>;
+ return {
+ Button: (props: JSX.ButtonHTMLAttributes<HTMLButtonElement>) => (
+ <button {...props} />
+ ),
+ Dialog: Object.assign(Slot, { Title: Slot, Description: Slot }),
+ Panel: Object.assign(Slot, { Header: Slot, Body: Slot }),
+ };
+});
+
+const APPROVAL_URL =
+ 'https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=app&state=signed';
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ Object.defineProperty(navigator, 'clipboard', {
+ configurable: true,
+ value: { writeText: mocks.writeText },
+ });
+ mocks.writeText.mockResolvedValue(undefined);
+});
+afterEach(cleanup);
+
+describe('admin approval dialog', () => {
+ it('copies the tenant-wide approval link for IT', async () => {
+ render(() => (
+ <AdminConsentRequiredDialog
+ open
+ adminConsentUrl={APPROVAL_URL}
+ onConnectDifferentAccount={() => {}}
+ onClose={() => {}}
+ />
+ ));
+ expect(
+ screen.getByText(
+ 'Your organization requires an IT admin to approve Macro before you can connect this account.'
+ )
+ ).toBeTruthy();
+ await fireEvent.click(
+ screen.getByRole('button', { name: 'Copy admin approval link' })
+ );
+ await vi.waitFor(() =>
+ expect(mocks.writeText).toHaveBeenCalledWith(APPROVAL_URL)
+ );
+ await vi.waitFor(() => expect(mocks.success).toHaveBeenCalledOnce());
+ });
+
+ it('reports a clipboard that refuses the link', async () => {
+ mocks.writeText.mockRejectedValue(new Error('denied'));
+ render(() => (
+ <AdminConsentRequiredDialog
+ open
+ adminConsentUrl={APPROVAL_URL}
+ onConnectDifferentAccount={() => {}}
+ onClose={() => {}}
+ />
+ ));
+ await fireEvent.click(
+ screen.getByRole('button', { name: 'Copy admin approval link' })
+ );
+ await vi.waitFor(() => expect(mocks.failure).toHaveBeenCalledOnce());
+ expect(mocks.success).not.toHaveBeenCalled();
+ });
+
+ it('keeps the copy action unavailable without a link and offers another account', async () => {
+ const onConnectDifferentAccount = vi.fn();
+ render(() => (
+ <AdminConsentRequiredDialog
+ open
+ adminConsentUrl={undefined}
+ onConnectDifferentAccount={onConnectDifferentAccount}
+ onClose={() => {}}
+ />
+ ));
+ const copy = screen.getByRole('button', {
+ name: 'Copy admin approval link',
+ }) as HTMLButtonElement;
+ expect(copy.disabled).toBe(true);
+ expect(
+ screen.getByText(/The approval link is unavailable right now/)
+ ).toBeTruthy();
+ await fireEvent.click(
+ screen.getByRole('button', { name: 'Connect a different account' })
+ );
+ expect(onConnectDifferentAccount).toHaveBeenCalledOnce();
+ });
+});
diff --git a/apps/web/src/features/inbox/AdminConsentRequiredDialog.tsx b/apps/web/src/features/inbox/AdminConsentRequiredDialog.tsx
new file mode 100644
index 0000000000..2f369015b1
--- /dev/null
+++ b/apps/web/src/features/inbox/AdminConsentRequiredDialog.tsx
@@ -0,0 +1,79 @@
+import { toast } from '@core/component/Toast/Toast';
+import { fireAndForget } from '@core/util/fireAndForget';
+import { Button, Dialog, Panel } from '@ui';
+import { Show } from 'solid-js';
+
+/**
+ * Shown when a Microsoft 365 tenant lets only an administrator consent to
+ * Macro's permissions. The user cannot finish on their own: they copy the
+ * tenant-wide approval link for IT, or connect a different account instead.
+ */
+export function AdminConsentRequiredDialog(props: {
+ open: boolean;
+ /** Tenant-wide approval link; absent while loading or when Outlook is off. */
+ adminConsentUrl: string | undefined;
+ onConnectDifferentAccount: () => void;
+ onClose: () => void;
+}) {
+ const copyApprovalLink = async () => {
+ const url = props.adminConsentUrl;
+ if (!url) return;
+ try {
+ await navigator.clipboard.writeText(url);
+ } catch {
+ toast.failure('Could not copy link');
+ return;
+ }
+ toast.success('Admin approval link copied', {
+ subtext: 'Send it to your IT admin. Once approved, connect again.',
+ });
+ };
+
+ return (
+ <Dialog
+ open={props.open}
+ onOpenChange={(open) => {
+ if (!open) props.onClose();
+ }}
+ position="center"
+ class="w-120 max-w-[calc(100vw-2rem)]"
+ >
+ <Panel depth={2} class="rounded-xl">
+ <Panel.Header class="px-6">
+ <Dialog.Title class="text-ink text-sm font-semibold">
+ Admin approval required
+ </Dialog.Title>
+ </Panel.Header>
+ <Panel.Body class="p-6 font-sans flex flex-col gap-3">
+ <Dialog.Description class="text-ink-muted text-sm/tight font-normal">
+ Your organization requires an IT admin to approve Macro before you
+ can connect this account.
+ </Dialog.Description>
+ <Show when={props.adminConsentUrl === undefined}>
+ <p class="text-ink-muted text-sm">
+ The approval link is unavailable right now. Try again later or
+ connect a different account.
+ </p>
+ </Show>
+ <div class="pt-3 flex flex-col-reverse sm:flex-row sm:justify-end sm:items-center gap-3">
+ <Button
+ variant="ghost"
+ depth={3}
+ onClick={() => props.onConnectDifferentAccount()}
+ >
+ Connect a different account
+ </Button>
+ <Button
+ variant="strong"
+ depth={3}
+ disabled={props.adminConsentUrl === undefined}
+ onClick={() => fireAndForget(copyApprovalLink(), 'inbox-link')}
+ >
+ Copy admin approval link
+ </Button>
+ </div>
+ </Panel.Body>
+ </Panel>
+ </Dialog>
+ );
+}
diff --git a/apps/web/src/lib/queries/auth/outlook-link.ts b/apps/web/src/lib/queries/auth/outlook-link.ts
index 187c429292..55030e5cfa 100644
--- a/apps/web/src/lib/queries/auth/outlook-link.ts
+++ b/apps/web/src/lib/queries/auth/outlook-link.ts
@@ -1,4 +1,5 @@
import { throwOnErr } from '@core/util/result';
+import { getWebOrigin } from '@core/util/webOrigin';
import { authServiceClient } from '@service-auth/client';
import { useMutation } from '@tanstack/solid-query';
import { queryClient } from '../client';
@@ -15,12 +16,21 @@ export function useInitOutlookLink() {
}));
}
+/**
+ * Where a Microsoft administrator lands after approving Macro. Always the web
+ * app: the link is copied for someone else, often on another device, so a
+ * desktop deep link or native callback would not reach them.
+ */
+const adminConsentReturnUrl = () => `${getWebOrigin()}/app/inbox-link-callback`;
+
/** Fetch on opening the chooser, without suspending unrelated application UI. */
export function fetchEmailConnectionProviders() {
return queryClient.fetchQuery({
queryKey: authKeys.emailConnectionProviders.queryKey,
queryFn: () =>
- throwOnErr(() => authServiceClient.emailConnectionProviders()),
+ throwOnErr(() =>
+ authServiceClient.emailConnectionProviders(adminConsentReturnUrl())
+ ),
staleTime: 0,
});
}
diff --git a/apps/web/src/lib/service-clients/service-auth/client.ts b/apps/web/src/lib/service-clients/service-auth/client.ts
index 6887f2f691..fb5c503ebe 100644
--- a/apps/web/src/lib/service-clients/service-auth/client.ts
+++ b/apps/web/src/lib/service-clients/service-auth/client.ts
@@ -26,6 +26,7 @@ import type {
CheckoutSessionV2Response,
CursorApiKeyStatus,
CursorModelsResponse,
+ EmailConnectionProviders,
EnrichGithubPullRequestsProxyRequest,
EnrichGithubPullRequestsResponse,
GithubLinkStatusResponse,
@@ -313,9 +314,16 @@ const githubErrorResponseHandler: ErrorResponseHandler<GithubReauthenticationErr
};
export const authServiceClient = {
- async emailConnectionProviders() {
- return fetchWithAuth<{ gmail: boolean; outlook: boolean }>(
- `${authHost}/link/email/providers`,
+ /**
+ * Which providers this deployment can connect. Pass `originalUrl` to also
+ * receive the Microsoft tenant-wide admin-consent URL that returns there.
+ */
+ async emailConnectionProviders(originalUrl?: string) {
+ const params = new URLSearchParams();
+ if (originalUrl) params.set('original_url', originalUrl);
+ const query = params.size > 0 ? `?${params}` : '';
+ return fetchWithAuth<EmailConnectionProviders>(
+ `${authHost}/link/email/providers${query}`,
{ method: 'GET' }
);
},
diff --git a/apps/web/src/lib/service-clients/service-auth/generated/client.ts b/apps/web/src/lib/service-clients/service-auth/generated/client.ts
index 4e75d7d9f8..4a04928fb7 100644
--- a/apps/web/src/lib/service-clients/service-auth/generated/client.ts
+++ b/apps/web/src/lib/service-clients/service-auth/generated/client.ts
@@ -26,6 +26,7 @@ import type {
CursorApiKeyStatus,
CursorModelsResponse,
EmailConnectionProviders,
+ EmailConnectionProvidersParams,
EmptyResponse,
EnrichGithubPullRequestsProxyRequest,
EnrichGithubPullRequestsResponse,
@@ -2222,22 +2223,47 @@ export type emailConnectionProvidersResponse200 = {
status: 200;
};
+export type emailConnectionProvidersResponse400 = {
+ data: ErrorResponse;
+ status: 400;
+};
+
export type emailConnectionProvidersResponseSuccess =
emailConnectionProvidersResponse200 & {
headers: Headers;
};
+export type emailConnectionProvidersResponseError =
+ emailConnectionProvidersResponse400 & {
+ headers: Headers;
+ };
export type emailConnectionProvidersResponse =
- emailConnectionProvidersResponseSuccess;
+ | emailConnectionProvidersResponseSuccess
+ | emailConnectionProvidersResponseError;
-export const getEmailConnectionProvidersUrl = () => {
- return `/link/email/providers`;
+export const getEmailConnectionProvidersUrl = (
+ params?: EmailConnectionProvidersParams
+) => {
+ const normalizedParams = new URLSearchParams();
+
+ Object.entries(params || {}).forEach(([key, value]) => {
+ if (value !== undefined) {
+ normalizedParams.append(key, value === null ? 'null' : value.toString());
+ }
+ });
+
+ const stringifiedParams = normalizedParams.toString();
+
+ return stringifiedParams.length > 0
+ ? `/link/email/providers?${stringifiedParams}`
+ : `/link/email/providers`;
};
export const emailConnectionProviders = async (
+ params?: EmailConnectionProvidersParams,
options?: RequestInit
): Promise<emailConnectionProvidersResponse> => {
- const res = await fetch(getEmailConnectionProvidersUrl(), {
+ const res = await fetch(getEmailConnectionProvidersUrl(params), {
...options,
method: 'GET',
});
@@ -3342,6 +3368,11 @@ export type oauth2CallbackResponse200 = {
status: 200;
};
+export type oauth2CallbackResponse303 = {
+ data: void;
+ status: 303;
+};
+
export type oauth2CallbackResponse304 = {
data: ErrorResponse;
status: 304;
@@ -3371,6 +3402,7 @@ export type oauth2CallbackResponseSuccess = oauth2CallbackResponse200 & {
headers: Headers;
};
export type oauth2CallbackResponseError = (
+ | oauth2CallbackResponse303
| oauth2CallbackResponse304
| oauth2CallbackResponse307
| oauth2CallbackResponse400
diff --git a/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProviders.ts b/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProviders.ts
index b8186863fe..722e8e8d95 100644
--- a/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProviders.ts
+++ b/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProviders.ts
@@ -4,6 +4,7 @@
* authentication_service
* OpenAPI spec version: 0.1.0
*/
+import type { EmailConnectionProvidersOutlookAdminConsentUrl } from './emailConnectionProvidersOutlookAdminConsentUrl';
/**
* Actual deployment availability for the provider selector.
@@ -11,4 +12,8 @@
export interface EmailConnectionProviders {
gmail: boolean;
outlook: boolean;
+ /** Where a Microsoft 365 administrator approves Macro for their whole
+directory. Present when Outlook is configured and the request named an
+`original_url` for the administrator's browser to return to. */
+ outlook_admin_consent_url?: EmailConnectionProvidersOutlookAdminConsentUrl;
}
diff --git a/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProvidersOutlookAdminConsentUrl.ts b/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProvidersOutlookAdminConsentUrl.ts
new file mode 100644
index 0000000000..7fa9bb1e8c
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProvidersOutlookAdminConsentUrl.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * authentication_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Where a Microsoft 365 administrator approves Macro for their whole
+directory. Present when Outlook is configured and the request named an
+`original_url` for the administrator's browser to return to.
+ */
+export type EmailConnectionProvidersOutlookAdminConsentUrl = string | null;
diff --git a/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProvidersParams.ts b/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProvidersParams.ts
new file mode 100644
index 0000000000..deb0ab156d
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-auth/generated/schemas/emailConnectionProvidersParams.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * authentication_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type EmailConnectionProvidersParams = {
+ /**
+ * **OPTIONAL**. Where the admin-consent flow returns to; required for `outlook_admin_consent_url`.
+ */
+ original_url?: string;
+};
diff --git a/apps/web/src/lib/service-clients/service-auth/generated/schemas/index.ts b/apps/web/src/lib/service-clients/service-auth/generated/schemas/index.ts
index e78a872e31..14a5ab36f2 100644
--- a/apps/web/src/lib/service-clients/service-auth/generated/schemas/index.ts
+++ b/apps/web/src/lib/service-clients/service-auth/generated/schemas/index.ts
@@ -51,6 +51,8 @@ export * from './cursorModelOption';
export * from './cursorModelsResponse';
export * from './denyReason';
export * from './emailConnectionProviders';
+export * from './emailConnectionProvidersOutlookAdminConsentUrl';
+export * from './emailConnectionProvidersParams';
export * from './emptyResponse';
export * from './enrichedGithubPullRequest';
export * from './enrichedGithubPullRequestAdditions';
diff --git a/apps/web/src/lib/service-clients/service-auth/openapi.json b/apps/web/src/lib/service-clients/service-auth/openapi.json
index 233035bf32..4aacf78ac8 100644
--- a/apps/web/src/lib/service-clients/service-auth/openapi.json
+++ b/apps/web/src/lib/service-clients/service-auth/openapi.json
@@ -1772,6 +1772,17 @@
"get": {
"tags": ["link::outlook"],
"operationId": "email_connection_providers",
+ "parameters": [
+ {
+ "name": "original_url",
+ "in": "query",
+ "description": "**OPTIONAL**. Where the admin-consent flow returns to; required for `outlook_admin_consent_url`.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
"responses": {
"200": {
"description": "",
@@ -1782,6 +1793,16 @@
}
}
}
+ },
+ "400": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
}
}
@@ -2832,6 +2853,9 @@
"200": {
"description": ""
},
+ "303": {
+ "description": "Back to the app with link identifiers, an `email_link_error`, or an `email_link_notice`"
+ },
"304": {
"description": "",
"content": {
@@ -5650,6 +5674,10 @@
},
"outlook": {
"type": "boolean"
+ },
+ "outlook_admin_consent_url": {
+ "type": ["string", "null"],
+ "description": "Where a Microsoft 365 administrator approves Macro for their whole\ndirectory. Present when Outlook is configured and the request named an\n`original_url` for the administrator's browser to return to."
}
}
},
diff --git a/crates/agent_code_mode/src/domain/documentation.json b/crates/agent_code_mode/src/domain/documentation.json
index 65a57add36..9ab032a789 100644
--- a/crates/agent_code_mode/src/domain/documentation.json
+++ b/crates/agent_code_mode/src/domain/documentation.json
@@ -105,7 +105,7 @@
"name": "email",
"description": "Search, read, draft, and send email.",
"overview": "<!-- src/entities/email/draft/type-aliases/DraftOptions.md -->\n# Type Alias: DraftOptions\n\n> **DraftOptions** = `Omit`\\<[`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md), `\"db_id\"` \\| `\"provider_id\"` \\| `\"provider_thread_id\"` \\| `\"replying_to_id\"` \\| `\"thread_db_id\"` \\| `\"body_text\"` \\| `\"body_html\"` \\| `\"body_macro\"` \\| `\"headers_json\"` \\| `\"include_signature\"`\\> & \\{ `bodyHtml?`: `string`; `bodyMacro?`: `string`; `bodyText?`: `string`; `headers?`: [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\\[`\"headers_json\"`\\]; `includeSignature?`: `boolean`; `replyingTo?`: [`EmailMessage`](../../message/classes/EmailMessage.md); `thread?`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}\n\nDraft content; relationships use message and thread handles.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `bodyHtml?` | `string` | HTML body. |\n| `bodyMacro?` | `string` | Macro body. |\n| `bodyText?` | `string` | Plain text body. |\n| `headers?` | [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\\[`\"headers_json\"`\\] | Extra headers. |\n| `includeSignature?` | `boolean` | Include the inbox signature. |\n| `replyingTo?` | [`EmailMessage`](../../message/classes/EmailMessage.md) | Message being replied to. |\n| `thread?` | [`EmailThread`](../../thread/classes/EmailThread.md) | Thread receiving this draft. |\n\n\n<!-- src/entities/email/filter/interfaces/EmailFilterOptions.md -->\n# Interface: EmailFilterOptions\n\nSender importance rule.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress?` | `string` | Match an address. |\n| <a id=\"property-emaildomain\"></a> `emailDomain?` | `string` | Match a domain. |\n| <a id=\"property-isimportant\"></a> `isImportant` | `boolean` | Whether matches are important. |\n\n\n<!-- src/entities/email/message/interfaces/SendEmailOptions.md -->\n# Interface: SendEmailOptions\n\nOptions for sending a fresh email message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Bcc recipients. |\n| <a id=\"property-bodytext\"></a> `bodyText` | `string` | Plain-text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Cc recipients. |\n| <a id=\"property-subject\"></a> `subject` | `string` | Subject line. |\n| <a id=\"property-to\"></a> `to` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Recipients. |\n\n\n<!-- src/entities/email/namespace/classes/EmailNamespace.md -->\n# Class: EmailNamespace\n\n## Constructors\n\n### Constructor\n\n> **new EmailNamespace**(`client`): `EmailNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`EmailNamespace`\n\n## Methods\n\n### attachment()\n\n> **attachment**(`id`): [`EmailAttachment`](../../attachment/classes/EmailAttachment.md)\n\nA handle to an email attachment by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)\n\n***\n\n### blockedSenders()\n\n> **blockedSenders**(): `Promise`\\<`string`[]\\>\n\nThe email addresses currently blocked.\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### blockSender()\n\n> **blockSender**(`email`): `Promise`\\<`void`\\>\n\nBlock an email sender.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `email` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> **byId**(`id`): [`EmailThread`](../../thread/classes/EmailThread.md)\n\nA handle to an email thread by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailThread`](../../thread/classes/EmailThread.md)\n\n***\n\n### connectionProviders()\n\n> **connectionProviders**(): `Promise`\\<[`EmailConnectionProviders`](../../../../../generated/auth/types.gen/type-aliases/EmailConnectionProviders.md)\\>\n\nProviders the server currently permits this caller to connect.\n\n#### Returns\n\n`Promise`\\<[`EmailConnectionProviders`](../../../../../generated/auth/types.gen/type-aliases/EmailConnectionProviders.md)\\>\n\n***\n\n### contacts()\n\n> **contacts**(): `Promise`\\<\\{\\[`key`: `string`\\]: [`ContactInfoWithInteraction`](../../../../../generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md)[]; \\}\\>\n\nAddress book contacts grouped by the service's interaction buckets.\n\n#### Returns\n\n`Promise`\\<\\{\\[`key`: `string`\\]: [`ContactInfoWithInteraction`](../../../../../generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md)[]; \\}\\>\n\n***\n\n### createDraft()\n\n> **createDraft**(`options`, `inbox?`): `Promise`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\nCreate a draft without sending it; the inbox defaults to the caller's primary.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../../draft/type-aliases/DraftOptions.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\n***\n\n### createLabel()\n\n> **createLabel**(`name`): `Promise`\\<[`Label`](../../label/classes/Label.md)\\>\n\nCreate a user label. Returns the created label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Label`](../../label/classes/Label.md)\\>\n\n***\n\n### deleteLabel()\n\n> **deleteLabel**(`label`): `Promise`\\<`void`\\>\n\nDelete a label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### draftById()\n\n> **draftById**(`id`): [`EmailDraft`](../../draft/classes/EmailDraft.md)\n\nConstruct a lazy draft handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailDraft`](../../draft/classes/EmailDraft.md)\n\n***\n\n### filters()\n\n> **filters**(`inbox?`): `Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)[]\\>\n\nImportance filters.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)[]\\>\n\n***\n\n### inbox()\n\n> **inbox**(`opts?`): `AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe threads in the inbox, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`InboxOptions`](../interfaces/InboxOptions.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### label()\n\n> **label**(`id`): [`Label`](../../label/classes/Label.md)\n\nA handle to a label by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Label`](../../label/classes/Label.md)\n\n***\n\n### labels()\n\n> **labels**(): `Promise`\\<[`Label`](../../label/classes/Label.md)[]\\>\n\nAll labels across the user's inboxes.\n\n#### Returns\n\n`Promise`\\<[`Label`](../../label/classes/Label.md)[]\\>\n\n***\n\n### link()\n\n> **link**(`id`): [`Link`](../../link/classes/Link.md)\n\nA handle to a connected inbox (email link) by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Link`](../../link/classes/Link.md)\n\n***\n\n### links()\n\n> **links**(): `Promise`\\<[`Link`](../../link/classes/Link.md)[]\\>\n\nThe caller's connected inboxes (email links).\n\n#### Returns\n\n`Promise`\\<[`Link`](../../link/classes/Link.md)[]\\>\n\n***\n\n### message()\n\n> **message**(`id`): [`EmailMessage`](../../message/classes/EmailMessage.md)\n\nA handle to an email message by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailMessage`](../../message/classes/EmailMessage.md)\n\n***\n\n### recoverDraftTransfer()\n\n> **recoverDraftTransfer**(`operationId`): `Promise`\\<[`TransferRecoveryResponse`](../../../../../generated/email/types.gen/type-aliases/TransferRecoveryResponse.md)\\>\n\nRecover a draft move using its original operation UUID; never starts a new move.\nAn empty committed result fences the old move so it cannot commit later.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `operationId` | `string` |\n\n#### Returns\n\n`Promise`\\<[`TransferRecoveryResponse`](../../../../../generated/email/types.gen/type-aliases/TransferRecoveryResponse.md)\\>\n\n***\n\n### reminders()\n\n> **reminders**(`options?`): `AsyncGenerator`\\<\\{ `followup`: [`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md); `thread`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}, `any`, `any`\\>\n\nFollow-up reminders with thread handles, automatically paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | `Omit`\\<\\{ `attachments?`: `string`[] \\| `null`; `calendar?`: `boolean` \\| `null`; `cursor?`: `string` \\| `null`; `done?`: `boolean` \\| `null`; `inboxIds?`: `string`[] \\| `null`; `limit?`: `number` \\| `null`; `noInboxes?`: `boolean` \\| `null`; `read?`: `boolean` \\| `null`; `tags?`: `string`[] \\| `null`; \\}, `\"cursor\"` \\| `\"inboxIds\"`\\> & \\{ `inboxes?`: [`Link`](../../link/classes/Link.md)[]; \\} |\n\n#### Returns\n\n`AsyncGenerator`\\<\\{ `followup`: [`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md); `thread`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}, `any`, `any`\\>\n\n***\n\n### scheduled()\n\n> **scheduled**(`options?`): `AsyncGenerator`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\nScheduled drafts, fetched lazily in bounded pages.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `inbox?`: [`Link`](../../link/classes/Link.md); `pageSize?`: `number`; \\} |\n| `options.inbox?` | [`Link`](../../link/classes/Link.md) |\n| `options.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nSearch email threads by subject and content.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### send()\n\n> **send**(`opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a new email message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | [`SendEmailOptions`](../../message/interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n***\n\n### unblockSender()\n\n> **unblockSender**(`email`): `Promise`\\<`void`\\>\n\nUnblock a previously blocked sender.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `email` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### upsertFilter()\n\n> **upsertFilter**(`options`, `inbox?`): `Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)\\>\n\nCreate or replace a filter matching an address or domain.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`EmailFilterOptions`](../../filter/interfaces/EmailFilterOptions.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)\\>\n\n\n<!-- src/entities/email/namespace/interfaces/InboxOptions.md -->\n# Interface: InboxOptions\n\nOptions for listing inbox threads.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-pagesize\"></a> `pageSize?` | `number` | Page size (default 20, max 500). |\n| <a id=\"property-sort\"></a> `sort?` | [`ApiSortMethod`](../../../../../generated/email/types.gen/type-aliases/ApiSortMethod.md) | Sort order. Defaults to `viewed_updated`. |\n",
- "documentation": "# Macro SDK: email\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/auth/types.gen/type-aliases/EmailConnectionProviders.md -->\n# Type Alias: EmailConnectionProviders\n\n> **EmailConnectionProviders** = \\{ `gmail`: `boolean`; `outlook`: `boolean`; \\}\n\nActual deployment availability for the provider selector.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-gmail\"></a> `gmail` | `boolean` |\n| <a id=\"property-outlook\"></a> `outlook` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/email/types.gen/type-aliases/ApiAttachmentDraft.md -->\n# Type Alias: ApiAttachmentDraft\n\n> **ApiAttachmentDraft** = \\{ `content_id?`: `string` \\| `null`; `content_type`: `string`; `draft_id`: `string`; `file_name`: `string`; `id`: `string`; `is_inline`: `boolean`; `s3_key`: `string`; `sha`: `string`; `size`: `number`; `upload_pending`: `boolean`; \\}\n\nAPI representation of a draft attachment on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-content_id\"></a> `content_id?` | `string` \\| `null` |\n| <a id=\"property-content_type\"></a> `content_type` | `string` |\n| <a id=\"property-draft_id\"></a> `draft_id` | `string` |\n| <a id=\"property-file_name\"></a> `file_name` | `string` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-is_inline\"></a> `is_inline` | `boolean` |\n| <a id=\"property-s3_key\"></a> `s3_key` | `string` |\n| <a id=\"property-sha\"></a> `sha` | `string` |\n| <a id=\"property-size\"></a> `size` | `number` |\n| <a id=\"property-upload_pending\"></a> `upload_pending` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiAttachmentForwarded.md -->\n# Type Alias: ApiAttachmentForwarded\n\n> **ApiAttachmentForwarded** = \\{ `attachment_id`: `string`; `draft_id`: `string`; `filename?`: `string` \\| `null`; `message_provider_id`: `string`; `mime_type?`: `string` \\| `null`; `provider_attachment_id?`: `string` \\| `null`; `size_bytes?`: `number` \\| `null`; \\}\n\nAPI representation of a forwarded attachment on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachment_id\"></a> `attachment_id` | `string` |\n| <a id=\"property-draft_id\"></a> `draft_id` | `string` |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` |\n| <a id=\"property-message_provider_id\"></a> `message_provider_id` | `string` |\n| <a id=\"property-mime_type\"></a> `mime_type?` | `string` \\| `null` |\n| <a id=\"property-provider_attachment_id\"></a> `provider_attachment_id?` | `string` \\| `null` |\n| <a id=\"property-size_bytes\"></a> `size_bytes?` | `number` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiContactInfo.md -->\n# Type Alias: ApiContactInfo\n\n> **ApiContactInfo** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\nAPI representation of a contact (sender or recipient).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiDraftContactInfo.md -->\n# Type Alias: ApiDraftContactInfo\n\n> **ApiDraftContactInfo** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\nContact info for draft request/response (backward-compatible with MessageToSend shape).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Email address. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Display name. |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` | Profile photo URL. |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiDraftInput.md -->\n# Type Alias: ApiDraftInput\n\n> **ApiDraftInput** = \\{ `bcc?`: [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null`; `body_html?`: `string` \\| `null`; `body_macro?`: `string` \\| `null`; `body_text?`: `string` \\| `null`; `cc?`: [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null`; `db_id?`: `string` \\| `null`; `headers_json?`: `null` \\| [`Value`](Value.md); `include_signature?`: `boolean` \\| `null`; `provider_id?`: `string` \\| `null`; `provider_thread_id?`: `string` \\| `null`; `replying_to_id?`: `string` \\| `null`; `subject`: `string`; `thread_db_id?`: `string` \\| `null`; `to?`: [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null`; \\}\n\nThe draft input matching the current `MessageToSend` JSON shape for backward compat.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null` | Bcc recipients. |\n| <a id=\"property-body_html\"></a> `body_html?` | `string` \\| `null` | HTML body (base64 URL_SAFE_NO_PAD encoded). Sanitized before storage. |\n| <a id=\"property-body_macro\"></a> `body_macro?` | `string` \\| `null` | Macro body format. |\n| <a id=\"property-body_text\"></a> `body_text?` | `string` \\| `null` | Plain text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null` | Cc recipients. |\n| <a id=\"property-db_id\"></a> `db_id?` | `string` \\| `null` | Existing message DB ID (for updating an existing draft). |\n| <a id=\"property-headers_json\"></a> `headers_json?` | `null` \\| [`Value`](Value.md) | - |\n| <a id=\"property-include_signature\"></a> `include_signature?` | `boolean` \\| `null` | Per-message override for whether to include the signature on send: `Some(false)` to exclude (user dismissed it). Omit to use the inbox's default policy. Ignored for drafts. |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` | Provider message ID. |\n| <a id=\"property-provider_thread_id\"></a> `provider_thread_id?` | `string` \\| `null` | Provider thread ID. |\n| <a id=\"property-replying_to_id\"></a> `replying_to_id?` | `string` \\| `null` | ID of the message this draft is replying to. |\n| <a id=\"property-subject\"></a> `subject` | `string` | Subject line. |\n| <a id=\"property-thread_db_id\"></a> `thread_db_id?` | `string` \\| `null` | Thread DB ID. |\n| <a id=\"property-to\"></a> `to?` | [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null` | To recipients. |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiEmailFilter.md -->\n# Type Alias: ApiEmailFilter\n\n> **ApiEmailFilter** = \\{ `created_at`: `string`; `email_address?`: `string` \\| `null`; `email_domain?`: `string` \\| `null`; `id`: `string`; `is_important`: `boolean`; \\}\n\nA single email filter in API responses.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-email_address\"></a> `email_address?` | `string` \\| `null` |\n| <a id=\"property-email_domain\"></a> `email_domain?` | `string` \\| `null` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-is_important\"></a> `is_important` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiLabel.md -->\n# Type Alias: ApiLabel\n\n> **ApiLabel** = \\{ `createdAt`: `string`; `id`: `string`; `labelListVisibility`: [`ApiLabelListVisibility`](ApiLabelListVisibility.md); `linkId`: `string`; `messageListVisibility`: [`ApiMessageListVisibility`](ApiMessageListVisibility.md); `name`: `string`; `providerLabelId`: `string`; `type`: [`ApiLabelType`](ApiLabelType.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-labellistvisibility\"></a> `labelListVisibility` | [`ApiLabelListVisibility`](ApiLabelListVisibility.md) |\n| <a id=\"property-linkid\"></a> `linkId` | `string` |\n| <a id=\"property-messagelistvisibility\"></a> `messageListVisibility` | [`ApiMessageListVisibility`](ApiMessageListVisibility.md) |\n| <a id=\"property-name\"></a> `name` | `string` |\n| <a id=\"property-providerlabelid\"></a> `providerLabelId` | `string` |\n| <a id=\"property-type\"></a> `type` | [`ApiLabelType`](ApiLabelType.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiLabelListVisibility.md -->\n# Type Alias: ApiLabelListVisibility\n\n> **ApiLabelListVisibility** = `\"LabelShow\"` \\| `\"LabelShowIfUnread\"` \\| `\"LabelHide\"`\n\n\n<!-- generated/email/types.gen/type-aliases/ApiLabelType.md -->\n# Type Alias: ApiLabelType\n\n> **ApiLabelType** = `\"System\"` \\| `\"User\"`\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessage.md -->\n# Type Alias: ApiMessage\n\n> **ApiMessage** = \\{ `attachments`: [`ApiMessageAttachment`](ApiMessageAttachment.md)[]; `attachments_draft`: [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[]; `attachments_forwarded`: [`ApiAttachmentForwarded`](ApiAttachmentForwarded.md)[]; `bcc`: [`ApiContactInfo`](ApiContactInfo.md)[]; `body_html_sanitized?`: `string` \\| `null`; `body_macro?`: `string` \\| `null`; `body_replyless?`: `string` \\| `null`; `body_text?`: `string` \\| `null`; `calendar_invitations?`: [`CalendarInvitation`](CalendarInvitation.md)[]; `cc`: [`ApiContactInfo`](ApiContactInfo.md)[]; `created_at`: `string`; `db_id`: `string`; `from?`: `null` \\| [`ApiContactInfo`](ApiContactInfo.md); `global_id?`: `string` \\| `null`; `has_attachments`: `boolean`; `headers_json?`: `unknown`; `internal_date_ts?`: `string` \\| `null`; `is_draft`: `boolean`; `is_read`: `boolean`; `is_sent`: `boolean`; `is_starred`: `boolean`; `labels`: [`ApiMessageLabel`](ApiMessageLabel.md)[]; `link_id`: `string`; `operation_status?`: `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md); `provider_history_id?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `provider_thread_id?`: `string` \\| `null`; `replying_to_id?`: `string` \\| `null`; `scheduled_send_time?`: `string` \\| `null`; `sent_at?`: `string` \\| `null`; `size_estimate?`: `number` \\| `null`; `snippet?`: `string` \\| `null`; `subject?`: `string` \\| `null`; `thread_db_id`: `string`; `to`: [`ApiContactInfo`](ApiContactInfo.md)[]; `updated_at`: `string`; \\}\n\nAPI representation of a fully assembled email message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`ApiMessageAttachment`](ApiMessageAttachment.md)[] |\n| <a id=\"property-attachments_draft\"></a> `attachments_draft` | [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[] |\n| <a id=\"property-attachments_forwarded\"></a> `attachments_forwarded` | [`ApiAttachmentForwarded`](ApiAttachmentForwarded.md)[] |\n| <a id=\"property-bcc\"></a> `bcc` | [`ApiContactInfo`](ApiContactInfo.md)[] |\n| <a id=\"property-body_html_sanitized\"></a> `body_html_sanitized?` | `string` \\| `null` |\n| <a id=\"property-body_macro\"></a> `body_macro?` | `string` \\| `null` |\n| <a id=\"property-body_replyless\"></a> `body_replyless?` | `string` \\| `null` |\n| <a id=\"property-body_text\"></a> `body_text?` | `string` \\| `null` |\n| <a id=\"property-calendar_invitations\"></a> `calendar_invitations?` | [`CalendarInvitation`](CalendarInvitation.md)[] |\n| <a id=\"property-cc\"></a> `cc` | [`ApiContactInfo`](ApiContactInfo.md)[] |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-from\"></a> `from?` | `null` \\| [`ApiContactInfo`](ApiContactInfo.md) |\n| <a id=\"property-global_id\"></a> `global_id?` | `string` \\| `null` |\n| <a id=\"property-has_attachments\"></a> `has_attachments` | `boolean` |\n| <a id=\"property-headers_json\"></a> `headers_json?` | `unknown` |\n| <a id=\"property-internal_date_ts\"></a> `internal_date_ts?` | `string` \\| `null` |\n| <a id=\"property-is_draft\"></a> `is_draft` | `boolean` |\n| <a id=\"property-is_read\"></a> `is_read` | `boolean` |\n| <a id=\"property-is_sent\"></a> `is_sent` | `boolean` |\n| <a id=\"property-is_starred\"></a> `is_starred` | `boolean` |\n| <a id=\"property-labels\"></a> `labels` | [`ApiMessageLabel`](ApiMessageLabel.md)[] |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-operation_status\"></a> `operation_status?` | `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md) |\n| <a id=\"property-provider_history_id\"></a> `provider_history_id?` | `string` \\| `null` |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` |\n| <a id=\"property-provider_thread_id\"></a> `provider_thread_id?` | `string` \\| `null` |\n| <a id=\"property-replying_to_id\"></a> `replying_to_id?` | `string` \\| `null` |\n| <a id=\"property-scheduled_send_time\"></a> `scheduled_send_time?` | `string` \\| `null` |\n| <a id=\"property-sent_at\"></a> `sent_at?` | `string` \\| `null` |\n| <a id=\"property-size_estimate\"></a> `size_estimate?` | `number` \\| `null` |\n| <a id=\"property-snippet\"></a> `snippet?` | `string` \\| `null` |\n| <a id=\"property-subject\"></a> `subject?` | `string` \\| `null` |\n| <a id=\"property-thread_db_id\"></a> `thread_db_id` | `string` |\n| <a id=\"property-to\"></a> `to` | [`ApiContactInfo`](ApiContactInfo.md)[] |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageAttachment.md -->\n# Type Alias: ApiMessageAttachment\n\n> **ApiMessageAttachment** = \\{ `content_id?`: `string` \\| `null`; `data_url?`: `string` \\| `null`; `db_id`: `string`; `filename?`: `string` \\| `null`; `mime_type?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `reference_url?`: `string` \\| `null`; `sfs_id?`: `string` \\| `null`; `size_bytes?`: `number` \\| `null`; \\}\n\nAPI representation of a provider attachment on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-content_id\"></a> `content_id?` | `string` \\| `null` |\n| <a id=\"property-data_url\"></a> `data_url?` | `string` \\| `null` |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` |\n| <a id=\"property-mime_type\"></a> `mime_type?` | `string` \\| `null` |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` |\n| <a id=\"property-reference_url\"></a> `reference_url?` | `string` \\| `null` |\n| <a id=\"property-sfs_id\"></a> `sfs_id?` | `string` \\| `null` |\n| <a id=\"property-size_bytes\"></a> `size_bytes?` | `number` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageLabel.md -->\n# Type Alias: ApiMessageLabel\n\n> **ApiMessageLabel** = \\{ `created_at`: `string`; `id?`: `string` \\| `null`; `label_list_visibility?`: `null` \\| [`ApiLabelListVisibility`](ApiLabelListVisibility.md); `link_id`: `string`; `message_list_visibility?`: `null` \\| [`ApiMessageListVisibility`](ApiMessageListVisibility.md); `name?`: `string` \\| `null`; `provider_label_id`: `string`; `type_?`: `null` \\| [`ApiLabelType`](ApiLabelType.md); \\}\n\nAPI representation of a label on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-id\"></a> `id?` | `string` \\| `null` |\n| <a id=\"property-label_list_visibility\"></a> `label_list_visibility?` | `null` \\| [`ApiLabelListVisibility`](ApiLabelListVisibility.md) |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-message_list_visibility\"></a> `message_list_visibility?` | `null` \\| [`ApiMessageListVisibility`](ApiMessageListVisibility.md) |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-provider_label_id\"></a> `provider_label_id` | `string` |\n| <a id=\"property-type_\"></a> `type_?` | `null` \\| [`ApiLabelType`](ApiLabelType.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageListVisibility.md -->\n# Type Alias: ApiMessageListVisibility\n\n> **ApiMessageListVisibility** = `\"Show\"` \\| `\"Hide\"`\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageOperation.md -->\n# Type Alias: ApiMessageOperation\n\n> **ApiMessageOperation** = \\{ `issue?`: `null` \\| [`ApiMessageOperationIssue`](ApiMessageOperationIssue.md); `remote_version?`: `string` \\| `null`; `revision`: `string`; `state`: [`ApiMessageOperationState`](ApiMessageOperationState.md); \\}\n\nVersions are opaque decimal strings so clients never truncate an i64.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-issue\"></a> `issue?` | `null` \\| [`ApiMessageOperationIssue`](ApiMessageOperationIssue.md) |\n| <a id=\"property-remote_version\"></a> `remote_version?` | `string` \\| `null` |\n| <a id=\"property-revision\"></a> `revision` | `string` |\n| <a id=\"property-state\"></a> `state` | [`ApiMessageOperationState`](ApiMessageOperationState.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageOperationIssue.md -->\n# Type Alias: ApiMessageOperationIssue\n\n> **ApiMessageOperationIssue** = `\"ACCEPTING_REMOTE\"` \\| `\"DRAFT_CONFLICT\"` \\| `\"CREATION_UNKNOWN\"` \\| `\"ATTACHMENT_UNKNOWN\"` \\| `\"SEND_UNKNOWN\"` \\| `\"SEND_REJECTED\"` \\| `\"ACCESS_REVOKED\"` \\| `\"INVALID_CONTENT\"` \\| `\"MOVE_PENDING\"` \\| `\"MOVE_CONFLICT\"` \\| `\"MOVE_SOURCE_SENT\"` \\| `\"MOVE_REAUTHORIZATION\"` \\| `\"MOVE_ORIGINAL_REMAINS\"`\n\nProvider-neutral state exposed to clients.\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageOperationState.md -->\n# Type Alias: ApiMessageOperationState\n\n> **ApiMessageOperationState** = `\"PENDING\"` \\| `\"SYNCHRONIZED\"` \\| `\"CONFLICT\"` \\| `\"UNCERTAIN\"` \\| `\"SUBMITTING\"` \\| `\"CONFIRMING\"` \\| `\"SENT\"` \\| `\"DELETED\"` \\| `\"CANCELLED\"` \\| `\"FAILED\"`\n\nProvider-neutral state exposed to clients.\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageResolutionAction.md -->\n# Type Alias: ApiMessageResolutionAction\n\n> **ApiMessageResolutionAction** = `\"keep_local\"` \\| `\"use_provider\"` \\| `\"recheck\"` \\| `\"retry_send\"` \\| `\"keep_original\"`\n\nA deliberate resolution of a particular observed operation version.\n\n\n<!-- generated/email/types.gen/type-aliases/ApiSortMethod.md -->\n# Type Alias: ApiSortMethod\n\n> **ApiSortMethod** = `\"viewed_at\"` \\| `\"updated_at\"` \\| `\"created_at\"` \\| `\"viewed_updated\"`\n\ncommon types of sorts based on timestamps\n\n\n<!-- generated/email/types.gen/type-aliases/ApiThread.md -->\n# Type Alias: ApiThread\n\n> **ApiThread** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `created_at`: `string`; `db_id`: `string`; `inbox_visible`: `boolean`; `is_read`: `boolean`; `latest_inbound_message_ts?`: `string` \\| `null`; `latest_non_spam_message_ts?`: `string` \\| `null`; `latest_outbound_message_ts?`: `string` \\| `null`; `link_id`: `string`; `messages`: [`ApiMessage`](ApiMessage.md)[]; `project_id?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nAPI representation of a fully assembled email thread.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-inbox_visible\"></a> `inbox_visible` | `boolean` |\n| <a id=\"property-is_read\"></a> `is_read` | `boolean` |\n| <a id=\"property-latest_inbound_message_ts\"></a> `latest_inbound_message_ts?` | `string` \\| `null` |\n| <a id=\"property-latest_non_spam_message_ts\"></a> `latest_non_spam_message_ts?` | `string` \\| `null` |\n| <a id=\"property-latest_outbound_message_ts\"></a> `latest_outbound_message_ts?` | `string` \\| `null` |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-messages\"></a> `messages` | [`ApiMessage`](ApiMessage.md)[] |\n| <a id=\"property-project_id\"></a> `project_id?` | `string` \\| `null` |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/Attachment.md -->\n# Type Alias: Attachment\n\n> **Attachment** = \\{ `content_id?`: `string` \\| `null`; `data_url?`: `string` \\| `null`; `db_id`: `string`; `filename?`: `string` \\| `null`; `mime_type?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `reference_url?`: `string` \\| `null`; `sfs_id?`: `string` \\| `null`; `size_bytes?`: `number` \\| `null`; \\}\n\nAttachments of a message, as sent to us by the provider.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-content_id\"></a> `content_id?` | `string` \\| `null` | - |\n| <a id=\"property-data_url\"></a> `data_url?` | `string` \\| `null` | - |\n| <a id=\"property-db_id\"></a> `db_id` | `string` | - |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` | - |\n| <a id=\"property-mime_type\"></a> `mime_type?` | `string` \\| `null` | - |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` | - |\n| <a id=\"property-reference_url\"></a> `reference_url?` | `string` \\| `null` | Cloud reference: open this provider page instead of downloading bytes. |\n| <a id=\"property-sfs_id\"></a> `sfs_id?` | `string` \\| `null` | - |\n| <a id=\"property-size_bytes\"></a> `size_bytes?` | `number` \\| `null` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/AttendeeResponseStatus.md -->\n# Type Alias: AttendeeResponseStatus\n\n> **AttendeeResponseStatus** = `\"needs_action\"` \\| `\"accepted\"` \\| `\"declined\"` \\| `\"tentative\"`\n\nRSVP state for an attendee.\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarAttendee.md -->\n# Type Alias: CalendarAttendee\n\n> **CalendarAttendee** = \\{ `comment?`: `string` \\| `null`; `displayName?`: `string` \\| `null`; `email`: `string`; `isOptional`: `boolean`; `isOrganizer`: `boolean`; `isSelf`: `boolean`; `responseStatus`: [`AttendeeResponseStatus`](AttendeeResponseStatus.md); \\}\n\nAn attendee on a calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Optional attendee comment. |\n| <a id=\"property-displayname\"></a> `displayName?` | `string` \\| `null` | Provider display name. |\n| <a id=\"property-email\"></a> `email` | `string` | Normalized email address. |\n| <a id=\"property-isoptional\"></a> `isOptional` | `boolean` | Whether attendance is optional. |\n| <a id=\"property-isorganizer\"></a> `isOrganizer` | `boolean` | Whether this attendee is the organizer. |\n| <a id=\"property-isself\"></a> `isSelf` | `boolean` | Whether this attendee is one of the viewing requester's inboxes. |\n| <a id=\"property-responsestatus\"></a> `responseStatus` | [`AttendeeResponseStatus`](AttendeeResponseStatus.md) | RSVP state. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarEvent.md -->\n# Type Alias: CalendarEvent\n\n> **CalendarEvent** = \\{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarId?`: `string` \\| `null`; `conferenceProvider?`: `null` \\| [`ConferenceProvider`](ConferenceProvider.md); `conferenceUrl?`: `string` \\| `null`; `createdAt`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType?`: [`EventType`](EventType.md); `icalUid`: `string`; `id`: `string`; `isReadOnly`: `boolean`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `ownerId`: `string`; `recurrenceLines`: `string`[]; `reminders?`: [`EventReminders`](EventReminders.md); `sequence`: `number`; `sources?`: [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[]; `status`: [`EventStatus`](EventStatus.md); `time`: [`EventTime`](EventTime.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `updatedAt`: `string`; `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nA stable, first-class Macro calendar event entity.\n\nContent fields hold the canonical source's values: the account's primary\ncalendar copy when one is synced, else the freshest remaining copy.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees, keyed by email during persistence. |\n| <a id=\"property-calendarid\"></a> `calendarId?` | `string` \\| `null` | Calendar the canonical source belongs to, when known. Absent only in projections stored before calendars were attributed. |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `null` \\| [`ConferenceProvider`](ConferenceProvider.md) | - |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Direct join URL when known. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Entity creation time. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. Distinct from the organizer when someone writes onto a calendar they do not own. Omitted from stored projections when unknown so events ingested before this field still compare equal. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType?` | [`EventType`](EventType.md) | Provider event type. Skipped when it is the regular type so projections stored before event types were modeled still compare equal. |\n| <a id=\"property-icaluid\"></a> `icalUid` | `string` | RFC 5545 UID used to reconcile provider and email sources. |\n| <a id=\"property-id\"></a> `id` | `string` | Macro entity identifier. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the canonical source's calendar prohibits editing it. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer email. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer display name. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | Macro user who owns this event entity. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](EventReminders.md) | Per-user reminder configuration. Skipped when it is the provider default so projections stored before reminders were modeled still compare equal. |\n| <a id=\"property-sequence\"></a> `sequence` | `number` | Provider/iCalendar sequence number. |\n| <a id=\"property-sources\"></a> `sources?` | [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[] | Content of every active copy of this event, canonical first: the primary calendar's copy, then the freshest. A client picks the copy whose calendar it is showing and falls back to the first. Populated only on the read path, so stored projections omit it. |\n| <a id=\"property-status\"></a> `status` | [`EventStatus`](EventStatus.md) | Event status. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Entity update time. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarEventSourceContent.md -->\n# Type Alias: CalendarEventSourceContent\n\n> **CalendarEventSourceContent** = \\{ `calendarId`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType`: [`EventType`](EventType.md); `isReadOnly`: `boolean`; `location?`: `string` \\| `null`; `reminders`: [`EventReminders`](EventReminders.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nThe content one provider copy of an event carries.\n\nGoogle keeps these fields per calendar copy: a shared calendar's copy of a\nmember's event can have its own title, type, reminders, and access role.\nThe entity holds its canonical source's values. Every other copy's values\nare read from here so a client can show the copy that belongs to the\ncalendar being viewed.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendarid\"></a> `calendarId` | `string` | Calendar this copy lives on. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType` | [`EventType`](EventType.md) | Provider event type. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the calendar's access role prohibits editing this copy. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-reminders\"></a> `reminders` | [`EventReminders`](EventReminders.md) | Reminder configuration of this copy. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarInvitation.md -->\n# Type Alias: CalendarInvitation\n\n> **CalendarInvitation** = \\{ `attendees`: [`InvitationParticipant`](InvitationParticipant.md)[]; `comment?`: `string` \\| `null`; `conference_url?`: `string` \\| `null`; `description?`: `string` \\| `null`; `dtstamp?`: `string` \\| `null`; `end?`: `null` \\| [`InvitationDateTime`](InvitationDateTime.md); `id`: `string`; `last_modified?`: `string` \\| `null`; `location?`: `string` \\| `null`; `method`: [`InvitationMethod`](InvitationMethod.md); `organizer?`: `null` \\| [`InvitationParticipant`](InvitationParticipant.md); `recurrence_id?`: `null` \\| [`InvitationDateTime`](InvitationDateTime.md); `recurrence_id_raw?`: `string` \\| `null`; `sequence`: `number`; `start?`: `null` \\| [`InvitationDateTime`](InvitationDateTime.md); `status?`: `string` \\| `null`; `title?`: `string` \\| `null`; `uid`: `string`; \\}\n\nDisplay snapshot of one meaningful VEVENT, owned by the email domain.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`InvitationParticipant`](InvitationParticipant.md)[] | Historical attendee identities and participation metadata. |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Reply or counter-proposal comment. |\n| <a id=\"property-conference_url\"></a> `conference_url?` | `string` \\| `null` | Validated HTTP(S) conferencing URL; never fetched during rendering. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Plaintext description, retaining passwords and dial-in instructions. |\n| <a id=\"property-dtstamp\"></a> `dtstamp?` | `string` \\| `null` | Scheduling timestamp in its original spelling. |\n| <a id=\"property-end\"></a> `end?` | `null` \\| [`InvitationDateTime`](InvitationDateTime.md) | - |\n| <a id=\"property-id\"></a> `id` | `string` | Content-derived component identity, stable across repeated extraction. |\n| <a id=\"property-last_modified\"></a> `last_modified?` | `string` \\| `null` | Last modification timestamp in its original spelling. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Plaintext event location. |\n| <a id=\"property-method\"></a> `method` | [`InvitationMethod`](InvitationMethod.md) | Original scheduling method. |\n| <a id=\"property-organizer\"></a> `organizer?` | `null` \\| [`InvitationParticipant`](InvitationParticipant.md) | - |\n| <a id=\"property-recurrence_id\"></a> `recurrence_id?` | `null` \\| [`InvitationDateTime`](InvitationDateTime.md) | - |\n| <a id=\"property-recurrence_id_raw\"></a> `recurrence_id_raw?` | `string` \\| `null` | Original recurrence identifier spelling and parameters. |\n| <a id=\"property-sequence\"></a> `sequence` | `number` | Scheduling revision, distinct from delivery order. |\n| <a id=\"property-start\"></a> `start?` | `null` \\| [`InvitationDateTime`](InvitationDateTime.md) | - |\n| <a id=\"property-status\"></a> `status?` | `string` \\| `null` | Original event status. |\n| <a id=\"property-title\"></a> `title?` | `string` \\| `null` | Event summary. |\n| <a id=\"property-uid\"></a> `uid` | `string` | iCalendar UID; never a Google provider event ID. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarOccurrence.md -->\n# Type Alias: CalendarOccurrence\n\n> **CalendarOccurrence** = \\{ `eventId`: `string`; `isCancelled`: `boolean`; `occurrenceKey`: `string`; `recurrenceId?`: `string` \\| `null`; `time`: [`EventTime`](EventTime.md); \\}\n\nA materialized recurrence instance optimized for range queries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-eventid\"></a> `eventId` | `string` | Owning event entity. |\n| <a id=\"property-iscancelled\"></a> `isCancelled` | `boolean` | Whether the instance was cancelled. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey` | `string` | Stable key within the event. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` \\| `null` | Provider recurrence identifier, when applicable. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Instance time. |\n\n\n<!-- generated/email/types.gen/type-aliases/ConferenceProvider.md -->\n# Type Alias: ConferenceProvider\n\n> **ConferenceProvider** = `\"microsoft_teams\"` \\| `\"google_meet\"` \\| `\"other\"`\n\nThe conferencing system backing an event's join URL.\n\nCalendars can create Google Meet or Microsoft Teams according to their\ncapabilities. Imported third-party conferences are labeled separately.\nOmitting a conference change preserves the current conference; explicit\nchanges still require provider and calendar capability validation.\n\n\n<!-- generated/email/types.gen/type-aliases/ContactInfo.md -->\n# Type Alias: ContactInfo\n\n> **ContactInfo** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ContactInfoLegacy.md -->\n# Type Alias: ContactInfoLegacy\n\n> **ContactInfoLegacy** = \\{ `email`: `string`; `email_address`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` |\n| <a id=\"property-email_address\"></a> `email_address` | `string` |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md -->\n# Type Alias: ContactInfoWithInteraction\n\n> **ContactInfoWithInteraction** = [`ContactInfoLegacy`](ContactInfoLegacy.md) & \\{ `last_interaction`: `string`; \\}\n\n## Type Declaration\n\n| Name | Type |\n| ------ | ------ |\n| `last_interaction` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/EventReminderOverride.md -->\n# Type Alias: EventReminderOverride\n\n> **EventReminderOverride** = \\{ `method`: `string`; `minutes`: `number`; \\}\n\nOne reminder: how it alerts and how many minutes before the event start\n(before midnight in the calendar's zone for all-day events) it fires.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-method\"></a> `method` | `string` | Provider method, stored verbatim; only `popup` fires Macro notifications. |\n| <a id=\"property-minutes\"></a> `minutes` | `number` | Minutes before the event start. |\n\n\n<!-- generated/email/types.gen/type-aliases/EventReminders.md -->\n# Type Alias: EventReminders\n\n> **EventReminders** = \\{ `overrides?`: [`EventReminderOverride`](EventReminderOverride.md)[]; `useDefault`: `boolean`; \\}\n\nPer-user reminder configuration for an event, mirroring Google's model:\neither the calendar's default reminders apply, or the explicit overrides\nreplace them entirely.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-overrides\"></a> `overrides?` | [`EventReminderOverride`](EventReminderOverride.md)[] | Explicit reminders replacing the defaults when `use_default` is off. |\n| <a id=\"property-usedefault\"></a> `useDefault` | `boolean` | Whether the calendar's default reminders apply. |\n\n\n<!-- generated/email/types.gen/type-aliases/EventStatus.md -->\n# Type Alias: EventStatus\n\n> **EventStatus** = `\"confirmed\"` \\| `\"tentative\"` \\| `\"cancelled\"`\n\nCanonical event status.\n\n\n<!-- generated/email/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- generated/email/types.gen/type-aliases/EventTransparency.md -->\n# Type Alias: EventTransparency\n\n> **EventTransparency** = `\"opaque\"` \\| `\"transparent\"`\n\nWhether an event blocks availability.\n\n\n<!-- generated/email/types.gen/type-aliases/EventType.md -->\n# Type Alias: EventType\n\n> **EventType** = `\"default\"` \\| `\"out_of_office\"` \\| `\"focus_time\"` \\| `\"working_location\"` \\| `\"birthday\"` \\| `\"from_gmail\"`\n\nGoogle's event type: ordinary meetings versus the status-style entries\n(working location, out of office, focus time, birthdays) Google renders\nand notifies differently. Immutable at the provider after creation.\n\n\n<!-- generated/email/types.gen/type-aliases/EventVisibility.md -->\n# Type Alias: EventVisibility\n\n> **EventVisibility** = `\"default\"` \\| `\"public\"` \\| `\"private\"` \\| `\"confidential\"`\n\nVisibility of event details.\n\n\n<!-- generated/email/types.gen/type-aliases/GetAttachmentResponse.md -->\n# Type Alias: GetAttachmentResponse\n\n> **GetAttachmentResponse** = \\{ `attachment`: [`Attachment`](Attachment.md); \\}\n\nThe response returned from the get attachment endpoint\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachment\"></a> `attachment` | [`Attachment`](Attachment.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/GetAttachmentResponses.md -->\n# Type Alias: GetAttachmentResponses\n\n> **GetAttachmentResponses** = \\{ `200`: [`GetAttachmentResponse`](GetAttachmentResponse.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-200\"></a> `200` | [`GetAttachmentResponse`](GetAttachmentResponse.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/GetMessageResponses.md -->\n# Type Alias: GetMessageResponses\n\n> **GetMessageResponses** = \\{ `200`: [`ParsedMessage`](ParsedMessage.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-200\"></a> `200` | [`ParsedMessage`](ParsedMessage.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationDateTime.md -->\n# Type Alias: InvitationDateTime\n\n> **InvitationDateTime** = \\{ `kind`: `\"date\"`; `value`: `string`; \\} \\| \\{ `kind`: `\"zoned\"`; `time_zone`: `string`; `value`: `string`; \\} \\| \\{ `kind`: `\"unresolved\"`; `time_zone?`: `string` \\| `null`; `value`: `string`; \\}\n\nPreserve date-only and unresolved times without manufacturing UTC instants.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"date\"` | - |\n| `value` | `string` | ISO calendar date. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"zoned\"`; `time_zone`: `string`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"zoned\"` | - |\n| `time_zone` | `string` | IANA zone of the original TZID, or UTC. |\n| `value` | `string` | RFC3339 instant. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"unresolved\"`; `time_zone?`: `string` \\| `null`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"unresolved\"` | - |\n| `time_zone?` | `string` \\| `null` | Original TZID if present. |\n| `value` | `string` | ISO local wall time, without an offset. |\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationMethod.md -->\n# Type Alias: InvitationMethod\n\n> **InvitationMethod** = `\"request\"` \\| `\"reply\"` \\| `\"cancel\"` \\| `\"counter\"` \\| `\"publish\"` \\| `\"unknown\"`\n\nOriginal scheduling method, including methods unsupported for actions.\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationParticipant.md -->\n# Type Alias: InvitationParticipant\n\n> **InvitationParticipant** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `participation_status?`: `string` \\| `null`; \\}\n\nScheduling participant; saved responses are historical, not current RSVP.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Participant calendar address. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Sender-supplied display name. |\n| <a id=\"property-participation_status\"></a> `participation_status?` | `string` \\| `null` | Original PARTSTAT, retaining extensions. |\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationResolution.md -->\n# Type Alias: InvitationResolution\n\n> **InvitationResolution** = \\{ `kind`: `\"disconnected\"`; \\} \\| \\{ `kind`: `\"still_syncing\"`; \\} \\| \\{ `kind`: `\"cancelled\"`; \\} \\| \\{ `kind`: `\"unavailable\"`; \\} \\| \\{ `kind`: `\"no_match\"`; \\} \\| \\{ `kind`: `\"ambiguous\"`; \\} \\| \\{ `can_join`: `boolean`; `can_respond`: `boolean`; `event`: [`CalendarEvent`](CalendarEvent.md); `is_stale`: `boolean`; `kind`: `\"resolved\"`; `occurrence`: [`CalendarOccurrence`](CalendarOccurrence.md); `responding_email`: `string`; \\}\n\nRefreshable result, distinct from the immutable email contents.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"disconnected\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"still_syncing\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"cancelled\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"unavailable\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"no_match\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"ambiguous\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `can_join`: `boolean`; `can_respond`: `boolean`; `event`: [`CalendarEvent`](CalendarEvent.md); `is_stale`: `boolean`; `kind`: `\"resolved\"`; `occurrence`: [`CalendarOccurrence`](CalendarOccurrence.md); `responding_email`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `can_join` | `boolean` | Whether the conference link belongs to the reconciled scheduling target. |\n| `can_respond` | `boolean` | Whether a response is currently allowed. |\n| `event` | [`CalendarEvent`](CalendarEvent.md) | Current occurrence-specific content. |\n| `is_stale` | `boolean` | Whether the provider projection trails the email revision. |\n| `kind` | `\"resolved\"` | - |\n| `occurrence` | [`CalendarOccurrence`](CalendarOccurrence.md) | Original occurrence identity and current time. |\n| `responding_email` | `string` | Connected address that would respond. |\n\n\n<!-- generated/email/types.gen/type-aliases/LabelInfo.md -->\n# Type Alias: LabelInfo\n\n> **LabelInfo** = \\{ `name`: `string`; `provider_id`: `string`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-name\"></a> `name` | `string` |\n| <a id=\"property-provider_id\"></a> `provider_id` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/Link.md -->\n# Type Alias: Link\n\n> **Link** = \\{ `calendar_disabled`: `boolean`; `created_at`: `string`; `email_address`: `string`; `fusionauth_user_id`: `string`; `has_calendar_data`: `boolean`; `id`: `string`; `is_primary`: `boolean`; `is_sync_active`: `boolean`; `macro_id`: `string`; `needs_calendar_permission`: `boolean`; `needs_reauth`: `boolean`; `photo_url?`: `string` \\| `null`; `provider`: [`UserProvider`](UserProvider.md); `settings`: [`Settings`](Settings.md); `sync_status`: [`SyncStatus`](SyncStatus.md); `updated_at`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar_disabled\"></a> `calendar_disabled` | `boolean` | Whether the user turned calendar off for this inbox, which also removed its calendar data. `needs_calendar_permission` is true either way, so this is what separates \"never granted\" from \"deliberately off\" — unprompted calendar nags must stay quiet for the latter. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-email_address\"></a> `email_address` | `string` | - |\n| <a id=\"property-fusionauth_user_id\"></a> `fusionauth_user_id` | `string` | - |\n| <a id=\"property-has_calendar_data\"></a> `has_calendar_data` | `boolean` | Whether Macro holds calendar data for this inbox. Drives the turn-off control on its own, so removing that data never depends on the recorded scopes still matching the set Macro requests today — a set that changes as the integration narrows, stranding data behind a capability check that no longer recognizes an older grant. |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_primary\"></a> `is_primary` | `boolean` | - |\n| <a id=\"property-is_sync_active\"></a> `is_sync_active` | `boolean` | - |\n| <a id=\"property-macro_id\"></a> `macro_id` | `string` | - |\n| <a id=\"property-needs_calendar_permission\"></a> `needs_calendar_permission` | `boolean` | Whether the link's Google grant is missing the calendar scope. True for inboxes connected before the calendar capability existed (and for grants where the user declined it); drives the per-inbox calendar upgrade prompt. Re-running the connect flow records the new grant. |\n| <a id=\"property-needs_reauth\"></a> `needs_reauth` | `boolean` | Whether the link's Google grant needs to be reconnected. Drives the per-inbox reconnect prompt independently of the sync-status badge. |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` | The inbox's own profile photo (its self-contact's SFS photo), if synced. |\n| <a id=\"property-provider\"></a> `provider` | [`UserProvider`](UserProvider.md) | - |\n| <a id=\"property-settings\"></a> `settings` | [`Settings`](Settings.md) | - |\n| <a id=\"property-sync_status\"></a> `sync_status` | [`SyncStatus`](SyncStatus.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxAction.md -->\n# Type Alias: MailboxAction\n\n> **MailboxAction** = \\{ `kind`: `\"read\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"flagged\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"archived\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"trashed\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"junk\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"category\"`; `value`: \\{ `name`: `string`; `present`: `boolean`; \\}; \\}\n\nDesired organization state. Categories never stand in for folders or flags.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"read\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"read\"` | - |\n| `value` | `boolean` | Mark correspondence read or unread. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"flagged\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"flagged\"` | - |\n| `value` | `boolean` | Set the follow-up star. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"archived\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"archived\"` | - |\n| `value` | `boolean` | Archive inbox messages, or restore received correspondence to the inbox. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"trashed\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"trashed\"` | - |\n| `value` | `boolean` | Move to recoverable trash, or restore correspondence to Inbox (drafts to Drafts). |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"junk\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"junk\"` | - |\n| `value` | `boolean` | Move to junk, or restore to the inbox. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"category\"`; `value`: \\{ `name`: `string`; `present`: `boolean`; \\}; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"category\"` | - |\n| `value` | \\{ `name`: `string`; `present`: `boolean`; \\} | Add/remove a category while preserving other provider assignments. |\n| `value.name` | `string` | - |\n| `value.present` | `boolean` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxOperation.md -->\n# Type Alias: MailboxOperation\n\n> **MailboxOperation** = \\{ `action`: [`MailboxAction`](MailboxAction.md); `id`: `string`; `state`: [`MailboxOperationState`](MailboxOperationState.md); `updated_at`: `string`; \\}\n\nDurable outcome of an accepted organization action.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-action\"></a> `action` | [`MailboxAction`](MailboxAction.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-state\"></a> `state` | [`MailboxOperationState`](MailboxOperationState.md) |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxOperationState.md -->\n# Type Alias: MailboxOperationState\n\n> **MailboxOperationState** = `\"pending\"` \\| `\"applied\"` \\| `\"failed\"` \\| `\"cancelled\"`\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxSettingsChange.md -->\n# Type Alias: MailboxSettingsChange\n\n> **MailboxSettingsChange** = `\"create_label\"` \\| `\"delete_label\"` \\| `\"sender_block\"`\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxSettingsOperation.md -->\n# Type Alias: MailboxSettingsOperation\n\n> **MailboxSettingsOperation** = \\{ `enabled`: `boolean`; `id`: `string`; `kind`: [`MailboxSettingsChange`](MailboxSettingsChange.md); `needs_attention`: `boolean`; `resource`: `string`; \\}\n\nAn accepted inbox configuration change awaiting provider confirmation.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-enabled\"></a> `enabled` | `boolean` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-kind\"></a> `kind` | [`MailboxSettingsChange`](MailboxSettingsChange.md) |\n| <a id=\"property-needs_attention\"></a> `needs_attention` | `boolean` |\n| <a id=\"property-resource\"></a> `resource` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/MessageOperationResponse.md -->\n# Type Alias: MessageOperationResponse\n\n> **MessageOperationResponse** = \\{ `operation?`: `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md); \\}\n\nAuthorized polling response. Gmail has no asynchronous draft operation.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-operation\"></a> `operation?` | `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ParsedMessage.md -->\n# Type Alias: ParsedMessage\n\n> **ParsedMessage** = \\{ `bcc`: [`ContactInfo`](ContactInfo.md)[]; `body_parsed?`: `string` \\| `null`; `cc`: [`ContactInfo`](ContactInfo.md)[]; `db_id`: `string`; `from?`: `null` \\| [`ContactInfo`](ContactInfo.md); `internal_date_ts?`: `string` \\| `null`; `labels`: [`LabelInfo`](LabelInfo.md)[]; `link_id`: `string`; `subject?`: `string` \\| `null`; `thread_db_id`: `string`; `to`: [`ContactInfo`](ContactInfo.md)[]; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc` | [`ContactInfo`](ContactInfo.md)[] |\n| <a id=\"property-body_parsed\"></a> `body_parsed?` | `string` \\| `null` |\n| <a id=\"property-cc\"></a> `cc` | [`ContactInfo`](ContactInfo.md)[] |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-from\"></a> `from?` | `null` \\| [`ContactInfo`](ContactInfo.md) |\n| <a id=\"property-internal_date_ts\"></a> `internal_date_ts?` | `string` \\| `null` |\n| <a id=\"property-labels\"></a> `labels` | [`LabelInfo`](LabelInfo.md)[] |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-subject\"></a> `subject?` | `string` \\| `null` |\n| <a id=\"property-thread_db_id\"></a> `thread_db_id` | `string` |\n| <a id=\"property-to\"></a> `to` | [`ContactInfo`](ContactInfo.md)[] |\n\n\n<!-- generated/email/types.gen/type-aliases/ResolveMessageOperationRequest.md -->\n# Type Alias: ResolveMessageOperationRequest\n\n> **ResolveMessageOperationRequest** = \\{ `accept_duplicate_risk?`: `boolean`; `action`: [`ApiMessageResolutionAction`](ApiMessageResolutionAction.md); `remote_version?`: `string` \\| `null`; `revision`: `string`; \\}\n\nStale versions fail without altering the current operation.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-accept_duplicate_risk\"></a> `accept_duplicate_risk?` | `boolean` |\n| <a id=\"property-action\"></a> `action` | [`ApiMessageResolutionAction`](ApiMessageResolutionAction.md) |\n| <a id=\"property-remote_version\"></a> `remote_version?` | `string` \\| `null` |\n| <a id=\"property-revision\"></a> `revision` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/Settings.md -->\n# Type Alias: Settings\n\n> **Settings** = \\{ `signature?`: `string` \\| `null`; `signature_on_replies_forwards?`: `boolean` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-signature\"></a> `signature?` | `string` \\| `null` | The user's email signature content (HTML). On a patch, omit or send `null` to leave unchanged (both deserialize to `None`); pass an empty string to clear it. The column cannot be set to SQL NULL via patch. |\n| <a id=\"property-signature_on_replies_forwards\"></a> `signature_on_replies_forwards?` | `boolean` \\| `null` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/SyncStatus.md -->\n# Type Alias: SyncStatus\n\n> **SyncStatus** = `\"SYNCING\"` \\| `\"UP_TO_DATE\"` \\| `\"ERROR\"` \\| `\"NEEDS_REAUTH\"` \\| `\"INACTIVE\"`\n\nCoarse sync state for an inbox, used to render a one-line hint in the\nmulti-inbox settings list. Derived from the link's `is_sync_active` flag, its\nreauth health, and its most recent backfill job.\n\n\n<!-- generated/email/types.gen/type-aliases/ThreadStateField.md -->\n# Type Alias: ThreadStateField\n\n> **ThreadStateField** = `\"read\"` \\| `\"starred\"` \\| `\"trashed\"` \\| `\"junk\"`\n\nSemantic mailbox facts, independent of folder/category names.\n\n\n<!-- generated/email/types.gen/type-aliases/TransferDraftRequest.md -->\n# Type Alias: TransferDraftRequest\n\n> **TransferDraftRequest** = \\{ `destination_link_id`: `string`; `operation_id`: `string`; \\}\n\nReuse the same operation ID when retrying after a lost response.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-destination_link_id\"></a> `destination_link_id` | `string` |\n| <a id=\"property-operation_id\"></a> `operation_id` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/TransferDraftResponse.md -->\n# Type Alias: TransferDraftResponse\n\n> **TransferDraftResponse** = \\{ `attachments`: [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[]; `message_id`: `string`; `source_id`: `string`; `source_thread_id`: `string`; `thread_id`: `string`; \\}\n\nA new identity prevents delayed writes from mutating the moved copy.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[] |\n| <a id=\"property-message_id\"></a> `message_id` | `string` |\n| <a id=\"property-source_id\"></a> `source_id` | `string` |\n| <a id=\"property-source_thread_id\"></a> `source_thread_id` | `string` |\n| <a id=\"property-thread_id\"></a> `thread_id` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/TransferRecoveryResponse.md -->\n# Type Alias: TransferRecoveryResponse\n\n> **TransferRecoveryResponse** = \\{ `committed?`: `null` \\| [`TransferDraftResponse`](TransferDraftResponse.md); \\}\n\nA null result confirms that the move cannot commit, even if its request was delayed.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-committed\"></a> `committed?` | `null` \\| [`TransferDraftResponse`](TransferDraftResponse.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/UpdateThreadStateRequest.md -->\n# Type Alias: UpdateThreadStateRequest\n\n> **UpdateThreadStateRequest** = \\{ `field`: [`ThreadStateField`](ThreadStateField.md); `value`: `boolean`; \\}\n\nDesired state for every applicable message in an authorized thread.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-field\"></a> `field` | [`ThreadStateField`](ThreadStateField.md) |\n| <a id=\"property-value\"></a> `value` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/UserProvider.md -->\n# Type Alias: UserProvider\n\n> **UserProvider** = `\"GMAIL\"` \\| `\"OUTLOOK\"`\n\n\n<!-- generated/email/types.gen/type-aliases/Value.md -->\n# Type Alias: Value\n\n> **Value** = `unknown`\n\n\n<!-- generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailFollowup.md -->\n# Type Alias: EmailFollowup\n\n> **EmailFollowup** = \\{ `condition`: [`EmailReminderCondition`](EmailReminderCondition.md); `linkId`: `string`; `remindAt`: `string`; `reminderId`: `string`; `revision`: `string`; `state`: [`FollowupState`](FollowupState.md); `threadId`: `string`; \\}\n\nPublic status shown on email and in the Reminders editor.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-condition\"></a> `condition` | [`EmailReminderCondition`](EmailReminderCondition.md) | Condition, defaulting to no reply for new follow-ups. |\n| <a id=\"property-linkid\"></a> `linkId` | `string` | Canonical owned/delegated inbox. |\n| <a id=\"property-remindat\"></a> `remindAt` | `string` | Confirmed schedule. |\n| <a id=\"property-reminderid\"></a> `reminderId` | `string` | Identity of the snooze and its delivery records. |\n| <a id=\"property-revision\"></a> `revision` | `string` | Last accepted operation; edits/removal compare this to prevent stale undo. |\n| <a id=\"property-state\"></a> `state` | [`FollowupState`](FollowupState.md) | Durable lifecycle progress. |\n| <a id=\"property-threadid\"></a> `threadId` | `string` | Conversation identity. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailFollowupCommand.md -->\n# Type Alias: EmailFollowupCommand\n\n> **EmailFollowupCommand** = \\{ `condition`: [`EmailReminderCondition`](EmailReminderCondition.md); `expectedRevision?`: `string` \\| `null`; `operationId`: `string`; `remindAt`: `string`; `type`: `\"set\"`; \\} \\| \\{ `expectedRevision`: `string`; `operationId`: `string`; `type`: `\"remove\"`; `undo?`: `boolean`; \\}\n\nIdempotent email command. Reusing an operation ID with different data fails.\n\n## Union Members\n\n### Type Literal\n\n\\{ `condition`: [`EmailReminderCondition`](EmailReminderCondition.md); `expectedRevision?`: `string` \\| `null`; `operationId`: `string`; `remindAt`: `string`; `type`: `\"set\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `condition` | [`EmailReminderCondition`](EmailReminderCondition.md) | Reply condition. |\n| `expectedRevision?` | `string` \\| `null` | None for creation, the current revision for edits. |\n| `operationId` | `string` | Unique request identity retained across network retries. |\n| `remindAt` | `string` | One future instant; conditional recurrence is deliberately absent. |\n| `type` | `\"set\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `expectedRevision`: `string`; `operationId`: `string`; `type`: `\"remove\"`; `undo?`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `expectedRevision` | `string` | Reject removal if a newer edit has replaced this operation. |\n| `operationId` | `string` | Unique request identity. |\n| `type` | `\"remove\"` | - |\n| `undo?` | `boolean` | Undo restores original visibility; ordinary Remove returns to inbox. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailFollowupResponse.md -->\n# Type Alias: EmailFollowupResponse\n\n> **EmailFollowupResponse** = \\{ `followup?`: `null` \\| [`EmailFollowup`](EmailFollowup.md); \\}\n\nLookup response, including an email with no follow-up yet.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-followup\"></a> `followup?` | `null` \\| [`EmailFollowup`](EmailFollowup.md) |\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailReminderCondition.md -->\n# Type Alias: EmailReminderCondition\n\n> **EmailReminderCondition** = `\"if_no_reply\"` \\| `\"regardless\"`\n\nWhen an email follow-up should return the conversation.\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/FollowupState.md -->\n# Type Alias: FollowupState\n\n> **FollowupState** = `\"archiving\"` \\| `\"pending\"` \\| `\"returning\"` \\| `\"returned\"` \\| `\"cancelled\"` \\| `\"removed\"`\n\nDurable progress of an email operation.\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- src/entities/email/attachment/classes/EmailAttachment.md -->\n# Class: EmailAttachment\n\nA file attached to an email message. A thin handle keyed by attachment id;\nthe record loads lazily on first field access.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`EmailAttachmentData`](../type-aliases/EmailAttachmentData.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-contentid\"></a> `contentId` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's Content-ID header value (for inline attachments). | - |\n| <a id=\"property-dataurl\"></a> `dataUrl` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | A URL to the attachment's raw data, when available. | - |\n| <a id=\"property-filename\"></a> `filename` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's original filename. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-mimetype\"></a> `mimeType` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's MIME type. | - |\n| <a id=\"property-sfsid\"></a> `sfsId` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's static-file-service id, when it has been stored there. | - |\n| <a id=\"property-size\"></a> `size` | `readonly` | () => `Promise`\\<`number` \\| `undefined`\\> | The attachment's size in bytes. | - |\n\n## Methods\n\n### toDocument()\n\n> **toDocument**(): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nThe Macro document holding this attachment's content. Get-or-create: the\nserver returns the existing document's id, or downloads the attachment\nfrom the provider and uploads it as a new document first (deduplicated\nbehind a server-side lock).\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailAttachment`\n\nA handle to an attachment by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailAttachment`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `data`): `EmailAttachment`\n\nBuild an attachment from an already-fetched record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `data` | [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md) |\n\n#### Returns\n\n`EmailAttachment`\n\n\n<!-- src/entities/email/attachment/type-aliases/EmailAttachmentData.md -->\n# Type Alias: EmailAttachmentData\n\n> **EmailAttachmentData** = [`GetAttachmentResponses`](../../../../../generated/email/types.gen/type-aliases/GetAttachmentResponses.md)\\[`200`\\]\\[`\"attachment\"`\\]\n\nThe API's representation of an email attachment (`Attachment`).\n\n\n<!-- src/entities/email/draft/classes/DraftAttachment.md -->\n# Class: DraftAttachment\n\nAn uploaded or forwarded attachment belonging to a draft.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-draft\"></a> `draft` | `readonly` | [`EmailDraft`](EmailDraft.md) | Parent draft. |\n| <a id=\"property-forwarded\"></a> `forwarded` | `readonly` | `boolean` | Whether this attachment was forwarded. |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | Attachment identity. |\n\n## Methods\n\n### complete()\n\n> **complete**(): `Promise`\\<`void`\\>\n\nComplete verification after uploading the file.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### remove()\n\n> **remove**(): `Promise`\\<`void`\\>\n\nRemove this attachment from its draft.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `draftId`: `string`; `forwarded`: `boolean`; `id`: `string`; \\}\n\nSerialize identity without credentials.\n\n#### Returns\n\n\\{ `draftId`: `string`; `forwarded`: `boolean`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `draftId` | `string` |\n| `forwarded` | `boolean` |\n| `id` | `string` |\n\n***\n\n### byId()\n\n> `static` **byId**(`_client`, `draft`, `id`, `forwarded?`): `DraftAttachment`\n\nConstruct a draft scoped attachment handle.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `_client` | `MacroClient` | `undefined` |\n| `draft` | [`EmailDraft`](EmailDraft.md) | `undefined` |\n| `id` | `string` | `undefined` |\n| `forwarded?` | `boolean` | `false` |\n\n#### Returns\n\n`DraftAttachment`\n\n\n<!-- src/entities/email/draft/classes/EmailDraft.md -->\n# Class: EmailDraft\n\nA draft email. Sending remains an explicit separate operation.\n\n## Extends\n\n- [`EmailMessage`](../../message/classes/EmailMessage.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Bcc recipients. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`bcc`](../../message/classes/EmailMessage.md#property-bcc) |\n| <a id=\"property-body\"></a> `body` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The parsed message body, as the API returns it. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`body`](../../message/classes/EmailMessage.md#property-body) |\n| <a id=\"property-cc\"></a> `cc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Cc recipients. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`cc`](../../message/classes/EmailMessage.md#property-cc) |\n| <a id=\"property-from\"></a> `from` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md) \\| `undefined`\\> | The sender. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`from`](../../message/classes/EmailMessage.md#property-from) |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`EmailMessage`](../../message/classes/EmailMessage.md).[`id`](../../message/classes/EmailMessage.md#property-id) |\n| <a id=\"property-labels\"></a> `labels` | `readonly` | () => `Promise`\\<[`LabelInfo`](../../../../../generated/email/types.gen/type-aliases/LabelInfo.md)[]\\> | Labels on this message. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`labels`](../../message/classes/EmailMessage.md#property-labels) |\n| <a id=\"property-link\"></a> `link` | `readonly` | () => `Promise`\\<[`Link`](../../link/classes/Link.md)\\> | The inbox (email link) this message belongs to. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`link`](../../message/classes/EmailMessage.md#property-link) |\n| <a id=\"property-sentat\"></a> `sentAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The provider-internal date of the message. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`sentAt`](../../message/classes/EmailMessage.md#property-sentat) |\n| <a id=\"property-subject\"></a> `subject` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The message's subject line. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`subject`](../../message/classes/EmailMessage.md#property-subject) |\n| <a id=\"property-to\"></a> `to` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The To recipients. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`to`](../../message/classes/EmailMessage.md#property-to) |\n\n## Methods\n\n### addAttachment()\n\n> **addAttachment**(`options`): `Promise`\\<\\{ `attachment`: [`DraftAttachment`](DraftAttachment.md); `contentType`: `string`; `uploadUrl`: `string`; \\}\\>\n\nReserve an attachment upload. Upload to the returned URL, then call complete().\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `fileName`: `string`; `sha`: `string`; `size`: `number`; `uploadId?`: `string`; \\} |\n| `options.fileName` | `string` |\n| `options.sha` | `string` |\n| `options.size` | `number` |\n| `options.uploadId?` | `string` |\n\n#### Returns\n\n`Promise`\\<\\{ `attachment`: [`DraftAttachment`](DraftAttachment.md); `contentType`: `string`; `uploadUrl`: `string`; \\}\\>\n\n***\n\n### addLabel()\n\n> **addLabel**(`label`): `Promise`\\<`void`\\>\n\nAdd a label to this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`addLabel`](../../message/classes/EmailMessage.md#addlabel)\n\n***\n\n### completeDraftAttachment()\n\n> **completeDraftAttachment**(`attachmentId`): `Promise`\\<`void`\\>\n\nVerify an uploaded draft attachment before it can be sent.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachmentId` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`completeDraftAttachment`](../../message/classes/EmailMessage.md#completedraftattachment)\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete the draft.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### forwardAttachment()\n\n> **forwardAttachment**(`attachment`): `Promise`\\<[`DraftAttachment`](DraftAttachment.md)\\>\n\nForward an existing attachment into this draft.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachment` | [`EmailAttachment`](../../attachment/classes/EmailAttachment.md) |\n\n#### Returns\n\n`Promise`\\<[`DraftAttachment`](DraftAttachment.md)\\>\n\n***\n\n### operationStatus()\n\n> **operationStatus**(): `Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\nRead the draft's durable send, upload, or conflict status without retrying it.\n\n#### Returns\n\n`Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`operationStatus`](../../message/classes/EmailMessage.md#operationstatus)\n\n***\n\n### removeAttachment()\n\n> **removeAttachment**(`attachment`): `Promise`\\<`void`\\>\n\nRemove a draft attachment.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachment` | [`DraftAttachment`](DraftAttachment.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### removeLabel()\n\n> **removeLabel**(`label`): `Promise`\\<`void`\\>\n\nRemove a label from this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`removeLabel`](../../message/classes/EmailMessage.md#removelabel)\n\n***\n\n### resolveOperation()\n\n> **resolveOperation**(`request`): `Promise`\\<`void`\\>\n\nResolve the displayed operation revision after the user chooses an action.\nRetrying an uncertain send requires explicit duplicate-risk acceptance.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`ResolveMessageOperationRequest`](../../../../../generated/email/types.gen/type-aliases/ResolveMessageOperationRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`resolveOperation`](../../message/classes/EmailMessage.md#resolveoperation)\n\n***\n\n### schedule()\n\n> **schedule**(`sendTime`, `options?`): `Promise`\\<`void`\\>\n\nSchedule this draft for sending.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `sendTime` | `string` |\n| `options?` | \\{ `includeSignature?`: `boolean`; \\} |\n| `options.includeSignature?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### thread()\n\n> **thread**(): `Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe thread this message belongs to.\n\n#### Returns\n\n`Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`thread`](../../message/classes/EmailMessage.md#thread)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`toJSON`](../../message/classes/EmailMessage.md#tojson)\n\n***\n\n### transferDraft()\n\n> **transferDraft**(`request`): `Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\nMove a draft to another inbox using a caller-persisted operation UUID.\nContinue editing the returned message_id; the original identity is retired.\nOn an interrupted response, use email.recoverDraftTransfer(operation_id).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`TransferDraftRequest`](../../../../../generated/email/types.gen/type-aliases/TransferDraftRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`transferDraft`](../../message/classes/EmailMessage.md#transferdraft)\n\n***\n\n### unschedule()\n\n> **unschedule**(): `Promise`\\<`void`\\>\n\nRemove a scheduled send.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`void`\\>\n\nReplace draft content without changing its identity or sending it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../type-aliases/DraftOptions.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### verifyAttachment()\n\n> **verifyAttachment**(`attachment`): `Promise`\\<`void`\\>\n\nComplete verification of an uploaded attachment.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachment` | [`DraftAttachment`](DraftAttachment.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailDraft`\n\nConstruct a lazy draft handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailDraft`\n\n#### Overrides\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`byId`](../../message/classes/EmailMessage.md#byid)\n\n***\n\n### from()\n\n> `static` **from**(`client`, `data`): [`EmailMessage`](../../message/classes/EmailMessage.md)\n\nBuild a message from an already-fetched record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `data` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n\n#### Returns\n\n[`EmailMessage`](../../message/classes/EmailMessage.md)\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`from`](../../message/classes/EmailMessage.md#from)\n\n***\n\n### send()\n\n> `static` **send**(`client`, `opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a new email message. Returns a handle when the API reports the created message's id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | [`SendEmailOptions`](../../message/interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`send`](../../message/classes/EmailMessage.md#send)\n\n\n<!-- src/entities/email/draft/functions/draftBody.md -->\n# Function: draftBody()\n\n> **draftBody**(`options`): [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\n\nTranslate draft content to the generated contract.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../type-aliases/DraftOptions.md) |\n\n## Returns\n\n[`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\n\n\n<!-- src/entities/email/draft/type-aliases/DraftOptions.md -->\n# Type Alias: DraftOptions\n\n> **DraftOptions** = `Omit`\\<[`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md), `\"db_id\"` \\| `\"provider_id\"` \\| `\"provider_thread_id\"` \\| `\"replying_to_id\"` \\| `\"thread_db_id\"` \\| `\"body_text\"` \\| `\"body_html\"` \\| `\"body_macro\"` \\| `\"headers_json\"` \\| `\"include_signature\"`\\> & \\{ `bodyHtml?`: `string`; `bodyMacro?`: `string`; `bodyText?`: `string`; `headers?`: [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\\[`\"headers_json\"`\\]; `includeSignature?`: `boolean`; `replyingTo?`: [`EmailMessage`](../../message/classes/EmailMessage.md); `thread?`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}\n\nDraft content; relationships use message and thread handles.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `bodyHtml?` | `string` | HTML body. |\n| `bodyMacro?` | `string` | Macro body. |\n| `bodyText?` | `string` | Plain text body. |\n| `headers?` | [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\\[`\"headers_json\"`\\] | Extra headers. |\n| `includeSignature?` | `boolean` | Include the inbox signature. |\n| `replyingTo?` | [`EmailMessage`](../../message/classes/EmailMessage.md) | Message being replied to. |\n| `thread?` | [`EmailThread`](../../thread/classes/EmailThread.md) | Thread receiving this draft. |\n\n\n<!-- src/entities/email/filter/classes/EmailFilter.md -->\n# Class: EmailFilter\n\nAn importance filter matched by sender address or domain.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Matched address. | - |\n| <a id=\"property-emaildomain\"></a> `emailDomain` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Matched domain. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isimportant\"></a> `isImportant` | `readonly` | () => `Promise`\\<`boolean`\\> | Importance assigned by this filter. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this filter.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### setImportant()\n\n> **setImportant**(`isImportant`): `Promise`\\<`void`\\>\n\nChange the importance for the same sender selector.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `isImportant` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`, `inbox?`): `EmailFilter`\n\nConstruct a lazy filter handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`EmailFilter`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `record`, `inbox?`): `EmailFilter`\n\nSeed from a server record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `record` | [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`EmailFilter`\n\n\n<!-- src/entities/email/filter/interfaces/EmailFilterOptions.md -->\n# Interface: EmailFilterOptions\n\nSender importance rule.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress?` | `string` | Match an address. |\n| <a id=\"property-emaildomain\"></a> `emailDomain?` | `string` | Match a domain. |\n| <a id=\"property-isimportant\"></a> `isImportant` | `boolean` | Whether matches are important. |\n\n\n<!-- src/entities/email/label/classes/Label.md -->\n# Class: Label\n\nAn email label. A free-to-construct handle: there is no single-label GET,\nso the detail record loads lazily on first field access by listing all\nlabels and finding this one (mirroring Link).\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the label was created. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-labellistvisibility\"></a> `labelListVisibility` | `readonly` | () => `Promise`\\<[`ApiLabelListVisibility`](../../../../../generated/email/types.gen/type-aliases/ApiLabelListVisibility.md)\\> | Whether the label is shown in the label list. | - |\n| <a id=\"property-linkid\"></a> `linkId` | `readonly` | () => `Promise`\\<`string`\\> | The inbox (email link) this label belongs to. | - |\n| <a id=\"property-messagelistvisibility\"></a> `messageListVisibility` | `readonly` | () => `Promise`\\<[`ApiMessageListVisibility`](../../../../../generated/email/types.gen/type-aliases/ApiMessageListVisibility.md)\\> | Whether the label is shown in the message list. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | The label's display name. | - |\n| <a id=\"property-type\"></a> `type` | `readonly` | () => `Promise`\\<[`ApiLabelType`](../../../../../generated/email/types.gen/type-aliases/ApiLabelType.md)\\> | Whether this is a system label or a user-created one. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this label.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Label`\n\nA handle to a label by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Label`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `name`): `Promise`\\<`Label`\\>\n\nCreate a user label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`Label`\\>\n\n***\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`Label`[]\\>\n\nAll labels across the user's inboxes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Label`[]\\>\n\n\n<!-- src/entities/email/link/classes/Link.md -->\n# Class: Link\n\nAn email link: a connected inbox (e.g. Gmail or Outlook) that threads and\nmessages sync through. A free-to-construct handle, resolved from the\ncaller's connected links.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `readonly` | () => `Promise`\\<`string`\\> | The inbox's email address. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isprimary\"></a> `isPrimary` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether this is the user's primary inbox. | - |\n| <a id=\"property-issyncactive\"></a> `isSyncActive` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether syncing is currently active for this inbox. | - |\n| <a id=\"property-needsreauth\"></a> `needsReauth` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the inbox needs to be re-authenticated. | - |\n| <a id=\"property-photourl\"></a> `photoUrl` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The inbox's avatar URL, if any. | - |\n| <a id=\"property-provider\"></a> `provider` | `readonly` | () => `Promise`\\<[`UserProvider`](../../../../../generated/email/types.gen/type-aliases/UserProvider.md)\\> | The email provider (e.g. `GMAIL` or `OUTLOOK`). | - |\n| <a id=\"property-syncstatus\"></a> `syncStatus` | `readonly` | () => `Promise`\\<[`SyncStatus`](../../../../../generated/email/types.gen/type-aliases/SyncStatus.md)\\> | The inbox's sync status. | - |\n\n## Methods\n\n### settingsOperations()\n\n> **settingsOperations**(): `Promise`\\<[`MailboxSettingsOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxSettingsOperation.md)[]\\>\n\nRead category and sender-policy changes for this inbox.\n\n#### Returns\n\n`Promise`\\<[`MailboxSettingsOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxSettingsOperation.md)[]\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Link`\n\nA handle to an email link by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Link`\n\n***\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`Link`[]\\>\n\nThe caller's connected email links.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Link`[]\\>\n\n\n<!-- src/entities/email/message/classes/EmailMessage.md -->\n# Class: EmailMessage\n\nA message in an email thread. A thin handle keyed by message id; the\nrecord loads lazily on first field access.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`EmailMessageData`](../type-aliases/EmailMessageData.md)\\>\n\n## Extended by\n\n- [`EmailDraft`](../../draft/classes/EmailDraft.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Bcc recipients. | - |\n| <a id=\"property-body\"></a> `body` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The parsed message body, as the API returns it. | - |\n| <a id=\"property-cc\"></a> `cc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Cc recipients. | - |\n| <a id=\"property-from\"></a> `from` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md) \\| `undefined`\\> | The sender. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-labels\"></a> `labels` | `readonly` | () => `Promise`\\<[`LabelInfo`](../../../../../generated/email/types.gen/type-aliases/LabelInfo.md)[]\\> | Labels on this message. | - |\n| <a id=\"property-link\"></a> `link` | `readonly` | () => `Promise`\\<[`Link`](../../link/classes/Link.md)\\> | The inbox (email link) this message belongs to. | - |\n| <a id=\"property-sentat\"></a> `sentAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The provider-internal date of the message. | - |\n| <a id=\"property-subject\"></a> `subject` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The message's subject line. | - |\n| <a id=\"property-to\"></a> `to` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The To recipients. | - |\n\n## Methods\n\n### addLabel()\n\n> **addLabel**(`label`): `Promise`\\<`void`\\>\n\nAdd a label to this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### completeDraftAttachment()\n\n> **completeDraftAttachment**(`attachmentId`): `Promise`\\<`void`\\>\n\nVerify an uploaded draft attachment before it can be sent.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachmentId` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### operationStatus()\n\n> **operationStatus**(): `Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\nRead the draft's durable send, upload, or conflict status without retrying it.\n\n#### Returns\n\n`Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\n***\n\n### removeLabel()\n\n> **removeLabel**(`label`): `Promise`\\<`void`\\>\n\nRemove a label from this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### resolveOperation()\n\n> **resolveOperation**(`request`): `Promise`\\<`void`\\>\n\nResolve the displayed operation revision after the user chooses an action.\nRetrying an uncertain send requires explicit duplicate-risk acceptance.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`ResolveMessageOperationRequest`](../../../../../generated/email/types.gen/type-aliases/ResolveMessageOperationRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### thread()\n\n> **thread**(): `Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe thread this message belongs to.\n\n#### Returns\n\n`Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### transferDraft()\n\n> **transferDraft**(`request`): `Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\nMove a draft to another inbox using a caller-persisted operation UUID.\nContinue editing the returned message_id; the original identity is retired.\nOn an interrupted response, use email.recoverDraftTransfer(operation_id).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`TransferDraftRequest`](../../../../../generated/email/types.gen/type-aliases/TransferDraftRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailMessage`\n\nA handle to a message by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailMessage`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `data`): `EmailMessage`\n\nBuild a message from an already-fetched record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `data` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n\n#### Returns\n\n`EmailMessage`\n\n***\n\n### send()\n\n> `static` **send**(`client`, `opts`): `Promise`\\<`EmailMessage` \\| `undefined`\\>\n\nSend a new email message. Returns a handle when the API reports the created message's id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | [`SendEmailOptions`](../interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<`EmailMessage` \\| `undefined`\\>\n\n\n<!-- src/entities/email/message/interfaces/SendEmailOptions.md -->\n# Interface: SendEmailOptions\n\nOptions for sending a fresh email message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Bcc recipients. |\n| <a id=\"property-bodytext\"></a> `bodyText` | `string` | Plain-text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Cc recipients. |\n| <a id=\"property-subject\"></a> `subject` | `string` | Subject line. |\n| <a id=\"property-to\"></a> `to` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Recipients. |\n\n\n<!-- src/entities/email/message/type-aliases/EmailMessageData.md -->\n# Type Alias: EmailMessageData\n\n> **EmailMessageData** = [`GetMessageResponses`](../../../../../generated/email/types.gen/type-aliases/GetMessageResponses.md)\\[`200`\\]\n\nThe API's representation of an email message (`ParsedMessage`).\n\n\n<!-- src/entities/email/namespace/classes/EmailNamespace.md -->\n# Class: EmailNamespace\n\n## Constructors\n\n### Constructor\n\n> **new EmailNamespace**(`client`): `EmailNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`EmailNamespace`\n\n## Methods\n\n### attachment()\n\n> **attachment**(`id`): [`EmailAttachment`](../../attachment/classes/EmailAttachment.md)\n\nA handle to an email attachment by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)\n\n***\n\n### blockedSenders()\n\n> **blockedSenders**(): `Promise`\\<`string`[]\\>\n\nThe email addresses currently blocked.\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### blockSender()\n\n> **blockSender**(`email`): `Promise`\\<`void`\\>\n\nBlock an email sender.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `email` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> **byId**(`id`): [`EmailThread`](../../thread/classes/EmailThread.md)\n\nA handle to an email thread by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailThread`](../../thread/classes/EmailThread.md)\n\n***\n\n### connectionProviders()\n\n> **connectionProviders**(): `Promise`\\<[`EmailConnectionProviders`](../../../../../generated/auth/types.gen/type-aliases/EmailConnectionProviders.md)\\>\n\nProviders the server currently permits this caller to connect.\n\n#### Returns\n\n`Promise`\\<[`EmailConnectionProviders`](../../../../../generated/auth/types.gen/type-aliases/EmailConnectionProviders.md)\\>\n\n***\n\n### contacts()\n\n> **contacts**(): `Promise`\\<\\{\\[`key`: `string`\\]: [`ContactInfoWithInteraction`](../../../../../generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md)[]; \\}\\>\n\nAddress book contacts grouped by the service's interaction buckets.\n\n#### Returns\n\n`Promise`\\<\\{\\[`key`: `string`\\]: [`ContactInfoWithInteraction`](../../../../../generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md)[]; \\}\\>\n\n***\n\n### createDraft()\n\n> **createDraft**(`options`, `inbox?`): `Promise`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\nCreate a draft without sending it; the inbox defaults to the caller's primary.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../../draft/type-aliases/DraftOptions.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\n***\n\n### createLabel()\n\n> **createLabel**(`name`): `Promise`\\<[`Label`](../../label/classes/Label.md)\\>\n\nCreate a user label. Returns the created label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Label`](../../label/classes/Label.md)\\>\n\n***\n\n### deleteLabel()\n\n> **deleteLabel**(`label`): `Promise`\\<`void`\\>\n\nDelete a label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### draftById()\n\n> **draftById**(`id`): [`EmailDraft`](../../draft/classes/EmailDraft.md)\n\nConstruct a lazy draft handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailDraft`](../../draft/classes/EmailDraft.md)\n\n***\n\n### filters()\n\n> **filters**(`inbox?`): `Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)[]\\>\n\nImportance filters.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)[]\\>\n\n***\n\n### inbox()\n\n> **inbox**(`opts?`): `AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe threads in the inbox, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`InboxOptions`](../interfaces/InboxOptions.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### label()\n\n> **label**(`id`): [`Label`](../../label/classes/Label.md)\n\nA handle to a label by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Label`](../../label/classes/Label.md)\n\n***\n\n### labels()\n\n> **labels**(): `Promise`\\<[`Label`](../../label/classes/Label.md)[]\\>\n\nAll labels across the user's inboxes.\n\n#### Returns\n\n`Promise`\\<[`Label`](../../label/classes/Label.md)[]\\>\n\n***\n\n### link()\n\n> **link**(`id`): [`Link`](../../link/classes/Link.md)\n\nA handle to a connected inbox (email link) by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Link`](../../link/classes/Link.md)\n\n***\n\n### links()\n\n> **links**(): `Promise`\\<[`Link`](../../link/classes/Link.md)[]\\>\n\nThe caller's connected inboxes (email links).\n\n#### Returns\n\n`Promise`\\<[`Link`](../../link/classes/Link.md)[]\\>\n\n***\n\n### message()\n\n> **message**(`id`): [`EmailMessage`](../../message/classes/EmailMessage.md)\n\nA handle to an email message by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailMessage`](../../message/classes/EmailMessage.md)\n\n***\n\n### recoverDraftTransfer()\n\n> **recoverDraftTransfer**(`operationId`): `Promise`\\<[`TransferRecoveryResponse`](../../../../../generated/email/types.gen/type-aliases/TransferRecoveryResponse.md)\\>\n\nRecover a draft move using its original operation UUID; never starts a new move.\nAn empty committed result fences the old move so it cannot commit later.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `operationId` | `string` |\n\n#### Returns\n\n`Promise`\\<[`TransferRecoveryResponse`](../../../../../generated/email/types.gen/type-aliases/TransferRecoveryResponse.md)\\>\n\n***\n\n### reminders()\n\n> **reminders**(`options?`): `AsyncGenerator`\\<\\{ `followup`: [`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md); `thread`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}, `any`, `any`\\>\n\nFollow-up reminders with thread handles, automatically paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | `Omit`\\<\\{ `attachments?`: `string`[] \\| `null`; `calendar?`: `boolean` \\| `null`; `cursor?`: `string` \\| `null`; `done?`: `boolean` \\| `null`; `inboxIds?`: `string`[] \\| `null`; `limit?`: `number` \\| `null`; `noInboxes?`: `boolean` \\| `null`; `read?`: `boolean` \\| `null`; `tags?`: `string`[] \\| `null`; \\}, `\"cursor\"` \\| `\"inboxIds\"`\\> & \\{ `inboxes?`: [`Link`](../../link/classes/Link.md)[]; \\} |\n\n#### Returns\n\n`AsyncGenerator`\\<\\{ `followup`: [`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md); `thread`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}, `any`, `any`\\>\n\n***\n\n### scheduled()\n\n> **scheduled**(`options?`): `AsyncGenerator`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\nScheduled drafts, fetched lazily in bounded pages.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `inbox?`: [`Link`](../../link/classes/Link.md); `pageSize?`: `number`; \\} |\n| `options.inbox?` | [`Link`](../../link/classes/Link.md) |\n| `options.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nSearch email threads by subject and content.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### send()\n\n> **send**(`opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a new email message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | [`SendEmailOptions`](../../message/interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n***\n\n### unblockSender()\n\n> **unblockSender**(`email`): `Promise`\\<`void`\\>\n\nUnblock a previously blocked sender.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `email` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### upsertFilter()\n\n> **upsertFilter**(`options`, `inbox?`): `Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)\\>\n\nCreate or replace a filter matching an address or domain.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`EmailFilterOptions`](../../filter/interfaces/EmailFilterOptions.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)\\>\n\n\n<!-- src/entities/email/namespace/interfaces/InboxOptions.md -->\n# Interface: InboxOptions\n\nOptions for listing inbox threads.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-pagesize\"></a> `pageSize?` | `number` | Page size (default 20, max 500). |\n| <a id=\"property-sort\"></a> `sort?` | [`ApiSortMethod`](../../../../../generated/email/types.gen/type-aliases/ApiSortMethod.md) | Sort order. Defaults to `viewed_updated`. |\n\n\n<!-- src/entities/email/thread/classes/EmailThread.md -->\n# Class: EmailThread\n\nAn email thread. A free-to-construct handle: the detail record (including\nup to the first 100 messages) loads lazily on first field access.\n\n## Extends\n\n- [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md)\\<`ThreadDetail`\\>\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | - |\n| <a id=\"property-accesslevel\"></a> `accessLevel` | `readonly` | () => `Promise`\\<[`AccessLevel`](../../../../../generated/email/types.gen/type-aliases/AccessLevel.md)\\> | `...` | The viewer's access level to this thread. | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | `...` | When the thread was created. | - | - |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"email_thread\"` | `'email_thread'` | Favorites identify email threads as `email_thread`. | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`entityType`](../../../entity/classes/PropertiedEntity.md#property-entitytype) | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`id`](../../../entity/classes/PropertiedEntity.md#property-id) |\n| <a id=\"property-inboxvisible\"></a> `inboxVisible` | `readonly` | () => `Promise`\\<`boolean`\\> | `...` | Whether the thread is visible in the inbox (i.e. not archived). | - | - |\n| <a id=\"property-isread\"></a> `isRead` | `readonly` | () => `Promise`\\<`boolean`\\> | `...` | Whether the thread has been read. | - | - |\n| <a id=\"property-latestinboundat\"></a> `latestInboundAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | Timestamp of the latest inbound message, if any. | - | - |\n| <a id=\"property-latestnonspamat\"></a> `latestNonSpamAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | Timestamp of the latest non-spam message, if any. | - | - |\n| <a id=\"property-latestoutboundat\"></a> `latestOutboundAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | Timestamp of the latest outbound message, if any. | - | - |\n| <a id=\"property-link\"></a> `link` | `readonly` | () => `Promise`\\<[`Link`](../../link/classes/Link.md)\\> | `...` | The inbox (email link) that owns this thread. | - | - |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this thread is attached to, if any. | - | - |\n| <a id=\"property-providerid\"></a> `providerId` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The provider-internal thread id (e.g. Gmail/Outlook), if any. | - | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string`\\> | `...` | When the thread was last updated. | - | - |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`EmailThread`\\> | `...` | Search email threads by subject and content, most relevant first, auto-paginated. | - | - |\n\n## Methods\n\n### addLabel()\n\n> **addLabel**(`label`): `Promise`\\<`void`\\>\n\nAdd a label to every message in the thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### archive()\n\n> **archive**(`archived?`): `Promise`\\<`void`\\>\n\nArchive the thread (or unarchive with `false`).\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `archived?` | `boolean` | `true` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### attachments()\n\n> **attachments**(): `Promise`\\<[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)[]\\>\n\nThe attachments across this thread's first 100 messages, pre-seeded from the thread detail.\n\n#### Returns\n\n`Promise`\\<[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)[]\\>\n\n***\n\n### calendarInvitations()\n\n> **calendarInvitations**(): `Promise`\\<\\{\\[`key`: `string`\\]: [`InvitationResolution`](../../../../../generated/email/types.gen/type-aliases/InvitationResolution.md); \\}\\>\n\nCalendar invitations resolved from this thread's messages.\n\n#### Returns\n\n`Promise`\\<\\{\\[`key`: `string`\\]: [`InvitationResolution`](../../../../../generated/email/types.gen/type-aliases/InvitationResolution.md); \\}\\>\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`deleteProperty`](../../../entity/classes/PropertiedEntity.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`EmailThread`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`EmailThread`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`favorite`](../../../entity/classes/PropertiedEntity.md#favorite)\n\n***\n\n### followup()\n\n> **followup**(): `Promise`\\<[`EmailFollowupResponse`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowupResponse.md)\\>\n\nRead follow-up state for this thread.\n\n#### Returns\n\n`Promise`\\<[`EmailFollowupResponse`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowupResponse.md)\\>\n\n***\n\n### markSeen()\n\n> **markSeen**(): `Promise`\\<`void`\\>\n\nMark the thread as seen.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### messages()\n\n> **messages**(`opts?`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md)[]\\>\n\nThe messages in this thread, pre-seeded from the list endpoint.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `limit?`: `number`; `since?`: `string`; \\} |\n| `opts.limit?` | `number` |\n| `opts.since?` | `string` |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md)[]\\>\n\n***\n\n### moveToProject()\n\n> **moveToProject**(`project`): `Promise`\\<`void`\\>\n\nAttach the thread to a project, or clear the project with `null`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `project` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### operations()\n\n> **operations**(): `Promise`\\<[`MailboxOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxOperation.md)[]\\>\n\nRead pending or failed mailbox changes without initiating a retry.\n\n#### Returns\n\n`Promise`\\<[`MailboxOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxOperation.md)[]\\>\n\n***\n\n### participants()\n\n> **participants**(): `Promise`\\<[`ApiContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiContactInfo.md)[]\\>\n\nEveryone on the thread (senders and recipients), deduped by email.\nDerived from the thread's first 100 messages.\n\n#### Returns\n\n`Promise`\\<[`ApiContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiContactInfo.md)[]\\>\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`permission`](../../../entity/classes/PropertiedEntity.md#permission)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`properties`](../../../entity/classes/PropertiedEntity.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`propertyReference`](../../../entity/classes/PropertiedEntity.md#propertyreference)\n\n***\n\n### removeLabel()\n\n> **removeLabel**(`label`): `Promise`\\<`void`\\>\n\nRemove a label from every message in the thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### reply()\n\n> **reply**(`opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a reply within this thread. Returns a handle when the API reports the created message's id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | [`ReplyEmailOptions`](../interfaces/ReplyEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n***\n\n### setFollowup()\n\n> **setFollowup**(`command`): `Promise`\\<[`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md)\\>\n\nSet or remove a follow-up using a persisted operation id and revision.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `command` | [`EmailFollowupCommand`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowupCommand.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md)\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`setProperty`](../../../entity/classes/PropertiedEntity.md#setproperty)\n\n***\n\n### subject()\n\n> **subject**(): `Promise`\\<`string` \\| `undefined`\\>\n\nThe thread's subject, from its first message with one.\n\n#### Returns\n\n`Promise`\\<`string` \\| `undefined`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiThread`](../../../../../generated/email/types.gen/type-aliases/ApiThread.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiThread`](../../../../../generated/email/types.gen/type-aliases/ApiThread.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiThread`](../../../../../generated/email/types.gen/type-aliases/ApiThread.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`toJSON`](../../../entity/classes/PropertiedEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`EmailThread`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`EmailThread`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`unfavorite`](../../../entity/classes/PropertiedEntity.md#unfavorite)\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`void`\\>\n\nChange project membership or share permissions for this thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `project?`: [`Project`](../../../projects/project/classes/Project.md) \\| `null`; `sharePermission?`: [`SharePermissionOptions`](../../../sharing/permissions/type-aliases/SharePermissionOptions.md); \\} |\n| `options.project?` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n| `options.sharePermission?` | [`SharePermissionOptions`](../../../sharing/permissions/type-aliases/SharePermissionOptions.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`updatePropertyOptions`](../../../entity/classes/PropertiedEntity.md#updatepropertyoptions)\n\n***\n\n### updateState()\n\n> **updateState**(`request`): `Promise`\\<`void`\\>\n\nUpdate provider-neutral read, trash, spam, or star state.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`UpdateThreadStateRequest`](../../../../../generated/email/types.gen/type-aliases/UpdateThreadStateRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailThread`\n\nA handle to a thread by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailThread`\n\n\n<!-- src/entities/email/thread/interfaces/ReplyEmailOptions.md -->\n# Interface: ReplyEmailOptions\n\nOptions for replying within an email thread.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Bcc recipients. |\n| <a id=\"property-bodytext\"></a> `bodyText` | `string` | Plain-text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Cc recipients. |\n| <a id=\"property-replyingto\"></a> `replyingTo?` | [`EmailMessage`](../../message/classes/EmailMessage.md) | The message being replied to. |\n| <a id=\"property-subject\"></a> `subject?` | `string` | Subject line. Defaults to the subject of the thread's first message. |\n| <a id=\"property-to\"></a> `to` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Recipients. |\n"
+ "documentation": "# Macro SDK: email\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/auth/types.gen/type-aliases/EmailConnectionProviders.md -->\n# Type Alias: EmailConnectionProviders\n\n> **EmailConnectionProviders** = \\{ `gmail`: `boolean`; `outlook`: `boolean`; `outlook_admin_consent_url?`: `string` \\| `null`; \\}\n\nActual deployment availability for the provider selector.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-gmail\"></a> `gmail` | `boolean` | - |\n| <a id=\"property-outlook\"></a> `outlook` | `boolean` | - |\n| <a id=\"property-outlook_admin_consent_url\"></a> `outlook_admin_consent_url?` | `string` \\| `null` | Where a Microsoft 365 administrator approves Macro for their whole directory. Present when Outlook is configured and the request named an `original_url` for the administrator's browser to return to. |\n\n\n<!-- generated/email/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/email/types.gen/type-aliases/ApiAttachmentDraft.md -->\n# Type Alias: ApiAttachmentDraft\n\n> **ApiAttachmentDraft** = \\{ `content_id?`: `string` \\| `null`; `content_type`: `string`; `draft_id`: `string`; `file_name`: `string`; `id`: `string`; `is_inline`: `boolean`; `s3_key`: `string`; `sha`: `string`; `size`: `number`; `upload_pending`: `boolean`; \\}\n\nAPI representation of a draft attachment on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-content_id\"></a> `content_id?` | `string` \\| `null` |\n| <a id=\"property-content_type\"></a> `content_type` | `string` |\n| <a id=\"property-draft_id\"></a> `draft_id` | `string` |\n| <a id=\"property-file_name\"></a> `file_name` | `string` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-is_inline\"></a> `is_inline` | `boolean` |\n| <a id=\"property-s3_key\"></a> `s3_key` | `string` |\n| <a id=\"property-sha\"></a> `sha` | `string` |\n| <a id=\"property-size\"></a> `size` | `number` |\n| <a id=\"property-upload_pending\"></a> `upload_pending` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiAttachmentForwarded.md -->\n# Type Alias: ApiAttachmentForwarded\n\n> **ApiAttachmentForwarded** = \\{ `attachment_id`: `string`; `draft_id`: `string`; `filename?`: `string` \\| `null`; `message_provider_id`: `string`; `mime_type?`: `string` \\| `null`; `provider_attachment_id?`: `string` \\| `null`; `size_bytes?`: `number` \\| `null`; \\}\n\nAPI representation of a forwarded attachment on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachment_id\"></a> `attachment_id` | `string` |\n| <a id=\"property-draft_id\"></a> `draft_id` | `string` |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` |\n| <a id=\"property-message_provider_id\"></a> `message_provider_id` | `string` |\n| <a id=\"property-mime_type\"></a> `mime_type?` | `string` \\| `null` |\n| <a id=\"property-provider_attachment_id\"></a> `provider_attachment_id?` | `string` \\| `null` |\n| <a id=\"property-size_bytes\"></a> `size_bytes?` | `number` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiContactInfo.md -->\n# Type Alias: ApiContactInfo\n\n> **ApiContactInfo** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\nAPI representation of a contact (sender or recipient).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiDraftContactInfo.md -->\n# Type Alias: ApiDraftContactInfo\n\n> **ApiDraftContactInfo** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\nContact info for draft request/response (backward-compatible with MessageToSend shape).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Email address. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Display name. |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` | Profile photo URL. |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiDraftInput.md -->\n# Type Alias: ApiDraftInput\n\n> **ApiDraftInput** = \\{ `bcc?`: [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null`; `body_html?`: `string` \\| `null`; `body_macro?`: `string` \\| `null`; `body_text?`: `string` \\| `null`; `cc?`: [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null`; `db_id?`: `string` \\| `null`; `headers_json?`: `null` \\| [`Value`](Value.md); `include_signature?`: `boolean` \\| `null`; `provider_id?`: `string` \\| `null`; `provider_thread_id?`: `string` \\| `null`; `replying_to_id?`: `string` \\| `null`; `subject`: `string`; `thread_db_id?`: `string` \\| `null`; `to?`: [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null`; \\}\n\nThe draft input matching the current `MessageToSend` JSON shape for backward compat.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null` | Bcc recipients. |\n| <a id=\"property-body_html\"></a> `body_html?` | `string` \\| `null` | HTML body (base64 URL_SAFE_NO_PAD encoded). Sanitized before storage. |\n| <a id=\"property-body_macro\"></a> `body_macro?` | `string` \\| `null` | Macro body format. |\n| <a id=\"property-body_text\"></a> `body_text?` | `string` \\| `null` | Plain text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null` | Cc recipients. |\n| <a id=\"property-db_id\"></a> `db_id?` | `string` \\| `null` | Existing message DB ID (for updating an existing draft). |\n| <a id=\"property-headers_json\"></a> `headers_json?` | `null` \\| [`Value`](Value.md) | - |\n| <a id=\"property-include_signature\"></a> `include_signature?` | `boolean` \\| `null` | Per-message override for whether to include the signature on send: `Some(false)` to exclude (user dismissed it). Omit to use the inbox's default policy. Ignored for drafts. |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` | Provider message ID. |\n| <a id=\"property-provider_thread_id\"></a> `provider_thread_id?` | `string` \\| `null` | Provider thread ID. |\n| <a id=\"property-replying_to_id\"></a> `replying_to_id?` | `string` \\| `null` | ID of the message this draft is replying to. |\n| <a id=\"property-subject\"></a> `subject` | `string` | Subject line. |\n| <a id=\"property-thread_db_id\"></a> `thread_db_id?` | `string` \\| `null` | Thread DB ID. |\n| <a id=\"property-to\"></a> `to?` | [`ApiDraftContactInfo`](ApiDraftContactInfo.md)[] \\| `null` | To recipients. |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiEmailFilter.md -->\n# Type Alias: ApiEmailFilter\n\n> **ApiEmailFilter** = \\{ `created_at`: `string`; `email_address?`: `string` \\| `null`; `email_domain?`: `string` \\| `null`; `id`: `string`; `is_important`: `boolean`; \\}\n\nA single email filter in API responses.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-email_address\"></a> `email_address?` | `string` \\| `null` |\n| <a id=\"property-email_domain\"></a> `email_domain?` | `string` \\| `null` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-is_important\"></a> `is_important` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiLabel.md -->\n# Type Alias: ApiLabel\n\n> **ApiLabel** = \\{ `createdAt`: `string`; `id`: `string`; `labelListVisibility`: [`ApiLabelListVisibility`](ApiLabelListVisibility.md); `linkId`: `string`; `messageListVisibility`: [`ApiMessageListVisibility`](ApiMessageListVisibility.md); `name`: `string`; `providerLabelId`: `string`; `type`: [`ApiLabelType`](ApiLabelType.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-labellistvisibility\"></a> `labelListVisibility` | [`ApiLabelListVisibility`](ApiLabelListVisibility.md) |\n| <a id=\"property-linkid\"></a> `linkId` | `string` |\n| <a id=\"property-messagelistvisibility\"></a> `messageListVisibility` | [`ApiMessageListVisibility`](ApiMessageListVisibility.md) |\n| <a id=\"property-name\"></a> `name` | `string` |\n| <a id=\"property-providerlabelid\"></a> `providerLabelId` | `string` |\n| <a id=\"property-type\"></a> `type` | [`ApiLabelType`](ApiLabelType.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiLabelListVisibility.md -->\n# Type Alias: ApiLabelListVisibility\n\n> **ApiLabelListVisibility** = `\"LabelShow\"` \\| `\"LabelShowIfUnread\"` \\| `\"LabelHide\"`\n\n\n<!-- generated/email/types.gen/type-aliases/ApiLabelType.md -->\n# Type Alias: ApiLabelType\n\n> **ApiLabelType** = `\"System\"` \\| `\"User\"`\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessage.md -->\n# Type Alias: ApiMessage\n\n> **ApiMessage** = \\{ `attachments`: [`ApiMessageAttachment`](ApiMessageAttachment.md)[]; `attachments_draft`: [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[]; `attachments_forwarded`: [`ApiAttachmentForwarded`](ApiAttachmentForwarded.md)[]; `bcc`: [`ApiContactInfo`](ApiContactInfo.md)[]; `body_html_sanitized?`: `string` \\| `null`; `body_macro?`: `string` \\| `null`; `body_replyless?`: `string` \\| `null`; `body_text?`: `string` \\| `null`; `calendar_invitations?`: [`CalendarInvitation`](CalendarInvitation.md)[]; `cc`: [`ApiContactInfo`](ApiContactInfo.md)[]; `created_at`: `string`; `db_id`: `string`; `from?`: `null` \\| [`ApiContactInfo`](ApiContactInfo.md); `global_id?`: `string` \\| `null`; `has_attachments`: `boolean`; `headers_json?`: `unknown`; `internal_date_ts?`: `string` \\| `null`; `is_draft`: `boolean`; `is_read`: `boolean`; `is_sent`: `boolean`; `is_starred`: `boolean`; `labels`: [`ApiMessageLabel`](ApiMessageLabel.md)[]; `link_id`: `string`; `operation_status?`: `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md); `provider_history_id?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `provider_thread_id?`: `string` \\| `null`; `replying_to_id?`: `string` \\| `null`; `scheduled_send_time?`: `string` \\| `null`; `sent_at?`: `string` \\| `null`; `size_estimate?`: `number` \\| `null`; `snippet?`: `string` \\| `null`; `subject?`: `string` \\| `null`; `thread_db_id`: `string`; `to`: [`ApiContactInfo`](ApiContactInfo.md)[]; `updated_at`: `string`; \\}\n\nAPI representation of a fully assembled email message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`ApiMessageAttachment`](ApiMessageAttachment.md)[] |\n| <a id=\"property-attachments_draft\"></a> `attachments_draft` | [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[] |\n| <a id=\"property-attachments_forwarded\"></a> `attachments_forwarded` | [`ApiAttachmentForwarded`](ApiAttachmentForwarded.md)[] |\n| <a id=\"property-bcc\"></a> `bcc` | [`ApiContactInfo`](ApiContactInfo.md)[] |\n| <a id=\"property-body_html_sanitized\"></a> `body_html_sanitized?` | `string` \\| `null` |\n| <a id=\"property-body_macro\"></a> `body_macro?` | `string` \\| `null` |\n| <a id=\"property-body_replyless\"></a> `body_replyless?` | `string` \\| `null` |\n| <a id=\"property-body_text\"></a> `body_text?` | `string` \\| `null` |\n| <a id=\"property-calendar_invitations\"></a> `calendar_invitations?` | [`CalendarInvitation`](CalendarInvitation.md)[] |\n| <a id=\"property-cc\"></a> `cc` | [`ApiContactInfo`](ApiContactInfo.md)[] |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-from\"></a> `from?` | `null` \\| [`ApiContactInfo`](ApiContactInfo.md) |\n| <a id=\"property-global_id\"></a> `global_id?` | `string` \\| `null` |\n| <a id=\"property-has_attachments\"></a> `has_attachments` | `boolean` |\n| <a id=\"property-headers_json\"></a> `headers_json?` | `unknown` |\n| <a id=\"property-internal_date_ts\"></a> `internal_date_ts?` | `string` \\| `null` |\n| <a id=\"property-is_draft\"></a> `is_draft` | `boolean` |\n| <a id=\"property-is_read\"></a> `is_read` | `boolean` |\n| <a id=\"property-is_sent\"></a> `is_sent` | `boolean` |\n| <a id=\"property-is_starred\"></a> `is_starred` | `boolean` |\n| <a id=\"property-labels\"></a> `labels` | [`ApiMessageLabel`](ApiMessageLabel.md)[] |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-operation_status\"></a> `operation_status?` | `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md) |\n| <a id=\"property-provider_history_id\"></a> `provider_history_id?` | `string` \\| `null` |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` |\n| <a id=\"property-provider_thread_id\"></a> `provider_thread_id?` | `string` \\| `null` |\n| <a id=\"property-replying_to_id\"></a> `replying_to_id?` | `string` \\| `null` |\n| <a id=\"property-scheduled_send_time\"></a> `scheduled_send_time?` | `string` \\| `null` |\n| <a id=\"property-sent_at\"></a> `sent_at?` | `string` \\| `null` |\n| <a id=\"property-size_estimate\"></a> `size_estimate?` | `number` \\| `null` |\n| <a id=\"property-snippet\"></a> `snippet?` | `string` \\| `null` |\n| <a id=\"property-subject\"></a> `subject?` | `string` \\| `null` |\n| <a id=\"property-thread_db_id\"></a> `thread_db_id` | `string` |\n| <a id=\"property-to\"></a> `to` | [`ApiContactInfo`](ApiContactInfo.md)[] |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageAttachment.md -->\n# Type Alias: ApiMessageAttachment\n\n> **ApiMessageAttachment** = \\{ `content_id?`: `string` \\| `null`; `data_url?`: `string` \\| `null`; `db_id`: `string`; `filename?`: `string` \\| `null`; `mime_type?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `reference_url?`: `string` \\| `null`; `sfs_id?`: `string` \\| `null`; `size_bytes?`: `number` \\| `null`; \\}\n\nAPI representation of a provider attachment on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-content_id\"></a> `content_id?` | `string` \\| `null` |\n| <a id=\"property-data_url\"></a> `data_url?` | `string` \\| `null` |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` |\n| <a id=\"property-mime_type\"></a> `mime_type?` | `string` \\| `null` |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` |\n| <a id=\"property-reference_url\"></a> `reference_url?` | `string` \\| `null` |\n| <a id=\"property-sfs_id\"></a> `sfs_id?` | `string` \\| `null` |\n| <a id=\"property-size_bytes\"></a> `size_bytes?` | `number` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageLabel.md -->\n# Type Alias: ApiMessageLabel\n\n> **ApiMessageLabel** = \\{ `created_at`: `string`; `id?`: `string` \\| `null`; `label_list_visibility?`: `null` \\| [`ApiLabelListVisibility`](ApiLabelListVisibility.md); `link_id`: `string`; `message_list_visibility?`: `null` \\| [`ApiMessageListVisibility`](ApiMessageListVisibility.md); `name?`: `string` \\| `null`; `provider_label_id`: `string`; `type_?`: `null` \\| [`ApiLabelType`](ApiLabelType.md); \\}\n\nAPI representation of a label on a message.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-id\"></a> `id?` | `string` \\| `null` |\n| <a id=\"property-label_list_visibility\"></a> `label_list_visibility?` | `null` \\| [`ApiLabelListVisibility`](ApiLabelListVisibility.md) |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-message_list_visibility\"></a> `message_list_visibility?` | `null` \\| [`ApiMessageListVisibility`](ApiMessageListVisibility.md) |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-provider_label_id\"></a> `provider_label_id` | `string` |\n| <a id=\"property-type_\"></a> `type_?` | `null` \\| [`ApiLabelType`](ApiLabelType.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageListVisibility.md -->\n# Type Alias: ApiMessageListVisibility\n\n> **ApiMessageListVisibility** = `\"Show\"` \\| `\"Hide\"`\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageOperation.md -->\n# Type Alias: ApiMessageOperation\n\n> **ApiMessageOperation** = \\{ `issue?`: `null` \\| [`ApiMessageOperationIssue`](ApiMessageOperationIssue.md); `remote_version?`: `string` \\| `null`; `revision`: `string`; `state`: [`ApiMessageOperationState`](ApiMessageOperationState.md); \\}\n\nVersions are opaque decimal strings so clients never truncate an i64.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-issue\"></a> `issue?` | `null` \\| [`ApiMessageOperationIssue`](ApiMessageOperationIssue.md) |\n| <a id=\"property-remote_version\"></a> `remote_version?` | `string` \\| `null` |\n| <a id=\"property-revision\"></a> `revision` | `string` |\n| <a id=\"property-state\"></a> `state` | [`ApiMessageOperationState`](ApiMessageOperationState.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageOperationIssue.md -->\n# Type Alias: ApiMessageOperationIssue\n\n> **ApiMessageOperationIssue** = `\"ACCEPTING_REMOTE\"` \\| `\"DRAFT_CONFLICT\"` \\| `\"CREATION_UNKNOWN\"` \\| `\"ATTACHMENT_UNKNOWN\"` \\| `\"SEND_UNKNOWN\"` \\| `\"SEND_REJECTED\"` \\| `\"ACCESS_REVOKED\"` \\| `\"INVALID_CONTENT\"` \\| `\"MOVE_PENDING\"` \\| `\"MOVE_CONFLICT\"` \\| `\"MOVE_SOURCE_SENT\"` \\| `\"MOVE_REAUTHORIZATION\"` \\| `\"MOVE_ORIGINAL_REMAINS\"`\n\nProvider-neutral state exposed to clients.\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageOperationState.md -->\n# Type Alias: ApiMessageOperationState\n\n> **ApiMessageOperationState** = `\"PENDING\"` \\| `\"SYNCHRONIZED\"` \\| `\"CONFLICT\"` \\| `\"UNCERTAIN\"` \\| `\"SUBMITTING\"` \\| `\"CONFIRMING\"` \\| `\"SENT\"` \\| `\"DELETED\"` \\| `\"CANCELLED\"` \\| `\"FAILED\"`\n\nProvider-neutral state exposed to clients.\n\n\n<!-- generated/email/types.gen/type-aliases/ApiMessageResolutionAction.md -->\n# Type Alias: ApiMessageResolutionAction\n\n> **ApiMessageResolutionAction** = `\"keep_local\"` \\| `\"use_provider\"` \\| `\"recheck\"` \\| `\"retry_send\"` \\| `\"keep_original\"`\n\nA deliberate resolution of a particular observed operation version.\n\n\n<!-- generated/email/types.gen/type-aliases/ApiSortMethod.md -->\n# Type Alias: ApiSortMethod\n\n> **ApiSortMethod** = `\"viewed_at\"` \\| `\"updated_at\"` \\| `\"created_at\"` \\| `\"viewed_updated\"`\n\ncommon types of sorts based on timestamps\n\n\n<!-- generated/email/types.gen/type-aliases/ApiThread.md -->\n# Type Alias: ApiThread\n\n> **ApiThread** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `created_at`: `string`; `db_id`: `string`; `inbox_visible`: `boolean`; `is_read`: `boolean`; `latest_inbound_message_ts?`: `string` \\| `null`; `latest_non_spam_message_ts?`: `string` \\| `null`; `latest_outbound_message_ts?`: `string` \\| `null`; `link_id`: `string`; `messages`: [`ApiMessage`](ApiMessage.md)[]; `project_id?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nAPI representation of a fully assembled email thread.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-inbox_visible\"></a> `inbox_visible` | `boolean` |\n| <a id=\"property-is_read\"></a> `is_read` | `boolean` |\n| <a id=\"property-latest_inbound_message_ts\"></a> `latest_inbound_message_ts?` | `string` \\| `null` |\n| <a id=\"property-latest_non_spam_message_ts\"></a> `latest_non_spam_message_ts?` | `string` \\| `null` |\n| <a id=\"property-latest_outbound_message_ts\"></a> `latest_outbound_message_ts?` | `string` \\| `null` |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-messages\"></a> `messages` | [`ApiMessage`](ApiMessage.md)[] |\n| <a id=\"property-project_id\"></a> `project_id?` | `string` \\| `null` |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/Attachment.md -->\n# Type Alias: Attachment\n\n> **Attachment** = \\{ `content_id?`: `string` \\| `null`; `data_url?`: `string` \\| `null`; `db_id`: `string`; `filename?`: `string` \\| `null`; `mime_type?`: `string` \\| `null`; `provider_id?`: `string` \\| `null`; `reference_url?`: `string` \\| `null`; `sfs_id?`: `string` \\| `null`; `size_bytes?`: `number` \\| `null`; \\}\n\nAttachments of a message, as sent to us by the provider.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-content_id\"></a> `content_id?` | `string` \\| `null` | - |\n| <a id=\"property-data_url\"></a> `data_url?` | `string` \\| `null` | - |\n| <a id=\"property-db_id\"></a> `db_id` | `string` | - |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` | - |\n| <a id=\"property-mime_type\"></a> `mime_type?` | `string` \\| `null` | - |\n| <a id=\"property-provider_id\"></a> `provider_id?` | `string` \\| `null` | - |\n| <a id=\"property-reference_url\"></a> `reference_url?` | `string` \\| `null` | Cloud reference: open this provider page instead of downloading bytes. |\n| <a id=\"property-sfs_id\"></a> `sfs_id?` | `string` \\| `null` | - |\n| <a id=\"property-size_bytes\"></a> `size_bytes?` | `number` \\| `null` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/AttendeeResponseStatus.md -->\n# Type Alias: AttendeeResponseStatus\n\n> **AttendeeResponseStatus** = `\"needs_action\"` \\| `\"accepted\"` \\| `\"declined\"` \\| `\"tentative\"`\n\nRSVP state for an attendee.\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarAttendee.md -->\n# Type Alias: CalendarAttendee\n\n> **CalendarAttendee** = \\{ `comment?`: `string` \\| `null`; `displayName?`: `string` \\| `null`; `email`: `string`; `isOptional`: `boolean`; `isOrganizer`: `boolean`; `isSelf`: `boolean`; `responseStatus`: [`AttendeeResponseStatus`](AttendeeResponseStatus.md); \\}\n\nAn attendee on a calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Optional attendee comment. |\n| <a id=\"property-displayname\"></a> `displayName?` | `string` \\| `null` | Provider display name. |\n| <a id=\"property-email\"></a> `email` | `string` | Normalized email address. |\n| <a id=\"property-isoptional\"></a> `isOptional` | `boolean` | Whether attendance is optional. |\n| <a id=\"property-isorganizer\"></a> `isOrganizer` | `boolean` | Whether this attendee is the organizer. |\n| <a id=\"property-isself\"></a> `isSelf` | `boolean` | Whether this attendee is one of the viewing requester's inboxes. |\n| <a id=\"property-responsestatus\"></a> `responseStatus` | [`AttendeeResponseStatus`](AttendeeResponseStatus.md) | RSVP state. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarEvent.md -->\n# Type Alias: CalendarEvent\n\n> **CalendarEvent** = \\{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarId?`: `string` \\| `null`; `conferenceProvider?`: `null` \\| [`ConferenceProvider`](ConferenceProvider.md); `conferenceUrl?`: `string` \\| `null`; `createdAt`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType?`: [`EventType`](EventType.md); `icalUid`: `string`; `id`: `string`; `isReadOnly`: `boolean`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `ownerId`: `string`; `recurrenceLines`: `string`[]; `reminders?`: [`EventReminders`](EventReminders.md); `sequence`: `number`; `sources?`: [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[]; `status`: [`EventStatus`](EventStatus.md); `time`: [`EventTime`](EventTime.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `updatedAt`: `string`; `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nA stable, first-class Macro calendar event entity.\n\nContent fields hold the canonical source's values: the account's primary\ncalendar copy when one is synced, else the freshest remaining copy.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees, keyed by email during persistence. |\n| <a id=\"property-calendarid\"></a> `calendarId?` | `string` \\| `null` | Calendar the canonical source belongs to, when known. Absent only in projections stored before calendars were attributed. |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `null` \\| [`ConferenceProvider`](ConferenceProvider.md) | - |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Direct join URL when known. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Entity creation time. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. Distinct from the organizer when someone writes onto a calendar they do not own. Omitted from stored projections when unknown so events ingested before this field still compare equal. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType?` | [`EventType`](EventType.md) | Provider event type. Skipped when it is the regular type so projections stored before event types were modeled still compare equal. |\n| <a id=\"property-icaluid\"></a> `icalUid` | `string` | RFC 5545 UID used to reconcile provider and email sources. |\n| <a id=\"property-id\"></a> `id` | `string` | Macro entity identifier. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the canonical source's calendar prohibits editing it. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer email. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer display name. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | Macro user who owns this event entity. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](EventReminders.md) | Per-user reminder configuration. Skipped when it is the provider default so projections stored before reminders were modeled still compare equal. |\n| <a id=\"property-sequence\"></a> `sequence` | `number` | Provider/iCalendar sequence number. |\n| <a id=\"property-sources\"></a> `sources?` | [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[] | Content of every active copy of this event, canonical first: the primary calendar's copy, then the freshest. A client picks the copy whose calendar it is showing and falls back to the first. Populated only on the read path, so stored projections omit it. |\n| <a id=\"property-status\"></a> `status` | [`EventStatus`](EventStatus.md) | Event status. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Entity update time. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarEventSourceContent.md -->\n# Type Alias: CalendarEventSourceContent\n\n> **CalendarEventSourceContent** = \\{ `calendarId`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType`: [`EventType`](EventType.md); `isReadOnly`: `boolean`; `location?`: `string` \\| `null`; `reminders`: [`EventReminders`](EventReminders.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nThe content one provider copy of an event carries.\n\nGoogle keeps these fields per calendar copy: a shared calendar's copy of a\nmember's event can have its own title, type, reminders, and access role.\nThe entity holds its canonical source's values. Every other copy's values\nare read from here so a client can show the copy that belongs to the\ncalendar being viewed.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendarid\"></a> `calendarId` | `string` | Calendar this copy lives on. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType` | [`EventType`](EventType.md) | Provider event type. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the calendar's access role prohibits editing this copy. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-reminders\"></a> `reminders` | [`EventReminders`](EventReminders.md) | Reminder configuration of this copy. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarInvitation.md -->\n# Type Alias: CalendarInvitation\n\n> **CalendarInvitation** = \\{ `attendees`: [`InvitationParticipant`](InvitationParticipant.md)[]; `comment?`: `string` \\| `null`; `conference_url?`: `string` \\| `null`; `description?`: `string` \\| `null`; `dtstamp?`: `string` \\| `null`; `end?`: `null` \\| [`InvitationDateTime`](InvitationDateTime.md); `id`: `string`; `last_modified?`: `string` \\| `null`; `location?`: `string` \\| `null`; `method`: [`InvitationMethod`](InvitationMethod.md); `organizer?`: `null` \\| [`InvitationParticipant`](InvitationParticipant.md); `recurrence_id?`: `null` \\| [`InvitationDateTime`](InvitationDateTime.md); `recurrence_id_raw?`: `string` \\| `null`; `sequence`: `number`; `start?`: `null` \\| [`InvitationDateTime`](InvitationDateTime.md); `status?`: `string` \\| `null`; `title?`: `string` \\| `null`; `uid`: `string`; \\}\n\nDisplay snapshot of one meaningful VEVENT, owned by the email domain.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`InvitationParticipant`](InvitationParticipant.md)[] | Historical attendee identities and participation metadata. |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Reply or counter-proposal comment. |\n| <a id=\"property-conference_url\"></a> `conference_url?` | `string` \\| `null` | Validated HTTP(S) conferencing URL; never fetched during rendering. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Plaintext description, retaining passwords and dial-in instructions. |\n| <a id=\"property-dtstamp\"></a> `dtstamp?` | `string` \\| `null` | Scheduling timestamp in its original spelling. |\n| <a id=\"property-end\"></a> `end?` | `null` \\| [`InvitationDateTime`](InvitationDateTime.md) | - |\n| <a id=\"property-id\"></a> `id` | `string` | Content-derived component identity, stable across repeated extraction. |\n| <a id=\"property-last_modified\"></a> `last_modified?` | `string` \\| `null` | Last modification timestamp in its original spelling. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Plaintext event location. |\n| <a id=\"property-method\"></a> `method` | [`InvitationMethod`](InvitationMethod.md) | Original scheduling method. |\n| <a id=\"property-organizer\"></a> `organizer?` | `null` \\| [`InvitationParticipant`](InvitationParticipant.md) | - |\n| <a id=\"property-recurrence_id\"></a> `recurrence_id?` | `null` \\| [`InvitationDateTime`](InvitationDateTime.md) | - |\n| <a id=\"property-recurrence_id_raw\"></a> `recurrence_id_raw?` | `string` \\| `null` | Original recurrence identifier spelling and parameters. |\n| <a id=\"property-sequence\"></a> `sequence` | `number` | Scheduling revision, distinct from delivery order. |\n| <a id=\"property-start\"></a> `start?` | `null` \\| [`InvitationDateTime`](InvitationDateTime.md) | - |\n| <a id=\"property-status\"></a> `status?` | `string` \\| `null` | Original event status. |\n| <a id=\"property-title\"></a> `title?` | `string` \\| `null` | Event summary. |\n| <a id=\"property-uid\"></a> `uid` | `string` | iCalendar UID; never a Google provider event ID. |\n\n\n<!-- generated/email/types.gen/type-aliases/CalendarOccurrence.md -->\n# Type Alias: CalendarOccurrence\n\n> **CalendarOccurrence** = \\{ `eventId`: `string`; `isCancelled`: `boolean`; `occurrenceKey`: `string`; `recurrenceId?`: `string` \\| `null`; `time`: [`EventTime`](EventTime.md); \\}\n\nA materialized recurrence instance optimized for range queries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-eventid\"></a> `eventId` | `string` | Owning event entity. |\n| <a id=\"property-iscancelled\"></a> `isCancelled` | `boolean` | Whether the instance was cancelled. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey` | `string` | Stable key within the event. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` \\| `null` | Provider recurrence identifier, when applicable. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Instance time. |\n\n\n<!-- generated/email/types.gen/type-aliases/ConferenceProvider.md -->\n# Type Alias: ConferenceProvider\n\n> **ConferenceProvider** = `\"microsoft_teams\"` \\| `\"google_meet\"` \\| `\"other\"`\n\nThe conferencing system backing an event's join URL.\n\nCalendars can create Google Meet or Microsoft Teams according to their\ncapabilities. Imported third-party conferences are labeled separately.\nOmitting a conference change preserves the current conference; explicit\nchanges still require provider and calendar capability validation.\n\n\n<!-- generated/email/types.gen/type-aliases/ContactInfo.md -->\n# Type Alias: ContactInfo\n\n> **ContactInfo** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ContactInfoLegacy.md -->\n# Type Alias: ContactInfoLegacy\n\n> **ContactInfoLegacy** = \\{ `email`: `string`; `email_address`: `string`; `name?`: `string` \\| `null`; `photo_url?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` |\n| <a id=\"property-email_address\"></a> `email_address` | `string` |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` |\n\n\n<!-- generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md -->\n# Type Alias: ContactInfoWithInteraction\n\n> **ContactInfoWithInteraction** = [`ContactInfoLegacy`](ContactInfoLegacy.md) & \\{ `last_interaction`: `string`; \\}\n\n## Type Declaration\n\n| Name | Type |\n| ------ | ------ |\n| `last_interaction` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/EventReminderOverride.md -->\n# Type Alias: EventReminderOverride\n\n> **EventReminderOverride** = \\{ `method`: `string`; `minutes`: `number`; \\}\n\nOne reminder: how it alerts and how many minutes before the event start\n(before midnight in the calendar's zone for all-day events) it fires.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-method\"></a> `method` | `string` | Provider method, stored verbatim; only `popup` fires Macro notifications. |\n| <a id=\"property-minutes\"></a> `minutes` | `number` | Minutes before the event start. |\n\n\n<!-- generated/email/types.gen/type-aliases/EventReminders.md -->\n# Type Alias: EventReminders\n\n> **EventReminders** = \\{ `overrides?`: [`EventReminderOverride`](EventReminderOverride.md)[]; `useDefault`: `boolean`; \\}\n\nPer-user reminder configuration for an event, mirroring Google's model:\neither the calendar's default reminders apply, or the explicit overrides\nreplace them entirely.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-overrides\"></a> `overrides?` | [`EventReminderOverride`](EventReminderOverride.md)[] | Explicit reminders replacing the defaults when `use_default` is off. |\n| <a id=\"property-usedefault\"></a> `useDefault` | `boolean` | Whether the calendar's default reminders apply. |\n\n\n<!-- generated/email/types.gen/type-aliases/EventStatus.md -->\n# Type Alias: EventStatus\n\n> **EventStatus** = `\"confirmed\"` \\| `\"tentative\"` \\| `\"cancelled\"`\n\nCanonical event status.\n\n\n<!-- generated/email/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- generated/email/types.gen/type-aliases/EventTransparency.md -->\n# Type Alias: EventTransparency\n\n> **EventTransparency** = `\"opaque\"` \\| `\"transparent\"`\n\nWhether an event blocks availability.\n\n\n<!-- generated/email/types.gen/type-aliases/EventType.md -->\n# Type Alias: EventType\n\n> **EventType** = `\"default\"` \\| `\"out_of_office\"` \\| `\"focus_time\"` \\| `\"working_location\"` \\| `\"birthday\"` \\| `\"from_gmail\"`\n\nGoogle's event type: ordinary meetings versus the status-style entries\n(working location, out of office, focus time, birthdays) Google renders\nand notifies differently. Immutable at the provider after creation.\n\n\n<!-- generated/email/types.gen/type-aliases/EventVisibility.md -->\n# Type Alias: EventVisibility\n\n> **EventVisibility** = `\"default\"` \\| `\"public\"` \\| `\"private\"` \\| `\"confidential\"`\n\nVisibility of event details.\n\n\n<!-- generated/email/types.gen/type-aliases/GetAttachmentResponse.md -->\n# Type Alias: GetAttachmentResponse\n\n> **GetAttachmentResponse** = \\{ `attachment`: [`Attachment`](Attachment.md); \\}\n\nThe response returned from the get attachment endpoint\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachment\"></a> `attachment` | [`Attachment`](Attachment.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/GetAttachmentResponses.md -->\n# Type Alias: GetAttachmentResponses\n\n> **GetAttachmentResponses** = \\{ `200`: [`GetAttachmentResponse`](GetAttachmentResponse.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-200\"></a> `200` | [`GetAttachmentResponse`](GetAttachmentResponse.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/GetMessageResponses.md -->\n# Type Alias: GetMessageResponses\n\n> **GetMessageResponses** = \\{ `200`: [`ParsedMessage`](ParsedMessage.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-200\"></a> `200` | [`ParsedMessage`](ParsedMessage.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationDateTime.md -->\n# Type Alias: InvitationDateTime\n\n> **InvitationDateTime** = \\{ `kind`: `\"date\"`; `value`: `string`; \\} \\| \\{ `kind`: `\"zoned\"`; `time_zone`: `string`; `value`: `string`; \\} \\| \\{ `kind`: `\"unresolved\"`; `time_zone?`: `string` \\| `null`; `value`: `string`; \\}\n\nPreserve date-only and unresolved times without manufacturing UTC instants.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"date\"` | - |\n| `value` | `string` | ISO calendar date. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"zoned\"`; `time_zone`: `string`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"zoned\"` | - |\n| `time_zone` | `string` | IANA zone of the original TZID, or UTC. |\n| `value` | `string` | RFC3339 instant. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"unresolved\"`; `time_zone?`: `string` \\| `null`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"unresolved\"` | - |\n| `time_zone?` | `string` \\| `null` | Original TZID if present. |\n| `value` | `string` | ISO local wall time, without an offset. |\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationMethod.md -->\n# Type Alias: InvitationMethod\n\n> **InvitationMethod** = `\"request\"` \\| `\"reply\"` \\| `\"cancel\"` \\| `\"counter\"` \\| `\"publish\"` \\| `\"unknown\"`\n\nOriginal scheduling method, including methods unsupported for actions.\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationParticipant.md -->\n# Type Alias: InvitationParticipant\n\n> **InvitationParticipant** = \\{ `email`: `string`; `name?`: `string` \\| `null`; `participation_status?`: `string` \\| `null`; \\}\n\nScheduling participant; saved responses are historical, not current RSVP.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Participant calendar address. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Sender-supplied display name. |\n| <a id=\"property-participation_status\"></a> `participation_status?` | `string` \\| `null` | Original PARTSTAT, retaining extensions. |\n\n\n<!-- generated/email/types.gen/type-aliases/InvitationResolution.md -->\n# Type Alias: InvitationResolution\n\n> **InvitationResolution** = \\{ `kind`: `\"disconnected\"`; \\} \\| \\{ `kind`: `\"still_syncing\"`; \\} \\| \\{ `kind`: `\"cancelled\"`; \\} \\| \\{ `kind`: `\"unavailable\"`; \\} \\| \\{ `kind`: `\"no_match\"`; \\} \\| \\{ `kind`: `\"ambiguous\"`; \\} \\| \\{ `can_join`: `boolean`; `can_respond`: `boolean`; `event`: [`CalendarEvent`](CalendarEvent.md); `is_stale`: `boolean`; `kind`: `\"resolved\"`; `occurrence`: [`CalendarOccurrence`](CalendarOccurrence.md); `responding_email`: `string`; \\}\n\nRefreshable result, distinct from the immutable email contents.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"disconnected\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"still_syncing\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"cancelled\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"unavailable\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"no_match\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"ambiguous\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `can_join`: `boolean`; `can_respond`: `boolean`; `event`: [`CalendarEvent`](CalendarEvent.md); `is_stale`: `boolean`; `kind`: `\"resolved\"`; `occurrence`: [`CalendarOccurrence`](CalendarOccurrence.md); `responding_email`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `can_join` | `boolean` | Whether the conference link belongs to the reconciled scheduling target. |\n| `can_respond` | `boolean` | Whether a response is currently allowed. |\n| `event` | [`CalendarEvent`](CalendarEvent.md) | Current occurrence-specific content. |\n| `is_stale` | `boolean` | Whether the provider projection trails the email revision. |\n| `kind` | `\"resolved\"` | - |\n| `occurrence` | [`CalendarOccurrence`](CalendarOccurrence.md) | Original occurrence identity and current time. |\n| `responding_email` | `string` | Connected address that would respond. |\n\n\n<!-- generated/email/types.gen/type-aliases/LabelInfo.md -->\n# Type Alias: LabelInfo\n\n> **LabelInfo** = \\{ `name`: `string`; `provider_id`: `string`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-name\"></a> `name` | `string` |\n| <a id=\"property-provider_id\"></a> `provider_id` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/Link.md -->\n# Type Alias: Link\n\n> **Link** = \\{ `calendar_disabled`: `boolean`; `created_at`: `string`; `email_address`: `string`; `fusionauth_user_id`: `string`; `has_calendar_data`: `boolean`; `id`: `string`; `is_primary`: `boolean`; `is_sync_active`: `boolean`; `macro_id`: `string`; `needs_calendar_permission`: `boolean`; `needs_reauth`: `boolean`; `photo_url?`: `string` \\| `null`; `provider`: [`UserProvider`](UserProvider.md); `settings`: [`Settings`](Settings.md); `sync_status`: [`SyncStatus`](SyncStatus.md); `updated_at`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar_disabled\"></a> `calendar_disabled` | `boolean` | Whether the user turned calendar off for this inbox, which also removed its calendar data. `needs_calendar_permission` is true either way, so this is what separates \"never granted\" from \"deliberately off\" — unprompted calendar nags must stay quiet for the latter. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-email_address\"></a> `email_address` | `string` | - |\n| <a id=\"property-fusionauth_user_id\"></a> `fusionauth_user_id` | `string` | - |\n| <a id=\"property-has_calendar_data\"></a> `has_calendar_data` | `boolean` | Whether Macro holds calendar data for this inbox. Drives the turn-off control on its own, so removing that data never depends on the recorded scopes still matching the set Macro requests today — a set that changes as the integration narrows, stranding data behind a capability check that no longer recognizes an older grant. |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_primary\"></a> `is_primary` | `boolean` | - |\n| <a id=\"property-is_sync_active\"></a> `is_sync_active` | `boolean` | - |\n| <a id=\"property-macro_id\"></a> `macro_id` | `string` | - |\n| <a id=\"property-needs_calendar_permission\"></a> `needs_calendar_permission` | `boolean` | Whether the link's Google grant is missing the calendar scope. True for inboxes connected before the calendar capability existed (and for grants where the user declined it); drives the per-inbox calendar upgrade prompt. Re-running the connect flow records the new grant. |\n| <a id=\"property-needs_reauth\"></a> `needs_reauth` | `boolean` | Whether the link's Google grant needs to be reconnected. Drives the per-inbox reconnect prompt independently of the sync-status badge. |\n| <a id=\"property-photo_url\"></a> `photo_url?` | `string` \\| `null` | The inbox's own profile photo (its self-contact's SFS photo), if synced. |\n| <a id=\"property-provider\"></a> `provider` | [`UserProvider`](UserProvider.md) | - |\n| <a id=\"property-settings\"></a> `settings` | [`Settings`](Settings.md) | - |\n| <a id=\"property-sync_status\"></a> `sync_status` | [`SyncStatus`](SyncStatus.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxAction.md -->\n# Type Alias: MailboxAction\n\n> **MailboxAction** = \\{ `kind`: `\"read\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"flagged\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"archived\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"trashed\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"junk\"`; `value`: `boolean`; \\} \\| \\{ `kind`: `\"category\"`; `value`: \\{ `name`: `string`; `present`: `boolean`; \\}; \\}\n\nDesired organization state. Categories never stand in for folders or flags.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"read\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"read\"` | - |\n| `value` | `boolean` | Mark correspondence read or unread. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"flagged\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"flagged\"` | - |\n| `value` | `boolean` | Set the follow-up star. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"archived\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"archived\"` | - |\n| `value` | `boolean` | Archive inbox messages, or restore received correspondence to the inbox. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"trashed\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"trashed\"` | - |\n| `value` | `boolean` | Move to recoverable trash, or restore correspondence to Inbox (drafts to Drafts). |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"junk\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"junk\"` | - |\n| `value` | `boolean` | Move to junk, or restore to the inbox. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"category\"`; `value`: \\{ `name`: `string`; `present`: `boolean`; \\}; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"category\"` | - |\n| `value` | \\{ `name`: `string`; `present`: `boolean`; \\} | Add/remove a category while preserving other provider assignments. |\n| `value.name` | `string` | - |\n| `value.present` | `boolean` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxOperation.md -->\n# Type Alias: MailboxOperation\n\n> **MailboxOperation** = \\{ `action`: [`MailboxAction`](MailboxAction.md); `id`: `string`; `state`: [`MailboxOperationState`](MailboxOperationState.md); `updated_at`: `string`; \\}\n\nDurable outcome of an accepted organization action.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-action\"></a> `action` | [`MailboxAction`](MailboxAction.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-state\"></a> `state` | [`MailboxOperationState`](MailboxOperationState.md) |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxOperationState.md -->\n# Type Alias: MailboxOperationState\n\n> **MailboxOperationState** = `\"pending\"` \\| `\"applied\"` \\| `\"failed\"` \\| `\"cancelled\"`\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxSettingsChange.md -->\n# Type Alias: MailboxSettingsChange\n\n> **MailboxSettingsChange** = `\"create_label\"` \\| `\"delete_label\"` \\| `\"sender_block\"`\n\n\n<!-- generated/email/types.gen/type-aliases/MailboxSettingsOperation.md -->\n# Type Alias: MailboxSettingsOperation\n\n> **MailboxSettingsOperation** = \\{ `enabled`: `boolean`; `id`: `string`; `kind`: [`MailboxSettingsChange`](MailboxSettingsChange.md); `needs_attention`: `boolean`; `resource`: `string`; \\}\n\nAn accepted inbox configuration change awaiting provider confirmation.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-enabled\"></a> `enabled` | `boolean` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-kind\"></a> `kind` | [`MailboxSettingsChange`](MailboxSettingsChange.md) |\n| <a id=\"property-needs_attention\"></a> `needs_attention` | `boolean` |\n| <a id=\"property-resource\"></a> `resource` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/MessageOperationResponse.md -->\n# Type Alias: MessageOperationResponse\n\n> **MessageOperationResponse** = \\{ `operation?`: `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md); \\}\n\nAuthorized polling response. Gmail has no asynchronous draft operation.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-operation\"></a> `operation?` | `null` \\| [`ApiMessageOperation`](ApiMessageOperation.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/ParsedMessage.md -->\n# Type Alias: ParsedMessage\n\n> **ParsedMessage** = \\{ `bcc`: [`ContactInfo`](ContactInfo.md)[]; `body_parsed?`: `string` \\| `null`; `cc`: [`ContactInfo`](ContactInfo.md)[]; `db_id`: `string`; `from?`: `null` \\| [`ContactInfo`](ContactInfo.md); `internal_date_ts?`: `string` \\| `null`; `labels`: [`LabelInfo`](LabelInfo.md)[]; `link_id`: `string`; `subject?`: `string` \\| `null`; `thread_db_id`: `string`; `to`: [`ContactInfo`](ContactInfo.md)[]; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc` | [`ContactInfo`](ContactInfo.md)[] |\n| <a id=\"property-body_parsed\"></a> `body_parsed?` | `string` \\| `null` |\n| <a id=\"property-cc\"></a> `cc` | [`ContactInfo`](ContactInfo.md)[] |\n| <a id=\"property-db_id\"></a> `db_id` | `string` |\n| <a id=\"property-from\"></a> `from?` | `null` \\| [`ContactInfo`](ContactInfo.md) |\n| <a id=\"property-internal_date_ts\"></a> `internal_date_ts?` | `string` \\| `null` |\n| <a id=\"property-labels\"></a> `labels` | [`LabelInfo`](LabelInfo.md)[] |\n| <a id=\"property-link_id\"></a> `link_id` | `string` |\n| <a id=\"property-subject\"></a> `subject?` | `string` \\| `null` |\n| <a id=\"property-thread_db_id\"></a> `thread_db_id` | `string` |\n| <a id=\"property-to\"></a> `to` | [`ContactInfo`](ContactInfo.md)[] |\n\n\n<!-- generated/email/types.gen/type-aliases/ResolveMessageOperationRequest.md -->\n# Type Alias: ResolveMessageOperationRequest\n\n> **ResolveMessageOperationRequest** = \\{ `accept_duplicate_risk?`: `boolean`; `action`: [`ApiMessageResolutionAction`](ApiMessageResolutionAction.md); `remote_version?`: `string` \\| `null`; `revision`: `string`; \\}\n\nStale versions fail without altering the current operation.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-accept_duplicate_risk\"></a> `accept_duplicate_risk?` | `boolean` |\n| <a id=\"property-action\"></a> `action` | [`ApiMessageResolutionAction`](ApiMessageResolutionAction.md) |\n| <a id=\"property-remote_version\"></a> `remote_version?` | `string` \\| `null` |\n| <a id=\"property-revision\"></a> `revision` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/Settings.md -->\n# Type Alias: Settings\n\n> **Settings** = \\{ `signature?`: `string` \\| `null`; `signature_on_replies_forwards?`: `boolean` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-signature\"></a> `signature?` | `string` \\| `null` | The user's email signature content (HTML). On a patch, omit or send `null` to leave unchanged (both deserialize to `None`); pass an empty string to clear it. The column cannot be set to SQL NULL via patch. |\n| <a id=\"property-signature_on_replies_forwards\"></a> `signature_on_replies_forwards?` | `boolean` \\| `null` | - |\n\n\n<!-- generated/email/types.gen/type-aliases/SyncStatus.md -->\n# Type Alias: SyncStatus\n\n> **SyncStatus** = `\"SYNCING\"` \\| `\"UP_TO_DATE\"` \\| `\"ERROR\"` \\| `\"NEEDS_REAUTH\"` \\| `\"INACTIVE\"`\n\nCoarse sync state for an inbox, used to render a one-line hint in the\nmulti-inbox settings list. Derived from the link's `is_sync_active` flag, its\nreauth health, and its most recent backfill job.\n\n\n<!-- generated/email/types.gen/type-aliases/ThreadStateField.md -->\n# Type Alias: ThreadStateField\n\n> **ThreadStateField** = `\"read\"` \\| `\"starred\"` \\| `\"trashed\"` \\| `\"junk\"`\n\nSemantic mailbox facts, independent of folder/category names.\n\n\n<!-- generated/email/types.gen/type-aliases/TransferDraftRequest.md -->\n# Type Alias: TransferDraftRequest\n\n> **TransferDraftRequest** = \\{ `destination_link_id`: `string`; `operation_id`: `string`; \\}\n\nReuse the same operation ID when retrying after a lost response.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-destination_link_id\"></a> `destination_link_id` | `string` |\n| <a id=\"property-operation_id\"></a> `operation_id` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/TransferDraftResponse.md -->\n# Type Alias: TransferDraftResponse\n\n> **TransferDraftResponse** = \\{ `attachments`: [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[]; `message_id`: `string`; `source_id`: `string`; `source_thread_id`: `string`; `thread_id`: `string`; \\}\n\nA new identity prevents delayed writes from mutating the moved copy.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`ApiAttachmentDraft`](ApiAttachmentDraft.md)[] |\n| <a id=\"property-message_id\"></a> `message_id` | `string` |\n| <a id=\"property-source_id\"></a> `source_id` | `string` |\n| <a id=\"property-source_thread_id\"></a> `source_thread_id` | `string` |\n| <a id=\"property-thread_id\"></a> `thread_id` | `string` |\n\n\n<!-- generated/email/types.gen/type-aliases/TransferRecoveryResponse.md -->\n# Type Alias: TransferRecoveryResponse\n\n> **TransferRecoveryResponse** = \\{ `committed?`: `null` \\| [`TransferDraftResponse`](TransferDraftResponse.md); \\}\n\nA null result confirms that the move cannot commit, even if its request was delayed.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-committed\"></a> `committed?` | `null` \\| [`TransferDraftResponse`](TransferDraftResponse.md) |\n\n\n<!-- generated/email/types.gen/type-aliases/UpdateThreadStateRequest.md -->\n# Type Alias: UpdateThreadStateRequest\n\n> **UpdateThreadStateRequest** = \\{ `field`: [`ThreadStateField`](ThreadStateField.md); `value`: `boolean`; \\}\n\nDesired state for every applicable message in an authorized thread.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-field\"></a> `field` | [`ThreadStateField`](ThreadStateField.md) |\n| <a id=\"property-value\"></a> `value` | `boolean` |\n\n\n<!-- generated/email/types.gen/type-aliases/UserProvider.md -->\n# Type Alias: UserProvider\n\n> **UserProvider** = `\"GMAIL\"` \\| `\"OUTLOOK\"`\n\n\n<!-- generated/email/types.gen/type-aliases/Value.md -->\n# Type Alias: Value\n\n> **Value** = `unknown`\n\n\n<!-- generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailFollowup.md -->\n# Type Alias: EmailFollowup\n\n> **EmailFollowup** = \\{ `condition`: [`EmailReminderCondition`](EmailReminderCondition.md); `linkId`: `string`; `remindAt`: `string`; `reminderId`: `string`; `revision`: `string`; `state`: [`FollowupState`](FollowupState.md); `threadId`: `string`; \\}\n\nPublic status shown on email and in the Reminders editor.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-condition\"></a> `condition` | [`EmailReminderCondition`](EmailReminderCondition.md) | Condition, defaulting to no reply for new follow-ups. |\n| <a id=\"property-linkid\"></a> `linkId` | `string` | Canonical owned/delegated inbox. |\n| <a id=\"property-remindat\"></a> `remindAt` | `string` | Confirmed schedule. |\n| <a id=\"property-reminderid\"></a> `reminderId` | `string` | Identity of the snooze and its delivery records. |\n| <a id=\"property-revision\"></a> `revision` | `string` | Last accepted operation; edits/removal compare this to prevent stale undo. |\n| <a id=\"property-state\"></a> `state` | [`FollowupState`](FollowupState.md) | Durable lifecycle progress. |\n| <a id=\"property-threadid\"></a> `threadId` | `string` | Conversation identity. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailFollowupCommand.md -->\n# Type Alias: EmailFollowupCommand\n\n> **EmailFollowupCommand** = \\{ `condition`: [`EmailReminderCondition`](EmailReminderCondition.md); `expectedRevision?`: `string` \\| `null`; `operationId`: `string`; `remindAt`: `string`; `type`: `\"set\"`; \\} \\| \\{ `expectedRevision`: `string`; `operationId`: `string`; `type`: `\"remove\"`; `undo?`: `boolean`; \\}\n\nIdempotent email command. Reusing an operation ID with different data fails.\n\n## Union Members\n\n### Type Literal\n\n\\{ `condition`: [`EmailReminderCondition`](EmailReminderCondition.md); `expectedRevision?`: `string` \\| `null`; `operationId`: `string`; `remindAt`: `string`; `type`: `\"set\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `condition` | [`EmailReminderCondition`](EmailReminderCondition.md) | Reply condition. |\n| `expectedRevision?` | `string` \\| `null` | None for creation, the current revision for edits. |\n| `operationId` | `string` | Unique request identity retained across network retries. |\n| `remindAt` | `string` | One future instant; conditional recurrence is deliberately absent. |\n| `type` | `\"set\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `expectedRevision`: `string`; `operationId`: `string`; `type`: `\"remove\"`; `undo?`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `expectedRevision` | `string` | Reject removal if a newer edit has replaced this operation. |\n| `operationId` | `string` | Unique request identity. |\n| `type` | `\"remove\"` | - |\n| `undo?` | `boolean` | Undo restores original visibility; ordinary Remove returns to inbox. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailFollowupResponse.md -->\n# Type Alias: EmailFollowupResponse\n\n> **EmailFollowupResponse** = \\{ `followup?`: `null` \\| [`EmailFollowup`](EmailFollowup.md); \\}\n\nLookup response, including an email with no follow-up yet.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-followup\"></a> `followup?` | `null` \\| [`EmailFollowup`](EmailFollowup.md) |\n\n\n<!-- generated/storage/types.gen/type-aliases/EmailReminderCondition.md -->\n# Type Alias: EmailReminderCondition\n\n> **EmailReminderCondition** = `\"if_no_reply\"` \\| `\"regardless\"`\n\nWhen an email follow-up should return the conversation.\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/FollowupState.md -->\n# Type Alias: FollowupState\n\n> **FollowupState** = `\"archiving\"` \\| `\"pending\"` \\| `\"returning\"` \\| `\"returned\"` \\| `\"cancelled\"` \\| `\"removed\"`\n\nDurable progress of an email operation.\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- src/entities/email/attachment/classes/EmailAttachment.md -->\n# Class: EmailAttachment\n\nA file attached to an email message. A thin handle keyed by attachment id;\nthe record loads lazily on first field access.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`EmailAttachmentData`](../type-aliases/EmailAttachmentData.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-contentid\"></a> `contentId` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's Content-ID header value (for inline attachments). | - |\n| <a id=\"property-dataurl\"></a> `dataUrl` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | A URL to the attachment's raw data, when available. | - |\n| <a id=\"property-filename\"></a> `filename` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's original filename. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-mimetype\"></a> `mimeType` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's MIME type. | - |\n| <a id=\"property-sfsid\"></a> `sfsId` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The attachment's static-file-service id, when it has been stored there. | - |\n| <a id=\"property-size\"></a> `size` | `readonly` | () => `Promise`\\<`number` \\| `undefined`\\> | The attachment's size in bytes. | - |\n\n## Methods\n\n### toDocument()\n\n> **toDocument**(): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nThe Macro document holding this attachment's content. Get-or-create: the\nserver returns the existing document's id, or downloads the attachment\nfrom the provider and uploads it as a new document first (deduplicated\nbehind a server-side lock).\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailAttachment`\n\nA handle to an attachment by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailAttachment`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `data`): `EmailAttachment`\n\nBuild an attachment from an already-fetched record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `data` | [`Attachment`](../../../../../generated/email/types.gen/type-aliases/Attachment.md) |\n\n#### Returns\n\n`EmailAttachment`\n\n\n<!-- src/entities/email/attachment/type-aliases/EmailAttachmentData.md -->\n# Type Alias: EmailAttachmentData\n\n> **EmailAttachmentData** = [`GetAttachmentResponses`](../../../../../generated/email/types.gen/type-aliases/GetAttachmentResponses.md)\\[`200`\\]\\[`\"attachment\"`\\]\n\nThe API's representation of an email attachment (`Attachment`).\n\n\n<!-- src/entities/email/draft/classes/DraftAttachment.md -->\n# Class: DraftAttachment\n\nAn uploaded or forwarded attachment belonging to a draft.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-draft\"></a> `draft` | `readonly` | [`EmailDraft`](EmailDraft.md) | Parent draft. |\n| <a id=\"property-forwarded\"></a> `forwarded` | `readonly` | `boolean` | Whether this attachment was forwarded. |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | Attachment identity. |\n\n## Methods\n\n### complete()\n\n> **complete**(): `Promise`\\<`void`\\>\n\nComplete verification after uploading the file.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### remove()\n\n> **remove**(): `Promise`\\<`void`\\>\n\nRemove this attachment from its draft.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `draftId`: `string`; `forwarded`: `boolean`; `id`: `string`; \\}\n\nSerialize identity without credentials.\n\n#### Returns\n\n\\{ `draftId`: `string`; `forwarded`: `boolean`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `draftId` | `string` |\n| `forwarded` | `boolean` |\n| `id` | `string` |\n\n***\n\n### byId()\n\n> `static` **byId**(`_client`, `draft`, `id`, `forwarded?`): `DraftAttachment`\n\nConstruct a draft scoped attachment handle.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `_client` | `MacroClient` | `undefined` |\n| `draft` | [`EmailDraft`](EmailDraft.md) | `undefined` |\n| `id` | `string` | `undefined` |\n| `forwarded?` | `boolean` | `false` |\n\n#### Returns\n\n`DraftAttachment`\n\n\n<!-- src/entities/email/draft/classes/EmailDraft.md -->\n# Class: EmailDraft\n\nA draft email. Sending remains an explicit separate operation.\n\n## Extends\n\n- [`EmailMessage`](../../message/classes/EmailMessage.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Bcc recipients. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`bcc`](../../message/classes/EmailMessage.md#property-bcc) |\n| <a id=\"property-body\"></a> `body` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The parsed message body, as the API returns it. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`body`](../../message/classes/EmailMessage.md#property-body) |\n| <a id=\"property-cc\"></a> `cc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Cc recipients. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`cc`](../../message/classes/EmailMessage.md#property-cc) |\n| <a id=\"property-from\"></a> `from` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md) \\| `undefined`\\> | The sender. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`from`](../../message/classes/EmailMessage.md#property-from) |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`EmailMessage`](../../message/classes/EmailMessage.md).[`id`](../../message/classes/EmailMessage.md#property-id) |\n| <a id=\"property-labels\"></a> `labels` | `readonly` | () => `Promise`\\<[`LabelInfo`](../../../../../generated/email/types.gen/type-aliases/LabelInfo.md)[]\\> | Labels on this message. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`labels`](../../message/classes/EmailMessage.md#property-labels) |\n| <a id=\"property-link\"></a> `link` | `readonly` | () => `Promise`\\<[`Link`](../../link/classes/Link.md)\\> | The inbox (email link) this message belongs to. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`link`](../../message/classes/EmailMessage.md#property-link) |\n| <a id=\"property-sentat\"></a> `sentAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The provider-internal date of the message. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`sentAt`](../../message/classes/EmailMessage.md#property-sentat) |\n| <a id=\"property-subject\"></a> `subject` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The message's subject line. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`subject`](../../message/classes/EmailMessage.md#property-subject) |\n| <a id=\"property-to\"></a> `to` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The To recipients. | [`EmailMessage`](../../message/classes/EmailMessage.md).[`to`](../../message/classes/EmailMessage.md#property-to) |\n\n## Methods\n\n### addAttachment()\n\n> **addAttachment**(`options`): `Promise`\\<\\{ `attachment`: [`DraftAttachment`](DraftAttachment.md); `contentType`: `string`; `uploadUrl`: `string`; \\}\\>\n\nReserve an attachment upload. Upload to the returned URL, then call complete().\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `fileName`: `string`; `sha`: `string`; `size`: `number`; `uploadId?`: `string`; \\} |\n| `options.fileName` | `string` |\n| `options.sha` | `string` |\n| `options.size` | `number` |\n| `options.uploadId?` | `string` |\n\n#### Returns\n\n`Promise`\\<\\{ `attachment`: [`DraftAttachment`](DraftAttachment.md); `contentType`: `string`; `uploadUrl`: `string`; \\}\\>\n\n***\n\n### addLabel()\n\n> **addLabel**(`label`): `Promise`\\<`void`\\>\n\nAdd a label to this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`addLabel`](../../message/classes/EmailMessage.md#addlabel)\n\n***\n\n### completeDraftAttachment()\n\n> **completeDraftAttachment**(`attachmentId`): `Promise`\\<`void`\\>\n\nVerify an uploaded draft attachment before it can be sent.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachmentId` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`completeDraftAttachment`](../../message/classes/EmailMessage.md#completedraftattachment)\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete the draft.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### forwardAttachment()\n\n> **forwardAttachment**(`attachment`): `Promise`\\<[`DraftAttachment`](DraftAttachment.md)\\>\n\nForward an existing attachment into this draft.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachment` | [`EmailAttachment`](../../attachment/classes/EmailAttachment.md) |\n\n#### Returns\n\n`Promise`\\<[`DraftAttachment`](DraftAttachment.md)\\>\n\n***\n\n### operationStatus()\n\n> **operationStatus**(): `Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\nRead the draft's durable send, upload, or conflict status without retrying it.\n\n#### Returns\n\n`Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`operationStatus`](../../message/classes/EmailMessage.md#operationstatus)\n\n***\n\n### removeAttachment()\n\n> **removeAttachment**(`attachment`): `Promise`\\<`void`\\>\n\nRemove a draft attachment.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachment` | [`DraftAttachment`](DraftAttachment.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### removeLabel()\n\n> **removeLabel**(`label`): `Promise`\\<`void`\\>\n\nRemove a label from this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`removeLabel`](../../message/classes/EmailMessage.md#removelabel)\n\n***\n\n### resolveOperation()\n\n> **resolveOperation**(`request`): `Promise`\\<`void`\\>\n\nResolve the displayed operation revision after the user chooses an action.\nRetrying an uncertain send requires explicit duplicate-risk acceptance.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`ResolveMessageOperationRequest`](../../../../../generated/email/types.gen/type-aliases/ResolveMessageOperationRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`resolveOperation`](../../message/classes/EmailMessage.md#resolveoperation)\n\n***\n\n### schedule()\n\n> **schedule**(`sendTime`, `options?`): `Promise`\\<`void`\\>\n\nSchedule this draft for sending.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `sendTime` | `string` |\n| `options?` | \\{ `includeSignature?`: `boolean`; \\} |\n| `options.includeSignature?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### thread()\n\n> **thread**(): `Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe thread this message belongs to.\n\n#### Returns\n\n`Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`thread`](../../message/classes/EmailMessage.md#thread)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`toJSON`](../../message/classes/EmailMessage.md#tojson)\n\n***\n\n### transferDraft()\n\n> **transferDraft**(`request`): `Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\nMove a draft to another inbox using a caller-persisted operation UUID.\nContinue editing the returned message_id; the original identity is retired.\nOn an interrupted response, use email.recoverDraftTransfer(operation_id).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`TransferDraftRequest`](../../../../../generated/email/types.gen/type-aliases/TransferDraftRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`transferDraft`](../../message/classes/EmailMessage.md#transferdraft)\n\n***\n\n### unschedule()\n\n> **unschedule**(): `Promise`\\<`void`\\>\n\nRemove a scheduled send.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`void`\\>\n\nReplace draft content without changing its identity or sending it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../type-aliases/DraftOptions.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### verifyAttachment()\n\n> **verifyAttachment**(`attachment`): `Promise`\\<`void`\\>\n\nComplete verification of an uploaded attachment.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachment` | [`DraftAttachment`](DraftAttachment.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailDraft`\n\nConstruct a lazy draft handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailDraft`\n\n#### Overrides\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`byId`](../../message/classes/EmailMessage.md#byid)\n\n***\n\n### from()\n\n> `static` **from**(`client`, `data`): [`EmailMessage`](../../message/classes/EmailMessage.md)\n\nBuild a message from an already-fetched record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `data` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n\n#### Returns\n\n[`EmailMessage`](../../message/classes/EmailMessage.md)\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`from`](../../message/classes/EmailMessage.md#from)\n\n***\n\n### send()\n\n> `static` **send**(`client`, `opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a new email message. Returns a handle when the API reports the created message's id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | [`SendEmailOptions`](../../message/interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n#### Inherited from\n\n[`EmailMessage`](../../message/classes/EmailMessage.md).[`send`](../../message/classes/EmailMessage.md#send)\n\n\n<!-- src/entities/email/draft/functions/draftBody.md -->\n# Function: draftBody()\n\n> **draftBody**(`options`): [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\n\nTranslate draft content to the generated contract.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../type-aliases/DraftOptions.md) |\n\n## Returns\n\n[`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\n\n\n<!-- src/entities/email/draft/type-aliases/DraftOptions.md -->\n# Type Alias: DraftOptions\n\n> **DraftOptions** = `Omit`\\<[`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md), `\"db_id\"` \\| `\"provider_id\"` \\| `\"provider_thread_id\"` \\| `\"replying_to_id\"` \\| `\"thread_db_id\"` \\| `\"body_text\"` \\| `\"body_html\"` \\| `\"body_macro\"` \\| `\"headers_json\"` \\| `\"include_signature\"`\\> & \\{ `bodyHtml?`: `string`; `bodyMacro?`: `string`; `bodyText?`: `string`; `headers?`: [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\\[`\"headers_json\"`\\]; `includeSignature?`: `boolean`; `replyingTo?`: [`EmailMessage`](../../message/classes/EmailMessage.md); `thread?`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}\n\nDraft content; relationships use message and thread handles.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `bodyHtml?` | `string` | HTML body. |\n| `bodyMacro?` | `string` | Macro body. |\n| `bodyText?` | `string` | Plain text body. |\n| `headers?` | [`ApiDraftInput`](../../../../../generated/email/types.gen/type-aliases/ApiDraftInput.md)\\[`\"headers_json\"`\\] | Extra headers. |\n| `includeSignature?` | `boolean` | Include the inbox signature. |\n| `replyingTo?` | [`EmailMessage`](../../message/classes/EmailMessage.md) | Message being replied to. |\n| `thread?` | [`EmailThread`](../../thread/classes/EmailThread.md) | Thread receiving this draft. |\n\n\n<!-- src/entities/email/filter/classes/EmailFilter.md -->\n# Class: EmailFilter\n\nAn importance filter matched by sender address or domain.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Matched address. | - |\n| <a id=\"property-emaildomain\"></a> `emailDomain` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Matched domain. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isimportant\"></a> `isImportant` | `readonly` | () => `Promise`\\<`boolean`\\> | Importance assigned by this filter. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this filter.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### setImportant()\n\n> **setImportant**(`isImportant`): `Promise`\\<`void`\\>\n\nChange the importance for the same sender selector.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `isImportant` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`, `inbox?`): `EmailFilter`\n\nConstruct a lazy filter handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`EmailFilter`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `record`, `inbox?`): `EmailFilter`\n\nSeed from a server record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `record` | [`ApiEmailFilter`](../../../../../generated/email/types.gen/type-aliases/ApiEmailFilter.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`EmailFilter`\n\n\n<!-- src/entities/email/filter/interfaces/EmailFilterOptions.md -->\n# Interface: EmailFilterOptions\n\nSender importance rule.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress?` | `string` | Match an address. |\n| <a id=\"property-emaildomain\"></a> `emailDomain?` | `string` | Match a domain. |\n| <a id=\"property-isimportant\"></a> `isImportant` | `boolean` | Whether matches are important. |\n\n\n<!-- src/entities/email/label/classes/Label.md -->\n# Class: Label\n\nAn email label. A free-to-construct handle: there is no single-label GET,\nso the detail record loads lazily on first field access by listing all\nlabels and finding this one (mirroring Link).\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the label was created. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-labellistvisibility\"></a> `labelListVisibility` | `readonly` | () => `Promise`\\<[`ApiLabelListVisibility`](../../../../../generated/email/types.gen/type-aliases/ApiLabelListVisibility.md)\\> | Whether the label is shown in the label list. | - |\n| <a id=\"property-linkid\"></a> `linkId` | `readonly` | () => `Promise`\\<`string`\\> | The inbox (email link) this label belongs to. | - |\n| <a id=\"property-messagelistvisibility\"></a> `messageListVisibility` | `readonly` | () => `Promise`\\<[`ApiMessageListVisibility`](../../../../../generated/email/types.gen/type-aliases/ApiMessageListVisibility.md)\\> | Whether the label is shown in the message list. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | The label's display name. | - |\n| <a id=\"property-type\"></a> `type` | `readonly` | () => `Promise`\\<[`ApiLabelType`](../../../../../generated/email/types.gen/type-aliases/ApiLabelType.md)\\> | Whether this is a system label or a user-created one. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this label.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiLabel`](../../../../../generated/email/types.gen/type-aliases/ApiLabel.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Label`\n\nA handle to a label by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Label`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `name`): `Promise`\\<`Label`\\>\n\nCreate a user label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`Label`\\>\n\n***\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`Label`[]\\>\n\nAll labels across the user's inboxes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Label`[]\\>\n\n\n<!-- src/entities/email/link/classes/Link.md -->\n# Class: Link\n\nAn email link: a connected inbox (e.g. Gmail or Outlook) that threads and\nmessages sync through. A free-to-construct handle, resolved from the\ncaller's connected links.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `readonly` | () => `Promise`\\<`string`\\> | The inbox's email address. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isprimary\"></a> `isPrimary` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether this is the user's primary inbox. | - |\n| <a id=\"property-issyncactive\"></a> `isSyncActive` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether syncing is currently active for this inbox. | - |\n| <a id=\"property-needsreauth\"></a> `needsReauth` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the inbox needs to be re-authenticated. | - |\n| <a id=\"property-photourl\"></a> `photoUrl` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The inbox's avatar URL, if any. | - |\n| <a id=\"property-provider\"></a> `provider` | `readonly` | () => `Promise`\\<[`UserProvider`](../../../../../generated/email/types.gen/type-aliases/UserProvider.md)\\> | The email provider (e.g. `GMAIL` or `OUTLOOK`). | - |\n| <a id=\"property-syncstatus\"></a> `syncStatus` | `readonly` | () => `Promise`\\<[`SyncStatus`](../../../../../generated/email/types.gen/type-aliases/SyncStatus.md)\\> | The inbox's sync status. | - |\n\n## Methods\n\n### settingsOperations()\n\n> **settingsOperations**(): `Promise`\\<[`MailboxSettingsOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxSettingsOperation.md)[]\\>\n\nRead category and sender-policy changes for this inbox.\n\n#### Returns\n\n`Promise`\\<[`MailboxSettingsOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxSettingsOperation.md)[]\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Link`](../../../../../generated/email/types.gen/type-aliases/Link.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Link`\n\nA handle to an email link by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Link`\n\n***\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`Link`[]\\>\n\nThe caller's connected email links.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Link`[]\\>\n\n\n<!-- src/entities/email/message/classes/EmailMessage.md -->\n# Class: EmailMessage\n\nA message in an email thread. A thin handle keyed by message id; the\nrecord loads lazily on first field access.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`EmailMessageData`](../type-aliases/EmailMessageData.md)\\>\n\n## Extended by\n\n- [`EmailDraft`](../../draft/classes/EmailDraft.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Bcc recipients. | - |\n| <a id=\"property-body\"></a> `body` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The parsed message body, as the API returns it. | - |\n| <a id=\"property-cc\"></a> `cc` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The Cc recipients. | - |\n| <a id=\"property-from\"></a> `from` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md) \\| `undefined`\\> | The sender. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-labels\"></a> `labels` | `readonly` | () => `Promise`\\<[`LabelInfo`](../../../../../generated/email/types.gen/type-aliases/LabelInfo.md)[]\\> | Labels on this message. | - |\n| <a id=\"property-link\"></a> `link` | `readonly` | () => `Promise`\\<[`Link`](../../link/classes/Link.md)\\> | The inbox (email link) this message belongs to. | - |\n| <a id=\"property-sentat\"></a> `sentAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The provider-internal date of the message. | - |\n| <a id=\"property-subject\"></a> `subject` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The message's subject line. | - |\n| <a id=\"property-to\"></a> `to` | `readonly` | () => `Promise`\\<[`ContactInfo`](../../../../../generated/email/types.gen/type-aliases/ContactInfo.md)[]\\> | The To recipients. | - |\n\n## Methods\n\n### addLabel()\n\n> **addLabel**(`label`): `Promise`\\<`void`\\>\n\nAdd a label to this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### completeDraftAttachment()\n\n> **completeDraftAttachment**(`attachmentId`): `Promise`\\<`void`\\>\n\nVerify an uploaded draft attachment before it can be sent.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `attachmentId` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### operationStatus()\n\n> **operationStatus**(): `Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\nRead the draft's durable send, upload, or conflict status without retrying it.\n\n#### Returns\n\n`Promise`\\<[`MessageOperationResponse`](../../../../../generated/email/types.gen/type-aliases/MessageOperationResponse.md)\\>\n\n***\n\n### removeLabel()\n\n> **removeLabel**(`label`): `Promise`\\<`void`\\>\n\nRemove a label from this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### resolveOperation()\n\n> **resolveOperation**(`request`): `Promise`\\<`void`\\>\n\nResolve the displayed operation revision after the user chooses an action.\nRetrying an uncertain send requires explicit duplicate-risk acceptance.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`ResolveMessageOperationRequest`](../../../../../generated/email/types.gen/type-aliases/ResolveMessageOperationRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### thread()\n\n> **thread**(): `Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe thread this message belongs to.\n\n#### Returns\n\n`Promise`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### transferDraft()\n\n> **transferDraft**(`request`): `Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\nMove a draft to another inbox using a caller-persisted operation UUID.\nContinue editing the returned message_id; the original identity is retired.\nOn an interrupted response, use email.recoverDraftTransfer(operation_id).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`TransferDraftRequest`](../../../../../generated/email/types.gen/type-aliases/TransferDraftRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`TransferDraftResponse`](../../../../../generated/email/types.gen/type-aliases/TransferDraftResponse.md)\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailMessage`\n\nA handle to a message by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailMessage`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `data`): `EmailMessage`\n\nBuild a message from an already-fetched record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `data` | [`ParsedMessage`](../../../../../generated/email/types.gen/type-aliases/ParsedMessage.md) |\n\n#### Returns\n\n`EmailMessage`\n\n***\n\n### send()\n\n> `static` **send**(`client`, `opts`): `Promise`\\<`EmailMessage` \\| `undefined`\\>\n\nSend a new email message. Returns a handle when the API reports the created message's id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | [`SendEmailOptions`](../interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<`EmailMessage` \\| `undefined`\\>\n\n\n<!-- src/entities/email/message/interfaces/SendEmailOptions.md -->\n# Interface: SendEmailOptions\n\nOptions for sending a fresh email message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Bcc recipients. |\n| <a id=\"property-bodytext\"></a> `bodyText` | `string` | Plain-text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Cc recipients. |\n| <a id=\"property-subject\"></a> `subject` | `string` | Subject line. |\n| <a id=\"property-to\"></a> `to` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Recipients. |\n\n\n<!-- src/entities/email/message/type-aliases/EmailMessageData.md -->\n# Type Alias: EmailMessageData\n\n> **EmailMessageData** = [`GetMessageResponses`](../../../../../generated/email/types.gen/type-aliases/GetMessageResponses.md)\\[`200`\\]\n\nThe API's representation of an email message (`ParsedMessage`).\n\n\n<!-- src/entities/email/namespace/classes/EmailNamespace.md -->\n# Class: EmailNamespace\n\n## Constructors\n\n### Constructor\n\n> **new EmailNamespace**(`client`): `EmailNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`EmailNamespace`\n\n## Methods\n\n### attachment()\n\n> **attachment**(`id`): [`EmailAttachment`](../../attachment/classes/EmailAttachment.md)\n\nA handle to an email attachment by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)\n\n***\n\n### blockedSenders()\n\n> **blockedSenders**(): `Promise`\\<`string`[]\\>\n\nThe email addresses currently blocked.\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### blockSender()\n\n> **blockSender**(`email`): `Promise`\\<`void`\\>\n\nBlock an email sender.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `email` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> **byId**(`id`): [`EmailThread`](../../thread/classes/EmailThread.md)\n\nA handle to an email thread by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailThread`](../../thread/classes/EmailThread.md)\n\n***\n\n### connectionProviders()\n\n> **connectionProviders**(): `Promise`\\<[`EmailConnectionProviders`](../../../../../generated/auth/types.gen/type-aliases/EmailConnectionProviders.md)\\>\n\nProviders the server currently permits this caller to connect.\n\n#### Returns\n\n`Promise`\\<[`EmailConnectionProviders`](../../../../../generated/auth/types.gen/type-aliases/EmailConnectionProviders.md)\\>\n\n***\n\n### contacts()\n\n> **contacts**(): `Promise`\\<\\{\\[`key`: `string`\\]: [`ContactInfoWithInteraction`](../../../../../generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md)[]; \\}\\>\n\nAddress book contacts grouped by the service's interaction buckets.\n\n#### Returns\n\n`Promise`\\<\\{\\[`key`: `string`\\]: [`ContactInfoWithInteraction`](../../../../../generated/email/types.gen/type-aliases/ContactInfoWithInteraction.md)[]; \\}\\>\n\n***\n\n### createDraft()\n\n> **createDraft**(`options`, `inbox?`): `Promise`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\nCreate a draft without sending it; the inbox defaults to the caller's primary.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`DraftOptions`](../../draft/type-aliases/DraftOptions.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\n***\n\n### createLabel()\n\n> **createLabel**(`name`): `Promise`\\<[`Label`](../../label/classes/Label.md)\\>\n\nCreate a user label. Returns the created label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Label`](../../label/classes/Label.md)\\>\n\n***\n\n### deleteLabel()\n\n> **deleteLabel**(`label`): `Promise`\\<`void`\\>\n\nDelete a label.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### draftById()\n\n> **draftById**(`id`): [`EmailDraft`](../../draft/classes/EmailDraft.md)\n\nConstruct a lazy draft handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailDraft`](../../draft/classes/EmailDraft.md)\n\n***\n\n### filters()\n\n> **filters**(`inbox?`): `Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)[]\\>\n\nImportance filters.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)[]\\>\n\n***\n\n### inbox()\n\n> **inbox**(`opts?`): `AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nThe threads in the inbox, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`InboxOptions`](../interfaces/InboxOptions.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### label()\n\n> **label**(`id`): [`Label`](../../label/classes/Label.md)\n\nA handle to a label by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Label`](../../label/classes/Label.md)\n\n***\n\n### labels()\n\n> **labels**(): `Promise`\\<[`Label`](../../label/classes/Label.md)[]\\>\n\nAll labels across the user's inboxes.\n\n#### Returns\n\n`Promise`\\<[`Label`](../../label/classes/Label.md)[]\\>\n\n***\n\n### link()\n\n> **link**(`id`): [`Link`](../../link/classes/Link.md)\n\nA handle to a connected inbox (email link) by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Link`](../../link/classes/Link.md)\n\n***\n\n### links()\n\n> **links**(): `Promise`\\<[`Link`](../../link/classes/Link.md)[]\\>\n\nThe caller's connected inboxes (email links).\n\n#### Returns\n\n`Promise`\\<[`Link`](../../link/classes/Link.md)[]\\>\n\n***\n\n### message()\n\n> **message**(`id`): [`EmailMessage`](../../message/classes/EmailMessage.md)\n\nA handle to an email message by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`EmailMessage`](../../message/classes/EmailMessage.md)\n\n***\n\n### recoverDraftTransfer()\n\n> **recoverDraftTransfer**(`operationId`): `Promise`\\<[`TransferRecoveryResponse`](../../../../../generated/email/types.gen/type-aliases/TransferRecoveryResponse.md)\\>\n\nRecover a draft move using its original operation UUID; never starts a new move.\nAn empty committed result fences the old move so it cannot commit later.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `operationId` | `string` |\n\n#### Returns\n\n`Promise`\\<[`TransferRecoveryResponse`](../../../../../generated/email/types.gen/type-aliases/TransferRecoveryResponse.md)\\>\n\n***\n\n### reminders()\n\n> **reminders**(`options?`): `AsyncGenerator`\\<\\{ `followup`: [`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md); `thread`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}, `any`, `any`\\>\n\nFollow-up reminders with thread handles, automatically paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | `Omit`\\<\\{ `attachments?`: `string`[] \\| `null`; `calendar?`: `boolean` \\| `null`; `cursor?`: `string` \\| `null`; `done?`: `boolean` \\| `null`; `inboxIds?`: `string`[] \\| `null`; `limit?`: `number` \\| `null`; `noInboxes?`: `boolean` \\| `null`; `read?`: `boolean` \\| `null`; `tags?`: `string`[] \\| `null`; \\}, `\"cursor\"` \\| `\"inboxIds\"`\\> & \\{ `inboxes?`: [`Link`](../../link/classes/Link.md)[]; \\} |\n\n#### Returns\n\n`AsyncGenerator`\\<\\{ `followup`: [`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md); `thread`: [`EmailThread`](../../thread/classes/EmailThread.md); \\}, `any`, `any`\\>\n\n***\n\n### scheduled()\n\n> **scheduled**(`options?`): `AsyncGenerator`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\nScheduled drafts, fetched lazily in bounded pages.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `inbox?`: [`Link`](../../link/classes/Link.md); `pageSize?`: `number`; \\} |\n| `options.inbox?` | [`Link`](../../link/classes/Link.md) |\n| `options.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailDraft`](../../draft/classes/EmailDraft.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\nSearch email threads by subject and content.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`EmailThread`](../../thread/classes/EmailThread.md)\\>\n\n***\n\n### send()\n\n> **send**(`opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a new email message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | [`SendEmailOptions`](../../message/interfaces/SendEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n***\n\n### unblockSender()\n\n> **unblockSender**(`email`): `Promise`\\<`void`\\>\n\nUnblock a previously blocked sender.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `email` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### upsertFilter()\n\n> **upsertFilter**(`options`, `inbox?`): `Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)\\>\n\nCreate or replace a filter matching an address or domain.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`EmailFilterOptions`](../../filter/interfaces/EmailFilterOptions.md) |\n| `inbox?` | [`Link`](../../link/classes/Link.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFilter`](../../filter/classes/EmailFilter.md)\\>\n\n\n<!-- src/entities/email/namespace/interfaces/InboxOptions.md -->\n# Interface: InboxOptions\n\nOptions for listing inbox threads.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-pagesize\"></a> `pageSize?` | `number` | Page size (default 20, max 500). |\n| <a id=\"property-sort\"></a> `sort?` | [`ApiSortMethod`](../../../../../generated/email/types.gen/type-aliases/ApiSortMethod.md) | Sort order. Defaults to `viewed_updated`. |\n\n\n<!-- src/entities/email/thread/classes/EmailThread.md -->\n# Class: EmailThread\n\nAn email thread. A free-to-construct handle: the detail record (including\nup to the first 100 messages) loads lazily on first field access.\n\n## Extends\n\n- [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md)\\<`ThreadDetail`\\>\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | - |\n| <a id=\"property-accesslevel\"></a> `accessLevel` | `readonly` | () => `Promise`\\<[`AccessLevel`](../../../../../generated/email/types.gen/type-aliases/AccessLevel.md)\\> | `...` | The viewer's access level to this thread. | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | `...` | When the thread was created. | - | - |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"email_thread\"` | `'email_thread'` | Favorites identify email threads as `email_thread`. | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`entityType`](../../../entity/classes/PropertiedEntity.md#property-entitytype) | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`id`](../../../entity/classes/PropertiedEntity.md#property-id) |\n| <a id=\"property-inboxvisible\"></a> `inboxVisible` | `readonly` | () => `Promise`\\<`boolean`\\> | `...` | Whether the thread is visible in the inbox (i.e. not archived). | - | - |\n| <a id=\"property-isread\"></a> `isRead` | `readonly` | () => `Promise`\\<`boolean`\\> | `...` | Whether the thread has been read. | - | - |\n| <a id=\"property-latestinboundat\"></a> `latestInboundAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | Timestamp of the latest inbound message, if any. | - | - |\n| <a id=\"property-latestnonspamat\"></a> `latestNonSpamAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | Timestamp of the latest non-spam message, if any. | - | - |\n| <a id=\"property-latestoutboundat\"></a> `latestOutboundAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | Timestamp of the latest outbound message, if any. | - | - |\n| <a id=\"property-link\"></a> `link` | `readonly` | () => `Promise`\\<[`Link`](../../link/classes/Link.md)\\> | `...` | The inbox (email link) that owns this thread. | - | - |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this thread is attached to, if any. | - | - |\n| <a id=\"property-providerid\"></a> `providerId` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The provider-internal thread id (e.g. Gmail/Outlook), if any. | - | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string`\\> | `...` | When the thread was last updated. | - | - |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`EmailThread`\\> | `...` | Search email threads by subject and content, most relevant first, auto-paginated. | - | - |\n\n## Methods\n\n### addLabel()\n\n> **addLabel**(`label`): `Promise`\\<`void`\\>\n\nAdd a label to every message in the thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### archive()\n\n> **archive**(`archived?`): `Promise`\\<`void`\\>\n\nArchive the thread (or unarchive with `false`).\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `archived?` | `boolean` | `true` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### attachments()\n\n> **attachments**(): `Promise`\\<[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)[]\\>\n\nThe attachments across this thread's first 100 messages, pre-seeded from the thread detail.\n\n#### Returns\n\n`Promise`\\<[`EmailAttachment`](../../attachment/classes/EmailAttachment.md)[]\\>\n\n***\n\n### calendarInvitations()\n\n> **calendarInvitations**(): `Promise`\\<\\{\\[`key`: `string`\\]: [`InvitationResolution`](../../../../../generated/email/types.gen/type-aliases/InvitationResolution.md); \\}\\>\n\nCalendar invitations resolved from this thread's messages.\n\n#### Returns\n\n`Promise`\\<\\{\\[`key`: `string`\\]: [`InvitationResolution`](../../../../../generated/email/types.gen/type-aliases/InvitationResolution.md); \\}\\>\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`deleteProperty`](../../../entity/classes/PropertiedEntity.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`EmailThread`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`EmailThread`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`favorite`](../../../entity/classes/PropertiedEntity.md#favorite)\n\n***\n\n### followup()\n\n> **followup**(): `Promise`\\<[`EmailFollowupResponse`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowupResponse.md)\\>\n\nRead follow-up state for this thread.\n\n#### Returns\n\n`Promise`\\<[`EmailFollowupResponse`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowupResponse.md)\\>\n\n***\n\n### markSeen()\n\n> **markSeen**(): `Promise`\\<`void`\\>\n\nMark the thread as seen.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### messages()\n\n> **messages**(`opts?`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md)[]\\>\n\nThe messages in this thread, pre-seeded from the list endpoint.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `limit?`: `number`; `since?`: `string`; \\} |\n| `opts.limit?` | `number` |\n| `opts.since?` | `string` |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md)[]\\>\n\n***\n\n### moveToProject()\n\n> **moveToProject**(`project`): `Promise`\\<`void`\\>\n\nAttach the thread to a project, or clear the project with `null`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `project` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### operations()\n\n> **operations**(): `Promise`\\<[`MailboxOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxOperation.md)[]\\>\n\nRead pending or failed mailbox changes without initiating a retry.\n\n#### Returns\n\n`Promise`\\<[`MailboxOperation`](../../../../../generated/email/types.gen/type-aliases/MailboxOperation.md)[]\\>\n\n***\n\n### participants()\n\n> **participants**(): `Promise`\\<[`ApiContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiContactInfo.md)[]\\>\n\nEveryone on the thread (senders and recipients), deduped by email.\nDerived from the thread's first 100 messages.\n\n#### Returns\n\n`Promise`\\<[`ApiContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiContactInfo.md)[]\\>\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`permission`](../../../entity/classes/PropertiedEntity.md#permission)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`properties`](../../../entity/classes/PropertiedEntity.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`propertyReference`](../../../entity/classes/PropertiedEntity.md#propertyreference)\n\n***\n\n### removeLabel()\n\n> **removeLabel**(`label`): `Promise`\\<`void`\\>\n\nRemove a label from every message in the thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`Label`](../../label/classes/Label.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### reply()\n\n> **reply**(`opts`): `Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\nSend a reply within this thread. Returns a handle when the API reports the created message's id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | [`ReplyEmailOptions`](../interfaces/ReplyEmailOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailMessage`](../../message/classes/EmailMessage.md) \\| `undefined`\\>\n\n***\n\n### setFollowup()\n\n> **setFollowup**(`command`): `Promise`\\<[`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md)\\>\n\nSet or remove a follow-up using a persisted operation id and revision.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `command` | [`EmailFollowupCommand`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowupCommand.md) |\n\n#### Returns\n\n`Promise`\\<[`EmailFollowup`](../../../../../generated/storage/types.gen/type-aliases/EmailFollowup.md)\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`setProperty`](../../../entity/classes/PropertiedEntity.md#setproperty)\n\n***\n\n### subject()\n\n> **subject**(): `Promise`\\<`string` \\| `undefined`\\>\n\nThe thread's subject, from its first message with one.\n\n#### Returns\n\n`Promise`\\<`string` \\| `undefined`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiThread`](../../../../../generated/email/types.gen/type-aliases/ApiThread.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiThread`](../../../../../generated/email/types.gen/type-aliases/ApiThread.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiThread`](../../../../../generated/email/types.gen/type-aliases/ApiThread.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`toJSON`](../../../entity/classes/PropertiedEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`EmailThread`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`EmailThread`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`unfavorite`](../../../entity/classes/PropertiedEntity.md#unfavorite)\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`void`\\>\n\nChange project membership or share permissions for this thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `project?`: [`Project`](../../../projects/project/classes/Project.md) \\| `null`; `sharePermission?`: [`SharePermissionOptions`](../../../sharing/permissions/type-aliases/SharePermissionOptions.md); \\} |\n| `options.project?` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n| `options.sharePermission?` | [`SharePermissionOptions`](../../../sharing/permissions/type-aliases/SharePermissionOptions.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`updatePropertyOptions`](../../../entity/classes/PropertiedEntity.md#updatepropertyoptions)\n\n***\n\n### updateState()\n\n> **updateState**(`request`): `Promise`\\<`void`\\>\n\nUpdate provider-neutral read, trash, spam, or star state.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`UpdateThreadStateRequest`](../../../../../generated/email/types.gen/type-aliases/UpdateThreadStateRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `EmailThread`\n\nA handle to a thread by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`EmailThread`\n\n\n<!-- src/entities/email/thread/interfaces/ReplyEmailOptions.md -->\n# Interface: ReplyEmailOptions\n\nOptions for replying within an email thread.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Bcc recipients. |\n| <a id=\"property-bodytext\"></a> `bodyText` | `string` | Plain-text body. |\n| <a id=\"property-cc\"></a> `cc?` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Cc recipients. |\n| <a id=\"property-replyingto\"></a> `replyingTo?` | [`EmailMessage`](../../message/classes/EmailMessage.md) | The message being replied to. |\n| <a id=\"property-subject\"></a> `subject?` | `string` | Subject line. Defaults to the subject of the thread's first message. |\n| <a id=\"property-to\"></a> `to` | [`ApiDraftContactInfo`](../../../../../generated/email/types.gen/type-aliases/ApiDraftContactInfo.md)[] | Recipients. |\n"
},
{
"name": "favorites",
diff --git a/crates/fusionauth/src/microsoft.rs b/crates/fusionauth/src/microsoft.rs
index 96e7cf9128..0af0bad682 100644
--- a/crates/fusionauth/src/microsoft.rs
+++ b/crates/fusionauth/src/microsoft.rs
@@ -92,10 +92,7 @@ impl FusionAuthClient {
url.query_pairs_mut()
.clear()
.extend_pairs(pairs)
- .append_pair(
- "scope",
- &format!("{} Calendars.ReadWrite", oauth::MICROSOFT_SCOPES),
- );
+ .append_pair("scope", &oauth::consent_scopes(true));
}
url.query_pairs_mut()
.append_pair("code_challenge", challenge)
@@ -104,6 +101,27 @@ impl FusionAuthClient {
Ok(url.into())
}
+ /// Constructs the tenant-wide admin-consent URL an administrator completes
+ /// when their directory does not let users consent to Macro themselves.
+ ///
+ /// `state` is opaque and is only URL-encoded, never JSON-serialized.
+ pub fn construct_microsoft_admin_consent_url(
+ &self,
+ redirect_uri: &str,
+ state: &str,
+ calendar: bool,
+ ) -> Result<String> {
+ let credentials = self.microsoft_credentials()?;
+ oauth::construct_admin_consent_url(
+ &credentials.client_id,
+ &credentials.tenant_id,
+ redirect_uri,
+ state,
+ calendar,
+ )
+ .map_err(FusionAuthClientError::from)
+ }
+
/// Exchanges a Microsoft authorization code for a refresh token and ID token.
#[tracing::instrument(skip(self, code, redirect_uri), err)]
pub async fn exchange_microsoft_code_for_tokens(
diff --git a/crates/fusionauth/src/microsoft/oauth.rs b/crates/fusionauth/src/microsoft/oauth.rs
index d42aff37d7..f9ecb71361 100644
--- a/crates/fusionauth/src/microsoft/oauth.rs
+++ b/crates/fusionauth/src/microsoft/oauth.rs
@@ -13,6 +13,15 @@ pub(crate) const MICROSOFT_LOGIN_BASE_URL: &str = "https://login.microsoftonline
/// Mail and address-book consent. Calendar access is requested only by calendar entry points.
pub const MICROSOFT_SCOPES: &str = "openid email offline_access profile User.Read Mail.ReadWrite Mail.Send MailboxSettings.ReadWrite Contacts.Read";
+/// The delegated scopes a consent request asks for.
+pub(crate) fn consent_scopes(calendar: bool) -> String {
+ if calendar {
+ format!("{MICROSOFT_SCOPES} Calendars.ReadWrite")
+ } else {
+ MICROSOFT_SCOPES.to_owned()
+ }
+}
+
#[derive(serde::Serialize)]
struct MicrosoftTokenExchangeRequest<'a> {
client_id: &'a str,
@@ -117,6 +126,39 @@ pub(crate) fn construct_authorize_url(
Ok(url.to_string())
}
+/// The tenant-wide admin-consent page for `tenant_id`.
+///
+/// Admin consent is a directory operation, so the `common` audience is not
+/// accepted there: a multi-tenant app asks `organizations` and lets the
+/// administrator pick their directory. A fixed tenant or `organizations` is
+/// used as configured. On success Microsoft returns to `redirect_uri` with
+/// `admin_consent=True&tenant={id}&state={state}`.
+pub(crate) fn construct_admin_consent_url(
+ client_id: &str,
+ tenant_id: &str,
+ redirect_uri: &str,
+ state: &str,
+ calendar: bool,
+) -> anyhow::Result<String> {
+ let tenant = match tenant_id {
+ "common" | "consumers" => "organizations",
+ tenant => tenant,
+ };
+ let mut url =
+ Url::parse(MICROSOFT_LOGIN_BASE_URL).context("invalid Microsoft OAuth base URL")?;
+ url.path_segments_mut()
+ .expect("Microsoft OAuth base URL must support path segments")
+ .pop_if_empty()
+ .extend([tenant, "v2.0", "adminconsent"]);
+ url.query_pairs_mut()
+ .append_pair("client_id", client_id)
+ .append_pair("redirect_uri", redirect_uri)
+ .append_pair("scope", &consent_scopes(calendar))
+ .append_pair("state", state);
+
+ Ok(url.to_string())
+}
+
pub(crate) async fn exchange_code_for_tokens(
_client: &UnauthedClient,
client_id: &str,
diff --git a/crates/fusionauth/src/microsoft/test.rs b/crates/fusionauth/src/microsoft/test.rs
index 41568e7f9b..11cff3df60 100644
--- a/crates/fusionauth/src/microsoft/test.rs
+++ b/crates/fusionauth/src/microsoft/test.rs
@@ -505,6 +505,74 @@ fn calendar_consent_is_opt_in_and_contacts_are_read_only() {
}
}
+#[test]
+fn admin_consent_url_targets_organizations_for_multi_tenant_apps() {
+ let state = "eyJraW5kIjoiYWRtaW5fY29uc2VudCJ9.c2ln+/=&?%20";
+ for (configured, expected_tenant) in [
+ ("common", "organizations"),
+ ("consumers", "organizations"),
+ ("organizations", "organizations"),
+ (
+ "cfc674f9-d10b-4b48-a2be-d018a76a6c27",
+ "cfc674f9-d10b-4b48-a2be-d018a76a6c27",
+ ),
+ ] {
+ let url = client()
+ .with_microsoft_credentials(
+ "microsoft-client-id".into(),
+ "microsoft-client-secret".into(),
+ configured.into(),
+ )
+ .construct_microsoft_admin_consent_url(
+ "https://auth.example.com/oauth2/microsoft/callback",
+ state,
+ false,
+ )
+ .unwrap();
+ let url = reqwest::Url::parse(&url).unwrap();
+ assert_eq!(
+ url.path(),
+ format!("/{expected_tenant}/v2.0/adminconsent"),
+ "{configured} should ask {expected_tenant}"
+ );
+ let values: HashMap<_, _> = url.query_pairs().into_owned().collect();
+ assert_eq!(url.query_pairs().count(), values.len());
+ assert_eq!(values["client_id"], "microsoft-client-id");
+ assert_eq!(
+ values["redirect_uri"],
+ "https://auth.example.com/oauth2/microsoft/callback"
+ );
+ assert_eq!(values["state"], state);
+ assert_eq!(values["scope"], oauth::MICROSOFT_SCOPES);
+ assert!(!url.as_str().contains("microsoft-client-secret"));
+ }
+}
+
+#[test]
+fn admin_consent_requests_calendar_only_when_the_deployment_offers_it() {
+ for calendar in [false, true] {
+ let url = microsoft_client()
+ .construct_microsoft_admin_consent_url(
+ "https://auth.example.com/callback",
+ "state",
+ calendar,
+ )
+ .unwrap();
+ let url = reqwest::Url::parse(&url).unwrap();
+ let values: HashMap<_, _> = url.query_pairs().into_owned().collect();
+ assert_eq!(
+ values["scope"]
+ .split_whitespace()
+ .any(|scope| scope == "Calendars.ReadWrite"),
+ calendar
+ );
+ }
+ assert!(matches!(
+ client().construct_microsoft_admin_consent_url("https://auth.example.com", "state", false),
+ Err(FusionAuthClientError::MicrosoftOAuthNotConfigured)
+ ));
+}
+
#[test]
fn id_token_without_email_is_usable_for_verified_graph_identity() {
let mut claims = valid_claims();
diff --git a/docs/agent-guide/email.md b/docs/agent-guide/email.md
index 6d6d158e58..e93a1a40a6 100644
--- a/docs/agent-guide/email.md
+++ b/docs/agent-guide/email.md
@@ -39,6 +39,14 @@ same thread, search, Signal/Noise, draft, and schedule surfaces apply to both
providers. Shared/delegated Microsoft mailboxes are outside this account scope;
sharing an inbox or thread inside Macro remains available.
+A Microsoft 365 tenant that lets only administrators consent sends the user
+back to an `Admin approval required` dialog with `Copy admin approval link`
+(a tenant-wide approval link for IT) and `Connect a different account`.
+Cancelling on the provider's consent screen returns to the previous view
+silently. An administrator who opens the approval link returns to
+`Approved. Try connecting again.` with the connect dialog open. On native
+mobile the approval dialog is not shown; connect from the web app instead.
+
For Outlook writes, distinguish acceptance from provider confirmation. Thread
organization notices and inbox settings show pending or failed changes; the
mark-as-read from opening a thread is announced only if it fails. Draft sync and
diff --git a/docs/design/outlook-email-support.md b/docs/design/outlook-email-support.md
index 9676eef89e..9d076c83ce 100644
--- a/docs/design/outlook-email-support.md
+++ b/docs/design/outlook-email-support.md
@@ -346,6 +346,17 @@ requires the relevant consent, but its absence must not destroy mail access.
Verify personal and cross-tenant Microsoft 365 linking, canonical identity,
revocation, and reconnect on real accounts before enabling connections.
+Tenants that restrict user consent answer the authorize request with
+`AADSTS65001` (sometimes `consent_required` or `interaction_required`) and no
+code. The callback classifies the failure and sends the user back to the
+inbox-link page with `email_link_error=admin_consent_required`; the app offers
+the tenant-wide approval link, built by `GET /link/email/providers` from the
+`/organizations/v2.0/adminconsent` endpoint with a signed, non-expiring state,
+so the client never carries the Microsoft client id. The administrator's
+return (`admin_consent=True`) redirects with
+`email_link_notice=admin_consent_granted`. A plain `access_denied` is a cancel
+and returns silently. Only the `AADSTS` code is logged.
+
**7. Drafts and delivery: preserve edits and model uncertainty.**
Use Macro as the authoritative store for active draft edits, with revision checks
diff --git a/packages/sdk-docs/reference/generated/auth/types.gen/README.md b/packages/sdk-docs/reference/generated/auth/types.gen/README.md
index df35e6daa2..70a317d1df 100644
--- a/packages/sdk-docs/reference/generated/auth/types.gen/README.md
+++ b/packages/sdk-docs/reference/generated/auth/types.gen/README.md
@@ -121,6 +121,8 @@
- [DisconnectCodexResponses](type-aliases/DisconnectCodexResponses.md)
- [EmailConnectionProviders](type-aliases/EmailConnectionProviders.md)
- [EmailConnectionProvidersData](type-aliases/EmailConnectionProvidersData.md)
+- [EmailConnectionProvidersError](type-aliases/EmailConnectionProvidersError.md)
+- [EmailConnectionProvidersErrors](type-aliases/EmailConnectionProvidersErrors.md)
- [EmailConnectionProvidersResponse](type-aliases/EmailConnectionProvidersResponse.md)
- [EmailConnectionProvidersResponses](type-aliases/EmailConnectionProvidersResponses.md)
- [EmptyResponse](type-aliases/EmptyResponse.md)
diff --git a/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProviders.md b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProviders.md
index 69fa657771..d999de5b6b 100644
--- a/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProviders.md
+++ b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProviders.md
@@ -1,12 +1,13 @@
# Type Alias: EmailConnectionProviders
-> **EmailConnectionProviders** = \{ `gmail`: `boolean`; `outlook`: `boolean`; \}
+> **EmailConnectionProviders** = \{ `gmail`: `boolean`; `outlook`: `boolean`; `outlook_admin_consent_url?`: `string` \| `null`; \}
Actual deployment availability for the provider selector.
## Properties
-| Property | Type |
-| ------ | ------ |
-| <a id="property-gmail"></a> `gmail` | `boolean` |
-| <a id="property-outlook"></a> `outlook` | `boolean` |
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="property-gmail"></a> `gmail` | `boolean` | - |
+| <a id="property-outlook"></a> `outlook` | `boolean` | - |
+| <a id="property-outlook_admin_consent_url"></a> `outlook_admin_consent_url?` | `string` \| `null` | Where a Microsoft 365 administrator approves Macro for their whole directory. Present when Outlook is configured and the request named an `original_url` for the administrator's browser to return to. |
diff --git a/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersData.md b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersData.md
index eb5483aeef..3432ac1225 100644
--- a/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersData.md
+++ b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersData.md
@@ -1,12 +1,13 @@
# Type Alias: EmailConnectionProvidersData
-> **EmailConnectionProvidersData** = \{ `body?`: `never`; `path?`: `never`; `query?`: `never`; `url`: `"/link/email/providers"`; \}
+> **EmailConnectionProvidersData** = \{ `body?`: `never`; `path?`: `never`; `query?`: \{ `original_url?`: `string`; \}; `url`: `"/link/email/providers"`; \}
## Properties
-| Property | Type |
-| ------ | ------ |
-| <a id="property-body"></a> `body?` | `never` |
-| <a id="property-path"></a> `path?` | `never` |
-| <a id="property-query"></a> `query?` | `never` |
-| <a id="property-url"></a> `url` | `"/link/email/providers"` |
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="property-body"></a> `body?` | `never` | - |
+| <a id="property-path"></a> `path?` | `never` | - |
+| <a id="property-query"></a> `query?` | \{ `original_url?`: `string`; \} | - |
+| `query.original_url?` | `string` | **OPTIONAL**. Where the admin-consent flow returns to; required for `outlook_admin_consent_url`. |
+| <a id="property-url"></a> `url` | `"/link/email/providers"` | - |
diff --git a/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersError.md b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersError.md
new file mode 100644
index 0000000000..59abdc9de5
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersError.md
@@ -0,0 +1,3 @@
+# Type Alias: EmailConnectionProvidersError
+
+> **EmailConnectionProvidersError** = [`EmailConnectionProvidersErrors`](EmailConnectionProvidersErrors.md)\[keyof [`EmailConnectionProvidersErrors`](EmailConnectionProvidersErrors.md)\]
diff --git a/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersErrors.md b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersErrors.md
new file mode 100644
index 0000000000..01967521a6
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/auth/types.gen/type-aliases/EmailConnectionProvidersErrors.md
@@ -0,0 +1,9 @@
+# Type Alias: EmailConnectionProvidersErrors
+
+> **EmailConnectionProvidersErrors** = \{ `400`: [`ErrorResponse`](ErrorResponse.md); \}
+
+## Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="property-400"></a> `400` | [`ErrorResponse`](ErrorResponse.md) |
diff --git a/packages/sdk/generated/auth/index.ts b/packages/sdk/generated/auth/index.ts
index 27162490bc..6b7dd1ea0a 100644
--- a/packages/sdk/generated/auth/index.ts
+++ b/packages/sdk/generated/auth/index.ts
@@ -1,4 +1,4 @@
// This file is auto-generated by @hey-api/openapi-ts
export { type Options, Sdk } from './sdk.gen';
-export type { AbGroup, AiBillingErrorBody, AppleLoginData, AppleLoginError, AppleLoginErrors, AppleLoginRequest, AppleLoginResponse, AppleLoginResponses, AutoReloadDefaults, AutoReloadMonthlyBudget, AutoReloadSnapshot, CancelCodexLoginData, CancelCodexLoginResponse, CancelCodexLoginResponses, ChangePlanData, ChangePlanError, ChangePlanErrors, ChangePlanRequest, ChangePlanResponse, ChangePlanResponse2, ChangePlanResponses, CheckGithubLinkStatusData, CheckGithubLinkStatusError, CheckGithubLinkStatusErrors, CheckGithubLinkStatusResponse, CheckGithubLinkStatusResponses, CheckGmailLinkStatusData, CheckGmailLinkStatusError, CheckGmailLinkStatusErrors, CheckGmailLinkStatusResponse, CheckGmailLinkStatusResponses, CheckoutSessionMetadata, CheckoutSessionV2Response, ClientOptions, CodexConfigRequest, CodexConnectionStatus, CodexEnvironment, CodexEnvironmentRepository, CodexLoginPoll, CodexLoginStart, CodexLoginState, ConfigureCodexData, ConfigureCodexResponse, ConfigureCodexResponses, CreateAccountMergeRequest, CreateAiCreditCheckoutData, CreateAiCreditCheckoutError, CreateAiCreditCheckoutErrors, CreateAiCreditCheckoutResponse, CreateAiCreditCheckoutResponses, CreateCheckoutSessionV2Data, CreateCheckoutSessionV2Error, CreateCheckoutSessionV2Errors, CreateCheckoutSessionV2Request, CreateCheckoutSessionV2Response, CreateCheckoutSessionV2Responses, CreateGtmInviteLinkData, CreateGtmInviteLinkError, CreateGtmInviteLinkErrors, CreateGtmInviteLinkRequest, CreateGtmInviteLinkResponse, CreateGtmInviteLinkResponses, CreateInProgressLinkData, CreateInProgressLinkError, CreateInProgressLinkErrors, CreateInProgressLinkResponse, CreateInProgressLinkResponse2, CreateInProgressLinkResponses, CreateMergeRequestData, CreateMergeRequestError, CreateMergeRequestErrors, CreateMergeRequestResponse, CreateMergeRequestResponses, CreatePortalSessionData, CreatePortalSessionError, CreatePortalSessionErrors, CreatePortalSessionRequest, CreatePortalSessionResponse, CreatePortalSessionResponses, CreateTeamData, CreateTeamError, CreateTeamErrors, CreateTeamRequest, CreateTeamResponse, CreateTeamResponses, CreditCheckoutRequestBody, CreditCheckoutResponse, CursorApiKeyStatus, CursorModelOption, CursorModelsResponse, DeleteCursorApiKeyData, DeleteCursorApiKeyError, DeleteCursorApiKeyErrors, DeleteCursorApiKeyResponse, DeleteCursorApiKeyResponses, DeleteGithubLinkData, DeleteGithubLinkError, DeleteGithubLinkErrors, DeleteGithubLinkResponse, DeleteGithubLinkResponses, DeleteTeamData, DeleteTeamError, DeleteTeamErrors, DeleteTeamInviteHandlerData, DeleteTeamInviteHandlerError, DeleteTeamInviteHandlerErrors, DeleteTeamInviteHandlerResponses, DeleteTeamResponses, DeleteUserData, DeleteUserError, DeleteUserErrors, DeleteUserResponse, DeleteUserResponses, DenyReason, DisconnectCodexData, DisconnectCodexResponse, DisconnectCodexResponses, EmailConnectionProviders, EmailConnectionProvidersData, EmailConnectionProvidersResponse, EmailConnectionProvidersResponses, EmptyResponse, EnrichedGithubPullRequest, EnrichGithubPullRequestsData, EnrichGithubPullRequestsError, EnrichGithubPullRequestsErrors, EnrichGithubPullRequestsProxyRequest, EnrichGithubPullRequestsResponse, EnrichGithubPullRequestsResponse2, EnrichGithubPullRequestsResponses, ErrorResponse, GenerateEmailLinkData, GenerateEmailLinkError, GenerateEmailLinkErrors, GenerateEmailLinkRequest, GenerateEmailLinkResponse, GenerateEmailLinkResponses, GenericSuccessResponse, GetAiBillingPlansData, GetAiBillingPlansResponse, GetAiBillingPlansResponses, GetAiBillingSummaryData, GetAiBillingSummaryError, GetAiBillingSummaryErrors, GetAiBillingSummaryResponse, GetAiBillingSummaryResponses, GetCodexConnectionData, GetCodexConnectionResponse, GetCodexConnectionResponses, GetCursorApiKeyData, GetCursorApiKeyError, GetCursorApiKeyErrors, GetCursorApiKeyResponse, GetCursorApiKeyResponses, GetGithubPullRequestMergeabilityData, GetGithubPullRequestMergeabilityError, GetGithubPullRequestMergeabilityErrors, GetGithubPullRequestMergeabilityResponse, GetGithubPullRequestMergeabilityResponses, GetGtmInviteOfferData, GetGtmInviteOfferError, GetGtmInviteOfferErrors, GetGtmInviteOfferResponse, GetGtmInviteOfferResponses, GetLegacyUserPermissionsData, GetLegacyUserPermissionsError, GetLegacyUserPermissionsErrors, GetLegacyUserPermissionsResponse, GetLegacyUserPermissionsResponse2, GetLegacyUserPermissionsResponses, GetNamesWithEmailRequestBody, GetPermissionsData, GetPermissionsError, GetPermissionsErrors, GetPermissionsResponse, GetPermissionsResponses, GetProfilePicturesRequestBody, GetReferralCodeData, GetReferralCodeError, GetReferralCodeErrors, GetReferralCodeResponse, GetReferralCodeResponses, GetSubscriptionStatusData, GetSubscriptionStatusError, GetSubscriptionStatusErrors, GetSubscriptionStatusResponse, GetSubscriptionStatusResponses, GetTeamData, GetTeamError, GetTeamErrors, GetTeamInvitesData, GetTeamInvitesError, GetTeamInvitesErrors, GetTeamInvitesResponse, GetTeamInvitesResponses, GetTeamResponse, GetTeamResponses, GetTrialEligibilityData, GetTrialEligibilityError, GetTrialEligibilityErrors, GetTrialEligibilityResponse, GetTrialEligibilityResponses, GetUserInfo, GetUserInfoData, GetUserInfoError, GetUserInfoErrors, GetUserInfoResponse, GetUserInfoResponses, GetUserInvitesData, GetUserInvitesError, GetUserInvitesErrors, GetUserInvitesResponse, GetUserInvitesResponses, GetUserLinkExistsData, GetUserLinkExistsError, GetUserLinkExistsErrors, GetUserLinkExistsResponse, GetUserLinkExistsResponses, GetUserNameData, GetUserNameError, GetUserNameErrors, GetUserNameResponse, GetUserNameResponses, GetUserNamesData, GetUserNamesError, GetUserNamesErrors, GetUserNamesResponse, GetUserNamesResponses, GetUserNamesWithEmailData, GetUserNamesWithEmailError, GetUserNamesWithEmailErrors, GetUserNamesWithEmailResponse, GetUserNamesWithEmailResponses, GetUserOrganizationData, GetUserOrganizationError, GetUserOrganizationErrors, GetUserOrganizationResponse, GetUserOrganizationResponses, GetUserPermissionsData, GetUserPermissionsError, GetUserPermissionsErrors, GetUserPermissionsResponse, GetUserPermissionsResponses, GetUserQuotaData, GetUserQuotaError, GetUserQuotaErrors, GetUserQuotaResponse, GetUserQuotaResponses, GetUserTeamsData, GetUserTeamsError, GetUserTeamsErrors, GetUserTeamsResponse, GetUserTeamsResponses, GithubLinkStatusResponse, GithubMergeMethod, GithubPullRequestCheckRun, GithubPullRequestComment, GithubPullRequestLabel, GithubPullRequestMergeability, GithubPullRequestMergeabilityEntry, GithubPullRequestMergeabilityRequest, GithubPullRequestMergeabilityResponse, GithubPullRequestNumber, GithubPullRequestRef, GithubPullRequestReview, GithubPullRequestReviewState, GithubPullRequestStatus, GithubPullRequestUser, GmailLinkStatusResponse, GtmInviteLink, GtmInviteLinkList, GtmInviteLinkStatus, GtmInviteOffer, GtmInviteOfferStatus, HealthHandlerData, HealthHandlerResponse, HealthHandlerResponses, InitGithubLinkData, InitGithubLinkError, InitGithubLinkErrors, InitGithubLinkResponse, InitGithubLinkResponse2, InitGithubLinkResponses, InitGmailLinkData, InitGmailLinkError, InitGmailLinkErrors, InitGmailLinkResponse, InitGmailLinkResponse2, InitGmailLinkResponses, InitOutlookLinkData, InitOutlookLinkError, InitOutlookLinkErrors, InitOutlookLinkResponse, InitOutlookLinkResponse2, InitOutlookLinkResponses, InviteEntry, InviteToTeamData, InviteToTeamError, InviteToTeamErrors, InviteToTeamRequest, InviteToTeamResponses, JoinTeamData, JoinTeamError, JoinTeamErrors, JoinTeamResponses, LinkShare, ListCodexEnvironmentsData, ListCodexEnvironmentsResponse, ListCodexEnvironmentsResponses, ListCursorModelsData, ListCursorModelsError, ListCursorModelsErrors, ListCursorModelsResponse, ListCursorModelsResponses, ListGtmInviteLinksData, ListGtmInviteLinksError, ListGtmInviteLinksErrors, ListGtmInviteLinksResponse, ListGtmInviteLinksResponses, LogoutData, LogoutResponse, LogoutResponses, MacroApiTokenData, MacroApiTokenError, MacroApiTokenErrors, MacroApiTokenResponse, MacroApiTokenResponse2, MacroApiTokenResponses, MergeGithubPullRequestData, MergeGithubPullRequestError, MergeGithubPullRequestErrors, MergeGithubPullRequestRequest, MergeGithubPullRequestResponse, MergeGithubPullRequestResponse2, MergeGithubPullRequestResponses, Oauth2CallbackData, Oauth2CallbackError, Oauth2CallbackErrors, Oauth2CallbackResponses, OauthRedirectData, OauthRedirectError, OauthRedirectErrors, OauthRedirectResponses, PasswordlessCallbackData, PasswordlessCallbackError, PasswordlessCallbackErrors, PasswordlessCallbackResponse, PasswordlessCallbackResponses, PasswordlessLoginData, PasswordlessLoginError, PasswordlessLoginErrors, PasswordlessLoginResponse, PasswordlessLoginResponses, PasswordlessRequest, PasswordlessStartedResponse, PasswordLoginData, PasswordLoginError, PasswordLoginErrors, PasswordLoginResponse, PasswordLoginResponses, PasswordRequest, PatchTeamCrmSettingsData, PatchTeamCrmSettingsError, PatchTeamCrmSettingsErrors, PatchTeamCrmSettingsRequest, PatchTeamCrmSettingsResponse, PatchTeamCrmSettingsResponse2, PatchTeamCrmSettingsResponses, PatchTeamData, PatchTeamError, PatchTeamErrors, PatchTeamMemberPlanData, PatchTeamMemberPlanError, PatchTeamMemberPlanErrors, PatchTeamMemberPlanRequest, PatchTeamMemberPlanResponse, PatchTeamMemberPlanResponses, PatchTeamRequest, PatchTeamResponses, PatchTeamUserRole, PatchUserGroupData, PatchUserGroupError, PatchUserGroupErrors, PatchUserGroupRequest, PatchUserGroupResponse, PatchUserGroupResponses, PatchUserOnboardingData, PatchUserOnboardingError, PatchUserOnboardingErrors, PatchUserOnboardingRequest, PatchUserOnboardingResponse, PatchUserOnboardingResponses, PatchUserTutorialData, PatchUserTutorialError, PatchUserTutorialErrors, PatchUserTutorialRequest, PatchUserTutorialResponse, PatchUserTutorialResponses, Permission, PlanCatalogEntry, PlanCatalogResponse, PlanTier, PollCodexLoginData, PollCodexLoginResponse, PollCodexLoginResponses, PostGetNamesRequestBody, PostProfilePicturesData, PostProfilePicturesError, PostProfilePicturesErrors, PostProfilePicturesResponse, PostProfilePicturesResponses, ProfilePictureQueryParams, ProfilePictures, PublicGtmInviteLink, PutCursorApiKeyData, PutCursorApiKeyError, PutCursorApiKeyErrors, PutCursorApiKeyRequest, PutCursorApiKeyResponse, PutCursorApiKeyResponses, PutCursorDefaultModelData, PutCursorDefaultModelError, PutCursorDefaultModelErrors, PutCursorDefaultModelRequest, PutCursorDefaultModelResponse, PutCursorDefaultModelResponses, PutProfilePictureData, PutProfilePictureError, PutProfilePictureErrors, PutProfilePictureResponse, PutProfilePictureResponses, PutUserNameData, PutUserNameError, PutUserNameErrors, PutUserNameQueryParams, PutUserNameResponse, PutUserNameResponses, RedeemGtmInviteLinkData, RedeemGtmInviteLinkError, RedeemGtmInviteLinkErrors, RedeemGtmInviteLinkRequest, RedeemGtmInviteLinkResponse, RedeemGtmInviteLinkResponses, RefreshData, RefreshError, RefreshErrors, RefreshResponse, RefreshResponses, RejectInvitationData, RejectInvitationError, RejectInvitationErrors, RejectInvitationResponses, RemoveUserFromTeamData, RemoveUserFromTeamError, RemoveUserFromTeamErrors, RemoveUserFromTeamResponses, ResendFusionauthVerifyUserEmailData, ResendFusionauthVerifyUserEmailError, ResendFusionauthVerifyUserEmailErrors, ResendFusionauthVerifyUserEmailRequest, ResendFusionauthVerifyUserEmailResponse, ResendFusionauthVerifyUserEmailResponses, ResolveGtmInviteLinkData, ResolveGtmInviteLinkError, ResolveGtmInviteLinkErrors, ResolveGtmInviteLinkResponse, ResolveGtmInviteLinkResponses, RevokeGtmInviteLinkData, RevokeGtmInviteLinkError, RevokeGtmInviteLinkErrors, RevokeGtmInviteLinkResponse, RevokeGtmInviteLinkResponses, ScheduledSeatPlan, SeatPlan, SendInviteBody, SendMobileWelcomeEmailData, SendMobileWelcomeEmailError, SendMobileWelcomeEmailErrors, SendMobileWelcomeEmailRequest, SendMobileWelcomeEmailResponse, SendMobileWelcomeEmailResponse2, SendMobileWelcomeEmailResponses, SendReferralCodeData, SendReferralCodeError, SendReferralCodeErrors, SendReferralCodeResponse, SendReferralCodeResponses, SessionCreationData, SessionCreationError, SessionCreationErrors, SessionCreationResponse, SessionCreationResponses, SessionLoginData, SessionLoginError, SessionLoginErrors, SessionLoginResponse, SessionLoginResponses, SetGithubPullRequestDraftData, SetGithubPullRequestDraftError, SetGithubPullRequestDraftErrors, SetGithubPullRequestDraftRequest, SetGithubPullRequestDraftResponse, SetGithubPullRequestDraftResponse2, SetGithubPullRequestDraftResponses, SsoLoginData, SsoLoginError, SsoLoginErrors, SsoLoginResponses, SsoRequiredResponse, StartCodexLoginData, StartCodexLoginResponse, StartCodexLoginResponses, StripeSessionResponse, SubscriptionStatus, Team, TeamInviteDetails, TeamInvitesResponse, TeamMember, TeamPlan, TeamRole, TeamWithMembers, ToggleAutoJoinDomainResponse, ToggleNonAdminInvitesResponse, ToggleTeamAutoJoinDomainData, ToggleTeamAutoJoinDomainError, ToggleTeamAutoJoinDomainErrors, ToggleTeamAutoJoinDomainResponse, ToggleTeamAutoJoinDomainResponses, ToggleTeamNonAdminInvitesData, ToggleTeamNonAdminInvitesError, ToggleTeamNonAdminInvitesErrors, ToggleTeamNonAdminInvitesResponse, ToggleTeamNonAdminInvitesResponses, TrialEligibility, UpdateAiBillingAutoReloadData, UpdateAiBillingAutoReloadError, UpdateAiBillingAutoReloadErrors, UpdateAiBillingAutoReloadResponse, UpdateAiBillingAutoReloadResponses, UpdateAiBillingOverageData, UpdateAiBillingOverageError, UpdateAiBillingOverageErrors, UpdateAiBillingOverageResponse, UpdateAiBillingOverageResponses, UpdateAutoReloadRequest, UpdateOverageRequest, UsageSnapshot, UserLinkResponse, UserName, UserNames, UserOrganizationResponse, UserProfilePicture, UserQuota, UserTokensResponse, VerifyEmailLinkData, VerifyEmailLinkError, VerifyEmailLinkErrors, VerifyEmailLinkResponse, VerifyEmailLinkResponses, VerifyFusionauthUserEmailData, VerifyFusionauthUserEmailError, VerifyFusionauthUserEmailErrors, VerifyFusionauthUserEmailResponse, VerifyFusionauthUserEmailResponses, VerifyMergeRequestData, VerifyMergeRequestError, VerifyMergeRequestErrors, VerifyMergeRequestResponse, VerifyMergeRequestResponses } from './types.gen';
+export type { AbGroup, AiBillingErrorBody, AppleLoginData, AppleLoginError, AppleLoginErrors, AppleLoginRequest, AppleLoginResponse, AppleLoginResponses, AutoReloadDefaults, AutoReloadMonthlyBudget, AutoReloadSnapshot, CancelCodexLoginData, CancelCodexLoginResponse, CancelCodexLoginResponses, ChangePlanData, ChangePlanError, ChangePlanErrors, ChangePlanRequest, ChangePlanResponse, ChangePlanResponse2, ChangePlanResponses, CheckGithubLinkStatusData, CheckGithubLinkStatusError, CheckGithubLinkStatusErrors, CheckGithubLinkStatusResponse, CheckGithubLinkStatusResponses, CheckGmailLinkStatusData, CheckGmailLinkStatusError, CheckGmailLinkStatusErrors, CheckGmailLinkStatusResponse, CheckGmailLinkStatusResponses, CheckoutSessionMetadata, CheckoutSessionV2Response, ClientOptions, CodexConfigRequest, CodexConnectionStatus, CodexEnvironment, CodexEnvironmentRepository, CodexLoginPoll, CodexLoginStart, CodexLoginState, ConfigureCodexData, ConfigureCodexResponse, ConfigureCodexResponses, CreateAccountMergeRequest, CreateAiCreditCheckoutData, CreateAiCreditCheckoutError, CreateAiCreditCheckoutErrors, CreateAiCreditCheckoutResponse, CreateAiCreditCheckoutResponses, CreateCheckoutSessionV2Data, CreateCheckoutSessionV2Error, CreateCheckoutSessionV2Errors, CreateCheckoutSessionV2Request, CreateCheckoutSessionV2Response, CreateCheckoutSessionV2Responses, CreateGtmInviteLinkData, CreateGtmInviteLinkError, CreateGtmInviteLinkErrors, CreateGtmInviteLinkRequest, CreateGtmInviteLinkResponse, CreateGtmInviteLinkResponses, CreateInProgressLinkData, CreateInProgressLinkError, CreateInProgressLinkErrors, CreateInProgressLinkResponse, CreateInProgressLinkResponse2, CreateInProgressLinkResponses, CreateMergeRequestData, CreateMergeRequestError, CreateMergeRequestErrors, CreateMergeRequestResponse, CreateMergeRequestResponses, CreatePortalSessionData, CreatePortalSessionError, CreatePortalSessionErrors, CreatePortalSessionRequest, CreatePortalSessionResponse, CreatePortalSessionResponses, CreateTeamData, CreateTeamError, CreateTeamErrors, CreateTeamRequest, CreateTeamResponse, CreateTeamResponses, CreditCheckoutRequestBody, CreditCheckoutResponse, CursorApiKeyStatus, CursorModelOption, CursorModelsResponse, DeleteCursorApiKeyData, DeleteCursorApiKeyError, DeleteCursorApiKeyErrors, DeleteCursorApiKeyResponse, DeleteCursorApiKeyResponses, DeleteGithubLinkData, DeleteGithubLinkError, DeleteGithubLinkErrors, DeleteGithubLinkResponse, DeleteGithubLinkResponses, DeleteTeamData, DeleteTeamError, DeleteTeamErrors, DeleteTeamInviteHandlerData, DeleteTeamInviteHandlerError, DeleteTeamInviteHandlerErrors, DeleteTeamInviteHandlerResponses, DeleteTeamResponses, DeleteUserData, DeleteUserError, DeleteUserErrors, DeleteUserResponse, DeleteUserResponses, DenyReason, DisconnectCodexData, DisconnectCodexResponse, DisconnectCodexResponses, EmailConnectionProviders, EmailConnectionProvidersData, EmailConnectionProvidersError, EmailConnectionProvidersErrors, EmailConnectionProvidersResponse, EmailConnectionProvidersResponses, EmptyResponse, EnrichedGithubPullRequest, EnrichGithubPullRequestsData, EnrichGithubPullRequestsError, EnrichGithubPullRequestsErrors, EnrichGithubPullRequestsProxyRequest, EnrichGithubPullRequestsResponse, EnrichGithubPullRequestsResponse2, EnrichGithubPullRequestsResponses, ErrorResponse, GenerateEmailLinkData, GenerateEmailLinkError, GenerateEmailLinkErrors, GenerateEmailLinkRequest, GenerateEmailLinkResponse, GenerateEmailLinkResponses, GenericSuccessResponse, GetAiBillingPlansData, GetAiBillingPlansResponse, GetAiBillingPlansResponses, GetAiBillingSummaryData, GetAiBillingSummaryError, GetAiBillingSummaryErrors, GetAiBillingSummaryResponse, GetAiBillingSummaryResponses, GetCodexConnectionData, GetCodexConnectionResponse, GetCodexConnectionResponses, GetCursorApiKeyData, GetCursorApiKeyError, GetCursorApiKeyErrors, GetCursorApiKeyResponse, GetCursorApiKeyResponses, GetGithubPullRequestMergeabilityData, GetGithubPullRequestMergeabilityError, GetGithubPullRequestMergeabilityErrors, GetGithubPullRequestMergeabilityResponse, GetGithubPullRequestMergeabilityResponses, GetGtmInviteOfferData, GetGtmInviteOfferError, GetGtmInviteOfferErrors, GetGtmInviteOfferResponse, GetGtmInviteOfferResponses, GetLegacyUserPermissionsData, GetLegacyUserPermissionsError, GetLegacyUserPermissionsErrors, GetLegacyUserPermissionsResponse, GetLegacyUserPermissionsResponse2, GetLegacyUserPermissionsResponses, GetNamesWithEmailRequestBody, GetPermissionsData, GetPermissionsError, GetPermissionsErrors, GetPermissionsResponse, GetPermissionsResponses, GetProfilePicturesRequestBody, GetReferralCodeData, GetReferralCodeError, GetReferralCodeErrors, GetReferralCodeResponse, GetReferralCodeResponses, GetSubscriptionStatusData, GetSubscriptionStatusError, GetSubscriptionStatusErrors, GetSubscriptionStatusResponse, GetSubscriptionStatusResponses, GetTeamData, GetTeamError, GetTeamErrors, GetTeamInvitesData, GetTeamInvitesError, GetTeamInvitesErrors, GetTeamInvitesResponse, GetTeamInvitesResponses, GetTeamResponse, GetTeamResponses, GetTrialEligibilityData, GetTrialEligibilityError, GetTrialEligibilityErrors, GetTrialEligibilityResponse, GetTrialEligibilityResponses, GetUserInfo, GetUserInfoData, GetUserInfoError, GetUserInfoErrors, GetUserInfoResponse, GetUserInfoResponses, GetUserInvitesData, GetUserInvitesError, GetUserInvitesErrors, GetUserInvitesResponse, GetUserInvitesResponses, GetUserLinkExistsData, GetUserLinkExistsError, GetUserLinkExistsErrors, GetUserLinkExistsResponse, GetUserLinkExistsResponses, GetUserNameData, GetUserNameError, GetUserNameErrors, GetUserNameResponse, GetUserNameResponses, GetUserNamesData, GetUserNamesError, GetUserNamesErrors, GetUserNamesResponse, GetUserNamesResponses, GetUserNamesWithEmailData, GetUserNamesWithEmailError, GetUserNamesWithEmailErrors, GetUserNamesWithEmailResponse, GetUserNamesWithEmailResponses, GetUserOrganizationData, GetUserOrganizationError, GetUserOrganizationErrors, GetUserOrganizationResponse, GetUserOrganizationResponses, GetUserPermissionsData, GetUserPermissionsError, GetUserPermissionsErrors, GetUserPermissionsResponse, GetUserPermissionsResponses, GetUserQuotaData, GetUserQuotaError, GetUserQuotaErrors, GetUserQuotaResponse, GetUserQuotaResponses, GetUserTeamsData, GetUserTeamsError, GetUserTeamsErrors, GetUserTeamsResponse, GetUserTeamsResponses, GithubLinkStatusResponse, GithubMergeMethod, GithubPullRequestCheckRun, GithubPullRequestComment, GithubPullRequestLabel, GithubPullRequestMergeability, GithubPullRequestMergeabilityEntry, GithubPullRequestMergeabilityRequest, GithubPullRequestMergeabilityResponse, GithubPullRequestNumber, GithubPullRequestRef, GithubPullRequestReview, GithubPullRequestReviewState, GithubPullRequestStatus, GithubPullRequestUser, GmailLinkStatusResponse, GtmInviteLink, GtmInviteLinkList, GtmInviteLinkStatus, GtmInviteOffer, GtmInviteOfferStatus, HealthHandlerData, HealthHandlerResponse, HealthHandlerResponses, InitGithubLinkData, InitGithubLinkError, InitGithubLinkErrors, InitGithubLinkResponse, InitGithubLinkResponse2, InitGithubLinkResponses, InitGmailLinkData, InitGmailLinkError, InitGmailLinkErrors, InitGmailLinkResponse, InitGmailLinkResponse2, InitGmailLinkResponses, InitOutlookLinkData, InitOutlookLinkError, InitOutlookLinkErrors, InitOutlookLinkResponse, InitOutlookLinkResponse2, InitOutlookLinkResponses, InviteEntry, InviteToTeamData, InviteToTeamError, InviteToTeamErrors, InviteToTeamRequest, InviteToTeamResponses, JoinTeamData, JoinTeamError, JoinTeamErrors, JoinTeamResponses, LinkShare, ListCodexEnvironmentsData, ListCodexEnvironmentsResponse, ListCodexEnvironmentsResponses, ListCursorModelsData, ListCursorModelsError, ListCursorModelsErrors, ListCursorModelsResponse, ListCursorModelsResponses, ListGtmInviteLinksData, ListGtmInviteLinksError, ListGtmInviteLinksErrors, ListGtmInviteLinksResponse, ListGtmInviteLinksResponses, LogoutData, LogoutResponse, LogoutResponses, MacroApiTokenData, MacroApiTokenError, MacroApiTokenErrors, MacroApiTokenResponse, MacroApiTokenResponse2, MacroApiTokenResponses, MergeGithubPullRequestData, MergeGithubPullRequestError, MergeGithubPullRequestErrors, MergeGithubPullRequestRequest, MergeGithubPullRequestResponse, MergeGithubPullRequestResponse2, MergeGithubPullRequestResponses, Oauth2CallbackData, Oauth2CallbackError, Oauth2CallbackErrors, Oauth2CallbackResponses, OauthRedirectData, OauthRedirectError, OauthRedirectErrors, OauthRedirectResponses, PasswordlessCallbackData, PasswordlessCallbackError, PasswordlessCallbackErrors, PasswordlessCallbackResponse, PasswordlessCallbackResponses, PasswordlessLoginData, PasswordlessLoginError, PasswordlessLoginErrors, PasswordlessLoginResponse, PasswordlessLoginResponses, PasswordlessRequest, PasswordlessStartedResponse, PasswordLoginData, PasswordLoginError, PasswordLoginErrors, PasswordLoginResponse, PasswordLoginResponses, PasswordRequest, PatchTeamCrmSettingsData, PatchTeamCrmSettingsError, PatchTeamCrmSettingsErrors, PatchTeamCrmSettingsRequest, PatchTeamCrmSettingsResponse, PatchTeamCrmSettingsResponse2, PatchTeamCrmSettingsResponses, PatchTeamData, PatchTeamError, PatchTeamErrors, PatchTeamMemberPlanData, PatchTeamMemberPlanError, PatchTeamMemberPlanErrors, PatchTeamMemberPlanRequest, PatchTeamMemberPlanResponse, PatchTeamMemberPlanResponses, PatchTeamRequest, PatchTeamResponses, PatchTeamUserRole, PatchUserGroupData, PatchUserGroupError, PatchUserGroupErrors, PatchUserGroupRequest, PatchUserGroupResponse, PatchUserGroupResponses, PatchUserOnboardingData, PatchUserOnboardingError, PatchUserOnboardingErrors, PatchUserOnboardingRequest, PatchUserOnboardingResponse, PatchUserOnboardingResponses, PatchUserTutorialData, PatchUserTutorialError, PatchUserTutorialErrors, PatchUserTutorialRequest, PatchUserTutorialResponse, PatchUserTutorialResponses, Permission, PlanCatalogEntry, PlanCatalogResponse, PlanTier, PollCodexLoginData, PollCodexLoginResponse, PollCodexLoginResponses, PostGetNamesRequestBody, PostProfilePicturesData, PostProfilePicturesError, PostProfilePicturesErrors, PostProfilePicturesResponse, PostProfilePicturesResponses, ProfilePictureQueryParams, ProfilePictures, PublicGtmInviteLink, PutCursorApiKeyData, PutCursorApiKeyError, PutCursorApiKeyErrors, PutCursorApiKeyRequest, PutCursorApiKeyResponse, PutCursorApiKeyResponses, PutCursorDefaultModelData, PutCursorDefaultModelError, PutCursorDefaultModelErrors, PutCursorDefaultModelRequest, PutCursorDefaultModelResponse, PutCursorDefaultModelResponses, PutProfilePictureData, PutProfilePictureError, PutProfilePictureErrors, PutProfilePictureResponse, PutProfilePictureResponses, PutUserNameData, PutUserNameError, PutUserNameErrors, PutUserNameQueryParams, PutUserNameResponse, PutUserNameResponses, RedeemGtmInviteLinkData, RedeemGtmInviteLinkError, RedeemGtmInviteLinkErrors, RedeemGtmInviteLinkRequest, RedeemGtmInviteLinkResponse, RedeemGtmInviteLinkResponses, RefreshData, RefreshError, RefreshErrors, RefreshResponse, RefreshResponses, RejectInvitationData, RejectInvitationError, RejectInvitationErrors, RejectInvitationResponses, RemoveUserFromTeamData, RemoveUserFromTeamError, RemoveUserFromTeamErrors, RemoveUserFromTeamResponses, ResendFusionauthVerifyUserEmailData, ResendFusionauthVerifyUserEmailError, ResendFusionauthVerifyUserEmailErrors, ResendFusionauthVerifyUserEmailRequest, ResendFusionauthVerifyUserEmailResponse, ResendFusionauthVerifyUserEmailResponses, ResolveGtmInviteLinkData, ResolveGtmInviteLinkError, ResolveGtmInviteLinkErrors, ResolveGtmInviteLinkResponse, ResolveGtmInviteLinkResponses, RevokeGtmInviteLinkData, RevokeGtmInviteLinkError, RevokeGtmInviteLinkErrors, RevokeGtmInviteLinkResponse, RevokeGtmInviteLinkResponses, ScheduledSeatPlan, SeatPlan, SendInviteBody, SendMobileWelcomeEmailData, SendMobileWelcomeEmailError, SendMobileWelcomeEmailErrors, SendMobileWelcomeEmailRequest, SendMobileWelcomeEmailResponse, SendMobileWelcomeEmailResponse2, SendMobileWelcomeEmailResponses, SendReferralCodeData, SendReferralCodeError, SendReferralCodeErrors, SendReferralCodeResponse, SendReferralCodeResponses, SessionCreationData, SessionCreationError, SessionCreationErrors, SessionCreationResponse, SessionCreationResponses, SessionLoginData, SessionLoginError, SessionLoginErrors, SessionLoginResponse, SessionLoginResponses, SetGithubPullRequestDraftData, SetGithubPullRequestDraftError, SetGithubPullRequestDraftErrors, SetGithubPullRequestDraftRequest, SetGithubPullRequestDraftResponse, SetGithubPullRequestDraftResponse2, SetGithubPullRequestDraftResponses, SsoLoginData, SsoLoginError, SsoLoginErrors, SsoLoginResponses, SsoRequiredResponse, StartCodexLoginData, StartCodexLoginResponse, StartCodexLoginResponses, StripeSessionResponse, SubscriptionStatus, Team, TeamInviteDetails, TeamInvitesResponse, TeamMember, TeamPlan, TeamRole, TeamWithMembers, ToggleAutoJoinDomainResponse, ToggleNonAdminInvitesResponse, ToggleTeamAutoJoinDomainData, ToggleTeamAutoJoinDomainError, ToggleTeamAutoJoinDomainErrors, ToggleTeamAutoJoinDomainResponse, ToggleTeamAutoJoinDomainResponses, ToggleTeamNonAdminInvitesData, ToggleTeamNonAdminInvitesError, ToggleTeamNonAdminInvitesErrors, ToggleTeamNonAdminInvitesResponse, ToggleTeamNonAdminInvitesResponses, TrialEligibility, UpdateAiBillingAutoReloadData, UpdateAiBillingAutoReloadError, UpdateAiBillingAutoReloadErrors, UpdateAiBillingAutoReloadResponse, UpdateAiBillingAutoReloadResponses, UpdateAiBillingOverageData, UpdateAiBillingOverageError, UpdateAiBillingOverageErrors, UpdateAiBillingOverageResponse, UpdateAiBillingOverageResponses, UpdateAutoReloadRequest, UpdateOverageRequest, UsageSnapshot, UserLinkResponse, UserName, UserNames, UserOrganizationResponse, UserProfilePicture, UserQuota, UserTokensResponse, VerifyEmailLinkData, VerifyEmailLinkError, VerifyEmailLinkErrors, VerifyEmailLinkResponse, VerifyEmailLinkResponses, VerifyFusionauthUserEmailData, VerifyFusionauthUserEmailError, VerifyFusionauthUserEmailErrors, VerifyFusionauthUserEmailResponse, VerifyFusionauthUserEmailResponses, VerifyMergeRequestData, VerifyMergeRequestError, VerifyMergeRequestErrors, VerifyMergeRequestResponse, VerifyMergeRequestResponses } from './types.gen';
diff --git a/packages/sdk/generated/auth/sdk.gen.ts b/packages/sdk/generated/auth/sdk.gen.ts
index bfe073b19e..8950989555 100644
--- a/packages/sdk/generated/auth/sdk.gen.ts
+++ b/packages/sdk/generated/auth/sdk.gen.ts
@@ -2,7 +2,7 @@
import type { Client, ClientMeta, Options as Options2, RequestResult, TDataShape } from './client';
import { client } from './client.gen';
-import type { AppleLoginData, AppleLoginErrors, AppleLoginResponses, CancelCodexLoginData, CancelCodexLoginResponses, ChangePlanData, ChangePlanErrors, ChangePlanResponses, CheckGithubLinkStatusData, CheckGithubLinkStatusErrors, CheckGithubLinkStatusResponses, CheckGmailLinkStatusData, CheckGmailLinkStatusErrors, CheckGmailLinkStatusResponses, ConfigureCodexData, ConfigureCodexResponses, CreateAiCreditCheckoutData, CreateAiCreditCheckoutErrors, CreateAiCreditCheckoutResponses, CreateCheckoutSessionV2Data, CreateCheckoutSessionV2Errors, CreateCheckoutSessionV2Responses, CreateGtmInviteLinkData, CreateGtmInviteLinkErrors, CreateGtmInviteLinkResponses, CreateInProgressLinkData, CreateInProgressLinkErrors, CreateInProgressLinkResponses, CreateMergeRequestData, CreateMergeRequestErrors, CreateMergeRequestResponses, CreatePortalSessionData, CreatePortalSessionErrors, CreatePortalSessionResponses, CreateTeamData, CreateTeamErrors, CreateTeamResponses, DeleteCursorApiKeyData, DeleteCursorApiKeyErrors, DeleteCursorApiKeyResponses, DeleteGithubLinkData, DeleteGithubLinkErrors, DeleteGithubLinkResponses, DeleteTeamData, DeleteTeamErrors, DeleteTeamInviteHandlerData, DeleteTeamInviteHandlerErrors, DeleteTeamInviteHandlerResponses, DeleteTeamResponses, DeleteUserData, DeleteUserErrors, DeleteUserResponses, DisconnectCodexData, DisconnectCodexResponses, EmailConnectionProvidersData, EmailConnectionProvidersResponses, EnrichGithubPullRequestsData, EnrichGithubPullRequestsErrors, EnrichGithubPullRequestsResponses, GenerateEmailLinkData, GenerateEmailLinkErrors, GenerateEmailLinkResponses, GetAiBillingPlansData, GetAiBillingPlansResponses, GetAiBillingSummaryData, GetAiBillingSummaryErrors, GetAiBillingSummaryResponses, GetCodexConnectionData, GetCodexConnectionResponses, GetCursorApiKeyData, GetCursorApiKeyErrors, GetCursorApiKeyResponses, GetGithubPullRequestMergeabilityData, GetGithubPullRequestMergeabilityErrors, GetGithubPullRequestMergeabilityResponses, GetGtmInviteOfferData, GetGtmInviteOfferErrors, GetGtmInviteOfferResponses, GetLegacyUserPermissionsData, GetLegacyUserPermissionsErrors, GetLegacyUserPermissionsResponses, GetPermissionsData, GetPermissionsErrors, GetPermissionsResponses, GetReferralCodeData, GetReferralCodeErrors, GetReferralCodeResponses, GetSubscriptionStatusData, GetSubscriptionStatusErrors, GetSubscriptionStatusResponses, GetTeamData, GetTeamErrors, GetTeamInvitesData, GetTeamInvitesErrors, GetTeamInvitesResponses, GetTeamResponses, GetTrialEligibilityData, GetTrialEligibilityErrors, GetTrialEligibilityResponses, GetUserInfoData, GetUserInfoErrors, GetUserInfoResponses, GetUserInvitesData, GetUserInvitesErrors, GetUserInvitesResponses, GetUserLinkExistsData, GetUserLinkExistsErrors, GetUserLinkExistsResponses, GetUserNameData, GetUserNameErrors, GetUserNameResponses, GetUserNamesData, GetUserNamesErrors, GetUserNamesResponses, GetUserNamesWithEmailData, GetUserNamesWithEmailErrors, GetUserNamesWithEmailResponses, GetUserOrganizationData, GetUserOrganizationErrors, GetUserOrganizationResponses, GetUserPermissionsData, GetUserPermissionsErrors, GetUserPermissionsResponses, GetUserQuotaData, GetUserQuotaErrors, GetUserQuotaResponses, GetUserTeamsData, GetUserTeamsErrors, GetUserTeamsResponses, HealthHandlerData, HealthHandlerResponses, InitGithubLinkData, InitGithubLinkErrors, InitGithubLinkResponses, InitGmailLinkData, InitGmailLinkErrors, InitGmailLinkResponses, InitOutlookLinkData, InitOutlookLinkErrors, InitOutlookLinkResponses, InviteToTeamData, InviteToTeamErrors, InviteToTeamResponses, JoinTeamData, JoinTeamErrors, JoinTeamResponses, ListCodexEnvironmentsData, ListCodexEnvironmentsResponses, ListCursorModelsData, ListCursorModelsErrors, ListCursorModelsResponses, ListGtmInviteLinksData, ListGtmInviteLinksErrors, ListGtmInviteLinksResponses, LogoutData, LogoutResponses, MacroApiTokenData, MacroApiTokenErrors, MacroApiTokenResponses, MergeGithubPullRequestData, MergeGithubPullRequestErrors, MergeGithubPullRequestResponses, Oauth2CallbackData, Oauth2CallbackErrors, Oauth2CallbackResponses, OauthRedirectData, OauthRedirectErrors, OauthRedirectResponses, PasswordlessCallbackData, PasswordlessCallbackErrors, PasswordlessCallbackResponses, PasswordlessLoginData, PasswordlessLoginErrors, PasswordlessLoginResponses, PasswordLoginData, PasswordLoginErrors, PasswordLoginResponses, PatchTeamCrmSettingsData, PatchTeamCrmSettingsErrors, PatchTeamCrmSettingsResponses, PatchTeamData, PatchTeamErrors, PatchTeamMemberPlanData, PatchTeamMemberPlanErrors, PatchTeamMemberPlanResponses, PatchTeamResponses, PatchUserGroupData, PatchUserGroupErrors, PatchUserGroupResponses, PatchUserOnboardingData, PatchUserOnboardingErrors, PatchUserOnboardingResponses, PatchUserTutorialData, PatchUserTutorialErrors, PatchUserTutorialResponses, PollCodexLoginData, PollCodexLoginResponses, PostProfilePicturesData, PostProfilePicturesErrors, PostProfilePicturesResponses, PutCursorApiKeyData, PutCursorApiKeyErrors, PutCursorApiKeyResponses, PutCursorDefaultModelData, PutCursorDefaultModelErrors, PutCursorDefaultModelResponses, PutProfilePictureData, PutProfilePictureErrors, PutProfilePictureResponses, PutUserNameData, PutUserNameErrors, PutUserNameResponses, RedeemGtmInviteLinkData, RedeemGtmInviteLinkErrors, RedeemGtmInviteLinkResponses, RefreshData, RefreshErrors, RefreshResponses, RejectInvitationData, RejectInvitationErrors, RejectInvitationResponses, RemoveUserFromTeamData, RemoveUserFromTeamErrors, RemoveUserFromTeamResponses, ResendFusionauthVerifyUserEmailData, ResendFusionauthVerifyUserEmailErrors, ResendFusionauthVerifyUserEmailResponses, ResolveGtmInviteLinkData, ResolveGtmInviteLinkErrors, ResolveGtmInviteLinkResponses, RevokeGtmInviteLinkData, RevokeGtmInviteLinkErrors, RevokeGtmInviteLinkResponses, SendMobileWelcomeEmailData, SendMobileWelcomeEmailErrors, SendMobileWelcomeEmailResponses, SendReferralCodeData, SendReferralCodeErrors, SendReferralCodeResponses, SessionCreationData, SessionCreationErrors, SessionCreationResponses, SessionLoginData, SessionLoginErrors, SessionLoginResponses, SetGithubPullRequestDraftData, SetGithubPullRequestDraftErrors, SetGithubPullRequestDraftResponses, SsoLoginData, SsoLoginErrors, SsoLoginResponses, StartCodexLoginData, StartCodexLoginResponses, ToggleTeamAutoJoinDomainData, ToggleTeamAutoJoinDomainErrors, ToggleTeamAutoJoinDomainResponses, ToggleTeamNonAdminInvitesData, ToggleTeamNonAdminInvitesErrors, ToggleTeamNonAdminInvitesResponses, UpdateAiBillingAutoReloadData, UpdateAiBillingAutoReloadErrors, UpdateAiBillingAutoReloadResponses, UpdateAiBillingOverageData, UpdateAiBillingOverageErrors, UpdateAiBillingOverageResponses, VerifyEmailLinkData, VerifyEmailLinkErrors, VerifyEmailLinkResponses, VerifyFusionauthUserEmailData, VerifyFusionauthUserEmailErrors, VerifyFusionauthUserEmailResponses, VerifyMergeRequestData, VerifyMergeRequestErrors, VerifyMergeRequestResponses } from './types.gen';
+import type { AppleLoginData, AppleLoginErrors, AppleLoginResponses, CancelCodexLoginData, CancelCodexLoginResponses, ChangePlanData, ChangePlanErrors, ChangePlanResponses, CheckGithubLinkStatusData, CheckGithubLinkStatusErrors, CheckGithubLinkStatusResponses, CheckGmailLinkStatusData, CheckGmailLinkStatusErrors, CheckGmailLinkStatusResponses, ConfigureCodexData, ConfigureCodexResponses, CreateAiCreditCheckoutData, CreateAiCreditCheckoutErrors, CreateAiCreditCheckoutResponses, CreateCheckoutSessionV2Data, CreateCheckoutSessionV2Errors, CreateCheckoutSessionV2Responses, CreateGtmInviteLinkData, CreateGtmInviteLinkErrors, CreateGtmInviteLinkResponses, CreateInProgressLinkData, CreateInProgressLinkErrors, CreateInProgressLinkResponses, CreateMergeRequestData, CreateMergeRequestErrors, CreateMergeRequestResponses, CreatePortalSessionData, CreatePortalSessionErrors, CreatePortalSessionResponses, CreateTeamData, CreateTeamErrors, CreateTeamResponses, DeleteCursorApiKeyData, DeleteCursorApiKeyErrors, DeleteCursorApiKeyResponses, DeleteGithubLinkData, DeleteGithubLinkErrors, DeleteGithubLinkResponses, DeleteTeamData, DeleteTeamErrors, DeleteTeamInviteHandlerData, DeleteTeamInviteHandlerErrors, DeleteTeamInviteHandlerResponses, DeleteTeamResponses, DeleteUserData, DeleteUserErrors, DeleteUserResponses, DisconnectCodexData, DisconnectCodexResponses, EmailConnectionProvidersData, EmailConnectionProvidersErrors, EmailConnectionProvidersResponses, EnrichGithubPullRequestsData, EnrichGithubPullRequestsErrors, EnrichGithubPullRequestsResponses, GenerateEmailLinkData, GenerateEmailLinkErrors, GenerateEmailLinkResponses, GetAiBillingPlansData, GetAiBillingPlansResponses, GetAiBillingSummaryData, GetAiBillingSummaryErrors, GetAiBillingSummaryResponses, GetCodexConnectionData, GetCodexConnectionResponses, GetCursorApiKeyData, GetCursorApiKeyErrors, GetCursorApiKeyResponses, GetGithubPullRequestMergeabilityData, GetGithubPullRequestMergeabilityErrors, GetGithubPullRequestMergeabilityResponses, GetGtmInviteOfferData, GetGtmInviteOfferErrors, GetGtmInviteOfferResponses, GetLegacyUserPermissionsData, GetLegacyUserPermissionsErrors, GetLegacyUserPermissionsResponses, GetPermissionsData, GetPermissionsErrors, GetPermissionsResponses, GetReferralCodeData, GetReferralCodeErrors, GetReferralCodeResponses, GetSubscriptionStatusData, GetSubscriptionStatusErrors, GetSubscriptionStatusResponses, GetTeamData, GetTeamErrors, GetTeamInvitesData, GetTeamInvitesErrors, GetTeamInvitesResponses, GetTeamResponses, GetTrialEligibilityData, GetTrialEligibilityErrors, GetTrialEligibilityResponses, GetUserInfoData, GetUserInfoErrors, GetUserInfoResponses, GetUserInvitesData, GetUserInvitesErrors, GetUserInvitesResponses, GetUserLinkExistsData, GetUserLinkExistsErrors, GetUserLinkExistsResponses, GetUserNameData, GetUserNameErrors, GetUserNameResponses, GetUserNamesData, GetUserNamesErrors, GetUserNamesResponses, GetUserNamesWithEmailData, GetUserNamesWithEmailErrors, GetUserNamesWithEmailResponses, GetUserOrganizationData, GetUserOrganizationErrors, GetUserOrganizationResponses, GetUserPermissionsData, GetUserPermissionsErrors, GetUserPermissionsResponses, GetUserQuotaData, GetUserQuotaErrors, GetUserQuotaResponses, GetUserTeamsData, GetUserTeamsErrors, GetUserTeamsResponses, HealthHandlerData, HealthHandlerResponses, InitGithubLinkData, InitGithubLinkErrors, InitGithubLinkResponses, InitGmailLinkData, InitGmailLinkErrors, InitGmailLinkResponses, InitOutlookLinkData, InitOutlookLinkErrors, InitOutlookLinkResponses, InviteToTeamData, InviteToTeamErrors, InviteToTeamResponses, JoinTeamData, JoinTeamErrors, JoinTeamResponses, ListCodexEnvironmentsData, ListCodexEnvironmentsResponses, ListCursorModelsData, ListCursorModelsErrors, ListCursorModelsResponses, ListGtmInviteLinksData, ListGtmInviteLinksErrors, ListGtmInviteLinksResponses, LogoutData, LogoutResponses, MacroApiTokenData, MacroApiTokenErrors, MacroApiTokenResponses, MergeGithubPullRequestData, MergeGithubPullRequestErrors, MergeGithubPullRequestResponses, Oauth2CallbackData, Oauth2CallbackErrors, Oauth2CallbackResponses, OauthRedirectData, OauthRedirectErrors, OauthRedirectResponses, PasswordlessCallbackData, PasswordlessCallbackErrors, PasswordlessCallbackResponses, PasswordlessLoginData, PasswordlessLoginErrors, PasswordlessLoginResponses, PasswordLoginData, PasswordLoginErrors, PasswordLoginResponses, PatchTeamCrmSettingsData, PatchTeamCrmSettingsErrors, PatchTeamCrmSettingsResponses, PatchTeamData, PatchTeamErrors, PatchTeamMemberPlanData, PatchTeamMemberPlanErrors, PatchTeamMemberPlanResponses, PatchTeamResponses, PatchUserGroupData, PatchUserGroupErrors, PatchUserGroupResponses, PatchUserOnboardingData, PatchUserOnboardingErrors, PatchUserOnboardingResponses, PatchUserTutorialData, PatchUserTutorialErrors, PatchUserTutorialResponses, PollCodexLoginData, PollCodexLoginResponses, PostProfilePicturesData, PostProfilePicturesErrors, PostProfilePicturesResponses, PutCursorApiKeyData, PutCursorApiKeyErrors, PutCursorApiKeyResponses, PutCursorDefaultModelData, PutCursorDefaultModelErrors, PutCursorDefaultModelResponses, PutProfilePictureData, PutProfilePictureErrors, PutProfilePictureResponses, PutUserNameData, PutUserNameErrors, PutUserNameResponses, RedeemGtmInviteLinkData, RedeemGtmInviteLinkErrors, RedeemGtmInviteLinkResponses, RefreshData, RefreshErrors, RefreshResponses, RejectInvitationData, RejectInvitationErrors, RejectInvitationResponses, RemoveUserFromTeamData, RemoveUserFromTeamErrors, RemoveUserFromTeamResponses, ResendFusionauthVerifyUserEmailData, ResendFusionauthVerifyUserEmailErrors, ResendFusionauthVerifyUserEmailResponses, ResolveGtmInviteLinkData, ResolveGtmInviteLinkErrors, ResolveGtmInviteLinkResponses, RevokeGtmInviteLinkData, RevokeGtmInviteLinkErrors, RevokeGtmInviteLinkResponses, SendMobileWelcomeEmailData, SendMobileWelcomeEmailErrors, SendMobileWelcomeEmailResponses, SendReferralCodeData, SendReferralCodeErrors, SendReferralCodeResponses, SessionCreationData, SessionCreationErrors, SessionCreationResponses, SessionLoginData, SessionLoginErrors, SessionLoginResponses, SetGithubPullRequestDraftData, SetGithubPullRequestDraftErrors, SetGithubPullRequestDraftResponses, SsoLoginData, SsoLoginErrors, SsoLoginResponses, StartCodexLoginData, StartCodexLoginResponses, ToggleTeamAutoJoinDomainData, ToggleTeamAutoJoinDomainErrors, ToggleTeamAutoJoinDomainResponses, ToggleTeamNonAdminInvitesData, ToggleTeamNonAdminInvitesErrors, ToggleTeamNonAdminInvitesResponses, UpdateAiBillingAutoReloadData, UpdateAiBillingAutoReloadErrors, UpdateAiBillingAutoReloadResponses, UpdateAiBillingOverageData, UpdateAiBillingOverageErrors, UpdateAiBillingOverageResponses, VerifyEmailLinkData, VerifyEmailLinkErrors, VerifyEmailLinkResponses, VerifyFusionauthUserEmailData, VerifyFusionauthUserEmailErrors, VerifyFusionauthUserEmailResponses, VerifyMergeRequestData, VerifyMergeRequestErrors, VerifyMergeRequestResponses } from './types.gen';
export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
/**
@@ -431,8 +431,8 @@ export class Sdk extends HeyApiClient {
return (options?.client ?? this.client).post<CreateInProgressLinkResponses, CreateInProgressLinkErrors, ThrowOnError>({ url: '/link', ...options });
}
- public emailConnectionProviders<ThrowOnError extends boolean = false>(options?: Options<EmailConnectionProvidersData, ThrowOnError>): RequestResult<EmailConnectionProvidersResponses, unknown, ThrowOnError> {
- return (options?.client ?? this.client).get<EmailConnectionProvidersResponses, unknown, ThrowOnError>({ url: '/link/email/providers', ...options });
+ public emailConnectionProviders<ThrowOnError extends boolean = false>(options?: Options<EmailConnectionProvidersData, ThrowOnError>): RequestResult<EmailConnectionProvidersResponses, EmailConnectionProvidersErrors, ThrowOnError> {
+ return (options?.client ?? this.client).get<EmailConnectionProvidersResponses, EmailConnectionProvidersErrors, ThrowOnError>({ url: '/link/email/providers', ...options });
}
/**
diff --git a/packages/sdk/generated/auth/types.gen.ts b/packages/sdk/generated/auth/types.gen.ts
index 30a41c97f7..737619464a 100644
--- a/packages/sdk/generated/auth/types.gen.ts
+++ b/packages/sdk/generated/auth/types.gen.ts
@@ -424,6 +424,12 @@ export type DenyReason = 'allowance_exhausted' | 'free_allowance_exhausted' | 'o
export type EmailConnectionProviders = {
gmail: boolean;
outlook: boolean;
+ /**
+ * Where a Microsoft 365 administrator approves Macro for their whole
+ * directory. Present when Outlook is configured and the request named an
+ * `original_url` for the administrator's browser to return to.
+ */
+ outlook_admin_consent_url?: string | null;
};
/**
@@ -2720,10 +2726,21 @@ export type CreateInProgressLinkResponse2 = CreateInProgressLinkResponses[keyof
export type EmailConnectionProvidersData = {
body?: never;
path?: never;
- query?: never;
+ query?: {
+ /**
+ * **OPTIONAL**. Where the admin-consent flow returns to; required for `outlook_admin_consent_url`.
+ */
+ original_url?: string;
+ };
url: '/link/email/providers';
};
+export type EmailConnectionProvidersErrors = {
+ 400: ErrorResponse;
+};
+
+export type EmailConnectionProvidersError = EmailConnectionProvidersErrors[keyof EmailConnectionProvidersErrors];
+
export type EmailConnectionProvidersResponses = {
200: EmailConnectionProviders;
};
diff --git a/packages/sdk/specs/auth.json b/packages/sdk/specs/auth.json
index 233035bf32..4aacf78ac8 100644
--- a/packages/sdk/specs/auth.json
+++ b/packages/sdk/specs/auth.json
@@ -1772,6 +1772,17 @@
"get": {
"tags": ["link::outlook"],
"operationId": "email_connection_providers",
+ "parameters": [
+ {
+ "name": "original_url",
+ "in": "query",
+ "description": "**OPTIONAL**. Where the admin-consent flow returns to; required for `outlook_admin_consent_url`.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
"responses": {
"200": {
"description": "",
@@ -1782,6 +1793,16 @@
}
}
}
+ },
+ "400": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
}
}
@@ -2832,6 +2853,9 @@
"200": {
"description": ""
},
+ "303": {
+ "description": "Back to the app with link identifiers, an `email_link_error`, or an `email_link_notice`"
+ },
"304": {
"description": "",
"content": {
@@ -5650,6 +5674,10 @@
},
"outlook": {
"type": "boolean"
+ },
+ "outlook_admin_consent_url": {
+ "type": ["string", "null"],
+ "description": "Where a Microsoft 365 administrator approves Macro for their whole\ndirectory. Present when Outlook is configured and the request named an\n`original_url` for the administrator's browser to return to."
}
}
},
diff --git a/services/authentication_service/AGENTS.md b/services/authentication_service/AGENTS.md
index 8633742263..25805e61f7 100644
--- a/services/authentication_service/AGENTS.md
+++ b/services/authentication_service/AGENTS.md
@@ -88,6 +88,12 @@ inputs cannot select an agent, and ordinary user credentials remain unattributed
when present; see `README.md` before changing signup behavior.
- Denial responses and policy errors must never disclose configured allowlist
addresses; never paste operational addresses into code, logs, or docs.
+- `/oauth2/{provider}/callback` verifies two signed `state` kinds
+ (`src/account_link_state.rs`): account links, which expire, and Microsoft
+ admin-consent returns, which do not. A consent screen that ends without a
+ code redirects a link flow to its `original_url` with `email_link_error`
+ (`admin_consent_required`, `cancelled`, `failed`); only the `AADSTS` code
+ from `error_description` is logged, never the description.
## Related
diff --git a/services/authentication_service/Cargo.toml b/services/authentication_service/Cargo.toml
index 8814790a91..2226145aa8 100644
--- a/services/authentication_service/Cargo.toml
+++ b/services/authentication_service/Cargo.toml
@@ -189,6 +189,7 @@ database_env_vars = { path = "../../crates/database_env_vars" }
[dev-dependencies]
cool_asserts = "2"
macro_db_migrator = { path = "../../crates/macro_db_migrator" }
+serde_urlencoded = { workspace = true }
[package.metadata.cargo-machete]
ignored = ["async-stripe"]
diff --git a/services/authentication_service/src/account_link_state.rs b/services/authentication_service/src/account_link_state.rs
index 363ff64e6e..8697acbe4f 100644
--- a/services/authentication_service/src/account_link_state.rs
+++ b/services/authentication_service/src/account_link_state.rs
@@ -11,6 +11,9 @@
//! The token is `base64url(payload).base64url(signature)`, without padding,
//! where the signature is HMAC-SHA256 over the encoded payload. This mirrors
//! the GitHub App installation state in the `github` crate.
+//!
+//! The same key signs the `state` of a Microsoft tenant-wide admin-consent
+//! request ([`AdminConsentState`]), which returns to the same callback.
use std::sync::Arc;
@@ -106,6 +109,45 @@ impl AccountLinkState {
}
}
+/// Signed `state` for a tenant-wide admin-consent request.
+///
+/// An administrator completes this flow from a copied link, often days later
+/// and from a different device, so it names no pending link or user and does
+/// not expire. The callback only redirects to the allow-listed `original_url`
+/// with the outcome, which is all a replay could do. The required `kind`
+/// field is what keeps an [`AccountLinkState`] token, which has none, from
+/// verifying as this type.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct AdminConsentState {
+ /// The payload discriminator; always [`AdminConsentKind::AdminConsent`].
+ pub kind: AdminConsentKind,
+ /// Which callback may complete this state.
+ pub provider: LinkProvider,
+ /// Where to send the browser once the administrator has answered.
+ pub original_url: String,
+}
+
+/// The `kind` of an [`AdminConsentState`] payload.
+///
+/// A one-variant enum rather than a `#[serde(tag)]` on the struct: serde
+/// writes a struct tag but does not check it when deserializing.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum AdminConsentKind {
+ AdminConsent,
+}
+
+/// What a signed `state` token verified as.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(untagged)]
+pub(crate) enum SignedState {
+ /// A tenant-wide admin-consent request. Tried first: its `kind` field is
+ /// required, so an account-link payload never matches.
+ AdminConsent(AdminConsentState),
+ /// A pending account link.
+ AccountLink(AccountLinkState),
+}
+
/// An error encountered while signing or verifying account-link state.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub(crate) enum AccountLinkStateError {
@@ -163,7 +205,22 @@ pub(crate) fn sign_account_link_state(
state: &AccountLinkState,
key: &AccountLinkStateKey,
) -> Result<String, AccountLinkStateError> {
- let json = serde_json::to_vec(state).map_err(|_| AccountLinkStateError::Serialization)?;
+ sign_payload(state, key)
+}
+
+/// Serialize and sign an admin-consent state.
+pub(crate) fn sign_admin_consent_state(
+ state: &AdminConsentState,
+ key: &AccountLinkStateKey,
+) -> Result<String, AccountLinkStateError> {
+ sign_payload(state, key)
+}
+
+fn sign_payload<T: Serialize>(
+ payload: &T,
+ key: &AccountLinkStateKey,
+) -> Result<String, AccountLinkStateError> {
+ let json = serde_json::to_vec(payload).map_err(|_| AccountLinkStateError::Serialization)?;
let encoded_payload = URL_SAFE_NO_PAD.encode(json);
let signature = signature_for(encoded_payload.as_bytes(), key);
@@ -173,17 +230,18 @@ pub(crate) fn sign_account_link_state(
))
}
-/// Verify and deserialize an account-link state token.
+/// Verify and deserialize a signed `state` token of either kind.
///
-/// `current_timestamp` is expressed in Unix seconds. A token is expired when
-/// the current timestamp is equal to or later than its `exp` value. The
+/// `current_timestamp` is expressed in Unix seconds. An account-link token is
+/// expired when the current timestamp is equal to or later than its `exp`
+/// value; admin-consent tokens do not expire (see [`AdminConsentState`]). The
/// signature is checked before the payload is decoded, so nothing in a
/// rejected token is ever interpreted.
-pub(crate) fn verify_account_link_state(
+pub(crate) fn verify_signed_state(
token: &str,
key: &AccountLinkStateKey,
current_timestamp: i64,
-) -> Result<AccountLinkState, AccountLinkStateError> {
+) -> Result<SignedState, AccountLinkStateError> {
let (encoded_payload, encoded_signature) = split_token(token)?;
let signature = URL_SAFE_NO_PAD
.decode(encoded_signature)
@@ -199,12 +257,14 @@ pub(crate) fn verify_account_link_state(
let json = URL_SAFE_NO_PAD
.decode(encoded_payload)
.map_err(|_| AccountLinkStateError::Malformed)?;
- let state: AccountLinkState =
+ let state: SignedState =
serde_json::from_slice(&json).map_err(|_| AccountLinkStateError::Malformed)?;
- if current_timestamp >= state.exp {
+ if let SignedState::AccountLink(link) = &state
+ && current_timestamp >= link.exp
+ {
return Err(AccountLinkStateError::Expired {
- link_id: state.link_id,
+ link_id: link.link_id,
});
}
diff --git a/services/authentication_service/src/account_link_state/test.rs b/services/authentication_service/src/account_link_state/test.rs
index d378c17d7d..fc98aca7e3 100644
--- a/services/authentication_service/src/account_link_state/test.rs
+++ b/services/authentication_service/src/account_link_state/test.rs
@@ -50,8 +50,8 @@ fn payload_round_trips_deterministically() {
assert_eq!(first_token, second_token);
assert!(!first_token.contains('='));
assert_eq!(
- verify_account_link_state(&first_token, &key(), NOW).unwrap(),
- payload
+ verify_signed_state(&first_token, &key(), NOW),
+ Ok(SignedState::AccountLink(payload))
);
}
@@ -62,8 +62,8 @@ fn payload_without_original_url_omits_the_field() {
assert!(!payload_json(&token).contains("original_url"));
assert_eq!(
- verify_account_link_state(&token, &key(), NOW).unwrap(),
- payload
+ verify_signed_state(&token, &key(), NOW),
+ Ok(SignedState::AccountLink(payload))
);
}
@@ -99,7 +99,7 @@ fn new_state_expires_one_ttl_from_now() {
assert!(state.exp >= before + ttl);
assert!(state.exp <= after + ttl);
assert!(
- verify_account_link_state(
+ verify_signed_state(
&sign_account_link_state(&state, &key()).unwrap(),
&key(),
after
@@ -113,12 +113,12 @@ fn expiration_boundary_is_enforced_and_names_the_pending_link() {
let token = sign_account_link_state(&state(None, NOW), &key()).unwrap();
assert_eq!(
- verify_account_link_state(&token, &key(), NOW - 1),
- Ok(state(None, NOW))
+ verify_signed_state(&token, &key(), NOW - 1),
+ Ok(SignedState::AccountLink(state(None, NOW)))
);
for current_timestamp in [NOW, NOW + 1] {
assert_eq!(
- verify_account_link_state(&token, &key(), current_timestamp),
+ verify_signed_state(&token, &key(), current_timestamp),
Err(AccountLinkStateError::Expired { link_id: link_id() })
);
}
@@ -137,14 +137,14 @@ fn malformed_tokens_are_rejected() {
r#"{"identity_provider_id":"idp","link_id":"0192b8a0-6a2e-7c3e-9b1f-4d5e6f708192"}"#,
] {
assert!(
- verify_account_link_state(token, &key(), NOW).is_err(),
+ verify_signed_state(token, &key(), NOW).is_err(),
"token should be rejected: {token}"
);
}
let malformed_json = sign_raw_payload(b"not json");
assert_eq!(
- verify_account_link_state(&malformed_json, &key(), NOW),
+ verify_signed_state(&malformed_json, &key(), NOW),
Err(AccountLinkStateError::Malformed)
);
}
@@ -169,7 +169,7 @@ fn authentic_payloads_with_bad_fields_are_rejected() {
payload[field] = value;
let token = sign_raw_payload(&serde_json::to_vec(&payload).unwrap());
assert_eq!(
- verify_account_link_state(&token, &key(), NOW),
+ verify_signed_state(&token, &key(), NOW),
Err(AccountLinkStateError::Malformed),
"{field} should be validated"
);
@@ -180,7 +180,7 @@ fn authentic_payloads_with_bad_fields_are_rejected() {
payload.as_object_mut().unwrap().remove(field);
let token = sign_raw_payload(&serde_json::to_vec(&payload).unwrap());
assert_eq!(
- verify_account_link_state(&token, &key(), NOW),
+ verify_signed_state(&token, &key(), NOW),
Err(AccountLinkStateError::Malformed),
"{field} should be required"
);
@@ -209,7 +209,7 @@ fn payload_tampering_is_rejected() {
let tampered_token = format!("{tampered_payload}.{encoded_signature}");
assert_eq!(
- verify_account_link_state(&tampered_token, &key(), NOW),
+ verify_signed_state(&tampered_token, &key(), NOW),
Err(AccountLinkStateError::InvalidSignature),
"changing {field} should invalidate the signature"
);
@@ -226,15 +226,61 @@ fn signature_tampering_and_wrong_keys_are_rejected() {
let other_key = AccountLinkStateKey::new("another secret that is also long enough").unwrap();
assert_eq!(
- verify_account_link_state(&tampered_token, &key(), NOW),
+ verify_signed_state(&tampered_token, &key(), NOW),
Err(AccountLinkStateError::InvalidSignature)
);
assert_eq!(
- verify_account_link_state(&token, &other_key, NOW),
+ verify_signed_state(&token, &other_key, NOW),
Err(AccountLinkStateError::InvalidSignature)
);
}
+fn admin_consent_state() -> AdminConsentState {
+ AdminConsentState {
+ kind: AdminConsentKind::AdminConsent,
+ provider: LinkProvider::Microsoft,
+ original_url: "https://macro.com/app/inbox-link-callback".into(),
+ }
+}
+
+#[test]
+fn admin_consent_state_round_trips_and_never_expires() {
+ let token = sign_admin_consent_state(&admin_consent_state(), &key()).unwrap();
+
+ let json: serde_json::Value = serde_json::from_str(&payload_json(&token)).unwrap();
+ assert_eq!(json["kind"], "admin_consent");
+ assert_eq!(json["provider"], "microsoft");
+ assert!(json.get("exp").is_none());
+ for current_timestamp in [NOW, NOW + 365 * 24 * 3_600] {
+ assert_eq!(
+ verify_signed_state(&token, &key(), current_timestamp),
+ Ok(SignedState::AdminConsent(admin_consent_state()))
+ );
+ }
+}
+
+#[test]
+fn signed_kinds_cannot_be_confused() {
+ // An admin-consent payload without its tag is neither kind.
+ let untagged = serde_json::json!({
+ "provider": "microsoft",
+ "original_url": "https://macro.com/app/inbox-link-callback",
+ });
+ let token = sign_raw_payload(&serde_json::to_vec(&untagged).unwrap());
+ assert_eq!(
+ verify_signed_state(&token, &key(), NOW),
+ Err(AccountLinkStateError::Malformed)
+ );
+
+ let mut mistagged = serde_json::to_value(admin_consent_state()).unwrap();
+ mistagged["kind"] = serde_json::json!("link");
+ let token = sign_raw_payload(&serde_json::to_vec(&mistagged).unwrap());
+ assert_eq!(
+ verify_signed_state(&token, &key(), NOW),
+ Err(AccountLinkStateError::Malformed)
+ );
+}
+
#[test]
fn keys_must_be_at_least_32_bytes() {
for secret in ["", " ", "short", &"x".repeat(MIN_SECRET_LENGTH - 1)] {
diff --git a/services/authentication_service/src/api/link/outlook.rs b/services/authentication_service/src/api/link/outlook.rs
index ad192da66e..e828ea1851 100644
--- a/services/authentication_service/src/api/link/outlook.rs
+++ b/services/authentication_service/src/api/link/outlook.rs
@@ -161,16 +161,63 @@ fn map_domain_error(error: MicrosoftAuthError) -> InitOutlookLinkError {
pub struct EmailConnectionProviders {
pub gmail: bool,
pub outlook: bool,
+ /// Where a Microsoft 365 administrator approves Macro for their whole
+ /// directory. Present when Outlook is configured and the request named an
+ /// `original_url` for the administrator's browser to return to.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub outlook_admin_consent_url: Option<String>,
}
-#[utoipa::path(get,operation_id="email_connection_providers",path="/link/email/providers",responses((status=200,body=EmailConnectionProviders)))]
+
+#[derive(Debug, serde::Deserialize)]
+pub(crate) struct EmailConnectionProvidersQueryParams {
+ original_url: Option<Url>,
+}
+
+#[utoipa::path(
+ get,
+ operation_id = "email_connection_providers",
+ path = "/link/email/providers",
+ params(
+ ("original_url" = Option<String>, Query, description = "**OPTIONAL**. Where the admin-consent flow returns to; required for `outlook_admin_consent_url`."),
+ ),
+ responses(
+ (status = 200, body = EmailConnectionProviders),
+ (status = 400, body = ErrorResponse),
+ )
+)]
pub async fn email_connection_providers(
State(ctx): State<ApiContext>,
-) -> Json<EmailConnectionProviders> {
- Json(EmailConnectionProviders {
+ Query(EmailConnectionProvidersQueryParams { original_url }): Query<
+ EmailConnectionProvidersQueryParams,
+ >,
+) -> Result<Json<EmailConnectionProviders>, InitOutlookLinkError> {
+ if original_url
+ .as_ref()
+ .is_some_and(|url| !crate::api::login::sso::is_allowed_original_url(url))
+ {
+ return Err(InitOutlookLinkError::InvalidReturnUrl);
+ }
+ // The consent URL is an optional extra; a failure to sign it must not hide
+ // which providers are available.
+ let outlook_admin_consent_url = match (&ctx.microsoft_auth, original_url) {
+ (Some(service), Some(original_url)) => service
+ .admin_consent_url(
+ &format_redirect_uri("microsoft"),
+ original_url.as_str(),
+ ctx.calendar_scope_enabled,
+ )
+ .inspect_err(|error| {
+ tracing::warn!(error=?error, "unable to build Outlook admin-consent URL");
+ })
+ .ok(),
+ _ => None,
+ };
+ Ok(Json(EmailConnectionProviders {
gmail: true,
outlook: ctx
.microsoft_auth
.as_ref()
.is_some_and(|service| service.new_connections_enabled()),
- })
+ outlook_admin_consent_url,
+ }))
}
diff --git a/services/authentication_service/src/api/oauth2.rs b/services/authentication_service/src/api/oauth2.rs
index 00b93e91da..773b0e15bc 100644
--- a/services/authentication_service/src/api/oauth2.rs
+++ b/services/authentication_service/src/api/oauth2.rs
@@ -1,7 +1,7 @@
use crate::{
account_link_state::{
- AccountLinkState, AccountLinkStateError, AccountLinkStateKey, LinkProvider,
- verify_account_link_state,
+ AccountLinkState, AccountLinkStateError, AccountLinkStateKey, AdminConsentState,
+ LinkProvider, SignedState, verify_signed_state,
},
api::login::sso::{is_allowed_original_url, redact_original_url_for_logging},
config::BASE_URL,
@@ -78,6 +78,8 @@ impl From<&AccountLinkState> for OAuthState {
enum CallbackState {
/// A signed token issued by one of the `/link/*` handlers.
AccountLink(AccountLinkState),
+ /// A signed token issued with a tenant-wide admin-consent URL.
+ AdminConsent(AdminConsentState),
/// Unsigned sign-in state. Never carries a `link_id`.
Login(OAuthState),
}
@@ -86,11 +88,74 @@ impl CallbackState {
fn original_url(&self) -> Option<&str> {
match self {
Self::AccountLink(state) => state.original_url.as_deref(),
+ Self::AdminConsent(state) => Some(&state.original_url),
Self::Login(state) => state.original_url.as_deref(),
}
}
}
+/// Why a consent screen came back without an authorization code.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ConsentFailure {
+ /// The directory lets only an administrator consent to Macro's permissions.
+ AdminConsentRequired,
+ /// The person on the consent screen declined or closed it.
+ Cancelled,
+ /// Anything else the provider reported.
+ Failed,
+}
+
+impl ConsentFailure {
+ /// Classifies the provider's `error` and `error_description`.
+ ///
+ /// Entra reports "Need admin approval" as `access_denied` with
+ /// `AADSTS65001` in the description (`AADSTS90094` for the admin-consent
+ /// endpoint itself); some tenants answer `consent_required` or
+ /// `interaction_required` instead.
+ fn classify(error: Option<&str>, error_description: Option<&str>) -> Self {
+ let code = error_description.and_then(aadsts_code);
+ if matches!(code, Some("AADSTS65001" | "AADSTS90094"))
+ || matches!(error, Some("consent_required" | "interaction_required"))
+ {
+ return Self::AdminConsentRequired;
+ }
+ if error == Some("access_denied") {
+ return Self::Cancelled;
+ }
+ Self::Failed
+ }
+
+ /// The `email_link_error` query value the app reads.
+ fn as_str(self) -> &'static str {
+ match self {
+ Self::AdminConsentRequired => "admin_consent_required",
+ Self::Cancelled => "cancelled",
+ Self::Failed => "failed",
+ }
+ }
+}
+
+/// The `AADSTS` error code at the start of an Entra `error_description`, such
+/// as `AADSTS65001`. Only the code is kept: the rest of the description names
+/// the user, the app, and the tenant.
+fn aadsts_code(error_description: &str) -> Option<&str> {
+ let start = error_description.find("AADSTS")?;
+ let code = &error_description[start..];
+ let end = code["AADSTS".len()..]
+ .find(|character: char| !character.is_ascii_digit())
+ .map_or(code.len(), |digits| "AADSTS".len() + digits);
+ Some(&code[..end]).filter(|code| code.len() > "AADSTS".len())
+}
+
+/// The `provider` query value the app reads, named for the inbox provider.
+fn provider_query_value(provider: LinkProvider) -> &'static str {
+ match provider {
+ LinkProvider::Google => "gmail",
+ LinkProvider::Github => "github",
+ LinkProvider::Microsoft => "outlook",
+ }
+}
+
#[derive(Debug, PartialEq, Eq)]
enum CallbackStateError {
/// A signed token that failed verification.
@@ -127,15 +192,23 @@ fn parse_callback_state(
return Ok(CallbackState::Login(state));
}
- let state = verify_account_link_state(raw, key, current_timestamp)
- .map_err(CallbackStateError::Signed)?;
- if state.provider.as_str() != provider {
- return Err(CallbackStateError::ProviderMismatch {
- issued_for: state.provider,
- });
+ let (state, issued_for) = match verify_signed_state(raw, key, current_timestamp)
+ .map_err(CallbackStateError::Signed)?
+ {
+ SignedState::AccountLink(state) => {
+ let issued_for = state.provider;
+ (CallbackState::AccountLink(state), issued_for)
+ }
+ SignedState::AdminConsent(state) => {
+ let issued_for = state.provider;
+ (CallbackState::AdminConsent(state), issued_for)
+ }
+ };
+ if issued_for.as_str() != provider {
+ return Err(CallbackStateError::ProviderMismatch { issued_for });
}
- Ok(CallbackState::AccountLink(state))
+ Ok(state)
}
#[derive(Debug, serde::Deserialize)]
@@ -150,6 +223,9 @@ pub(in crate::api) struct Params {
error_description: Option<String>,
#[serde(default)]
error_reason: Option<String>,
+ /// `True` when a Microsoft administrator granted tenant-wide consent.
+ #[serde(default)]
+ admin_consent: Option<String>,
}
#[derive(Debug, serde::Deserialize)]
@@ -234,6 +310,70 @@ async fn verify_pending_link_owner(
Ok(())
}
+/// Sends the administrator's browser back to the app with the result of a
+/// tenant-wide consent request. Microsoft reports success with
+/// `admin_consent=True` and a refusal with `error`; neither carries a code.
+fn admin_consent_outcome(params: &Params, consent: &AdminConsentState) -> Response {
+ let provider = provider_query_value(consent.provider);
+ let granted = params
+ .admin_consent
+ .as_deref()
+ .is_some_and(|value| value.eq_ignore_ascii_case("true"));
+ let outcome: (&str, &str) = if granted {
+ tracing::info!(provider, "admin consent granted");
+ ("email_link_notice", "admin_consent_granted")
+ } else {
+ let failure =
+ ConsentFailure::classify(params.error.as_deref(), params.error_description.as_deref());
+ tracing::info!(
+ provider,
+ error = ?params.error,
+ aadsts_code = params.error_description.as_deref().and_then(aadsts_code),
+ outcome = failure.as_str(),
+ "admin consent not granted"
+ );
+ ("email_link_error", failure.as_str())
+ };
+ account_link::build_return_redirect(&consent.original_url, &[outcome, ("provider", provider)])
+ .unwrap_or_else(IntoResponse::into_response)
+}
+
+/// Answers a consent screen that came back without an authorization code.
+///
+/// A link flow started from a page in the app, which explains the outcome in
+/// place, so it is sent back there with an `email_link_error`. Sign-in has no
+/// such page and keeps the error body.
+fn consent_failure_response(link_state: Option<&AccountLinkState>, params: &Params) -> Response {
+ let failure =
+ ConsentFailure::classify(params.error.as_deref(), params.error_description.as_deref());
+ tracing::info!(
+ error = ?params.error,
+ error_reason = ?params.error_reason,
+ aadsts_code = params.error_description.as_deref().and_then(aadsts_code),
+ outcome = failure.as_str(),
+ "oauth2 callback received without code"
+ );
+
+ if let Some(link_state) = link_state
+ && let Some(original_url) = &link_state.original_url
+ {
+ return account_link::build_return_redirect(
+ original_url,
+ &[
+ ("link_id", &link_state.link_id.to_string()),
+ ("email_link_error", failure.as_str()),
+ ("provider", provider_query_value(link_state.provider)),
+ ],
+ )
+ .unwrap_or_else(IntoResponse::into_response);
+ }
+
+ error_response(
+ StatusCode::BAD_REQUEST,
+ "Sign-in failed. Please try again or contact support.",
+ )
+}
+
/// Custom OAuth2 callback
#[utoipa::path(
get,
@@ -244,6 +384,7 @@ async fn verify_pending_link_owner(
operation_id = "oauth2_callback",
responses(
(status = 200),
+ (status = 303, description = "Back to the app with link identifiers, an `email_link_error`, or an `email_link_notice`"),
(status = 307),
(status = 304, body=ErrorResponse),
(status = 400, body=ErrorResponse),
@@ -320,37 +461,32 @@ pub(in crate::api) async fn handler(
)
})?;
- let code = match params.code {
- Some(c) => c,
- None => {
- tracing::warn!(
- error = ?params.error,
- error_reason = ?params.error_reason,
- error_description = ?params.error_description,
- "oauth2 callback received without code",
- );
- return Err(error_response(
- StatusCode::BAD_REQUEST,
- "Sign-in failed. Please try again or contact support.",
- ));
+ let (link_state, state) = match state {
+ CallbackState::AdminConsent(consent) => {
+ return Ok(admin_consent_outcome(&params, &consent));
}
- };
-
- let state = match state {
- CallbackState::Login(state) => state,
+ CallbackState::Login(state) => (None, state),
CallbackState::AccountLink(link_state) => {
- verify_pending_link_owner(&ctx, &link_state).await?;
- OAuthState::from(&link_state)
+ let state = OAuthState::from(&link_state);
+ (Some(link_state), state)
}
};
+ let Some(code) = params.code.as_deref() else {
+ return Ok(consent_failure_response(link_state.as_ref(), &params));
+ };
+
+ if let Some(link_state) = &link_state {
+ verify_pending_link_owner(&ctx, link_state).await?;
+ }
+
match provider.as_str() {
- "google" => google::handler(&ctx, cookies, &code, &state).await,
- "github" => github::handler(&ctx, cookies, &code, &state)
+ "google" => google::handler(&ctx, cookies, code, &state).await,
+ "github" => github::handler(&ctx, cookies, code, &state)
.await
.map(|r| r.into_response())
.map_err(|e| e.into_response()),
- "microsoft" => microsoft::handler(&ctx, &code, &state).await,
+ "microsoft" => microsoft::handler(&ctx, code, &state).await,
_ => Err(error_response(
StatusCode::NOT_IMPLEMENTED,
"oauth2 callback not implemented for this provider",
diff --git a/services/authentication_service/src/api/oauth2/account_link.rs b/services/authentication_service/src/api/oauth2/account_link.rs
index 39eae1a5df..b7ff1665b8 100644
--- a/services/authentication_service/src/api/oauth2/account_link.rs
+++ b/services/authentication_service/src/api/oauth2/account_link.rs
@@ -154,10 +154,30 @@ pub(super) async fn replace_identity_provider_grant(
swap_result
}
+/// Query keys the callback owns on the return URL. Replaced, never duplicated,
+/// so a return URL that already carries a previous outcome does not keep it.
+const CALLBACK_QUERY_KEYS: [&str; 5] = [
+ "link_id",
+ "token",
+ "email_link_error",
+ "email_link_notice",
+ "provider",
+];
+
/// Builds the redirect back to an account-link caller with fresh link identifiers.
pub(super) fn build_callback_redirect(
original_url: &str,
link_id: &Uuid,
+) -> Result<Response, CallbackRedirectError> {
+ let link_id = link_id.to_string();
+ build_return_redirect(original_url, &[("link_id", &link_id), ("token", &link_id)])
+}
+
+/// Builds the redirect back to the caller's return URL carrying `outcome`
+/// query pairs, such as a consent error or an admin-consent notice.
+pub(super) fn build_return_redirect(
+ original_url: &str,
+ outcome: &[(&str, &str)],
) -> Result<Response, CallbackRedirectError> {
let decoded_url = urlencoding::decode(original_url).map_err(|error| {
tracing::error!(error=?error, "unable to decode original url");
@@ -171,17 +191,13 @@ pub(super) fn build_callback_redirect(
let preserved_query_pairs: Vec<(String, String)> = url
.query_pairs()
- .filter(|(key, _)| key != "link_id" && key != "token")
+ .filter(|(key, _)| !CALLBACK_QUERY_KEYS.contains(&key.as_ref()))
.map(|(key, value)| (key.into_owned(), value.into_owned()))
.collect();
url.query_pairs_mut()
.clear()
- .extend_pairs(preserved_query_pairs);
-
- let link_id = link_id.to_string();
- url.query_pairs_mut()
- .append_pair("link_id", &link_id)
- .append_pair("token", &link_id);
+ .extend_pairs(preserved_query_pairs)
+ .extend_pairs(outcome);
Ok(Redirect::to(url.as_str()).into_response())
}
diff --git a/services/authentication_service/src/api/oauth2/account_link/test.rs b/services/authentication_service/src/api/oauth2/account_link/test.rs
index 9e42cb4927..05e036d870 100644
--- a/services/authentication_service/src/api/oauth2/account_link/test.rs
+++ b/services/authentication_service/src/api/oauth2/account_link/test.rs
@@ -2,7 +2,7 @@ use axum::http::{StatusCode, header::LOCATION};
use url::Url;
use uuid::Uuid;
-use super::build_callback_redirect;
+use super::{build_callback_redirect, build_return_redirect};
#[test]
fn callback_redirect_appends_link_identifiers_and_preserves_query_parameters() {
@@ -25,6 +25,40 @@ fn callback_redirect_appends_link_identifiers_and_preserves_query_parameters() {
);
}
+#[test]
+fn return_redirect_replaces_a_previous_outcome_and_keeps_the_rest() {
+ let original_url = urlencoding::encode(
+ "macro:///inbox-link-callback?email_link_error=cancelled&provider=gmail&token=stale&view=all",
+ );
+
+ let response = build_return_redirect(
+ &original_url,
+ &[
+ ("link_id", "694d20f7-ff85-46fd-b17d-5f68ff2d3707"),
+ ("email_link_error", "admin_consent_required"),
+ ("provider", "outlook"),
+ ],
+ )
+ .unwrap();
+ let redirect_url = Url::parse(response.headers()[LOCATION].to_str().unwrap()).unwrap();
+ let query_pairs: Vec<_> = redirect_url.query_pairs().collect();
+
+ assert_eq!(response.status(), StatusCode::SEE_OTHER);
+ assert_eq!(redirect_url.scheme(), "macro");
+ assert_eq!(
+ query_pairs,
+ vec![
+ ("view".into(), "all".into()),
+ (
+ "link_id".into(),
+ "694d20f7-ff85-46fd-b17d-5f68ff2d3707".into()
+ ),
+ ("email_link_error".into(), "admin_consent_required".into()),
+ ("provider".into(), "outlook".into()),
+ ]
+ );
+}
+
#[test]
fn callback_redirect_replaces_stale_link_identifiers() {
let link_id = Uuid::parse_str("694d20f7-ff85-46fd-b17d-5f68ff2d3707").unwrap();
diff --git a/services/authentication_service/src/api/oauth2/test.rs b/services/authentication_service/src/api/oauth2/test.rs
index cd360e13c2..951171baa1 100644
--- a/services/authentication_service/src/api/oauth2/test.rs
+++ b/services/authentication_service/src/api/oauth2/test.rs
@@ -59,7 +59,10 @@ fn callback_original_url_rejects_invalid_urls() {
assert!(validate_original_url(None).is_ok());
}
-use crate::account_link_state::{AccountLinkState, AccountLinkStateKey, sign_account_link_state};
+use crate::account_link_state::{
+ AccountLinkState, AccountLinkStateKey, AdminConsentKind, sign_account_link_state,
+ sign_admin_consent_state,
+};
use uuid::Uuid;
const NOW: i64 = 1_730_000_000;
@@ -247,6 +250,172 @@ fn callback_accepts_unsigned_state_only_for_sign_in() {
);
}
+#[test]
+fn consent_failures_are_classified_from_entra_errors() {
+ for (error, description, expected) in [
+ (
+ Some("access_denied"),
+ Some(
+ "AADSTS65001: The user or administrator has not consented to use the application with ID 'a1b2' named 'Macro'. Send an interactive authorization request for this user and resource.",
+ ),
+ ConsentFailure::AdminConsentRequired,
+ ),
+ (
+ Some("access_denied"),
+ Some("AADSTS90094: The grant requires admin permission."),
+ ConsentFailure::AdminConsentRequired,
+ ),
+ (
+ Some("consent_required"),
+ None,
+ ConsentFailure::AdminConsentRequired,
+ ),
+ (
+ Some("interaction_required"),
+ Some("AADSTS50076: MFA required"),
+ ConsentFailure::AdminConsentRequired,
+ ),
+ (
+ Some("access_denied"),
+ Some("AADSTS65004: User declined to consent to access the app."),
+ ConsentFailure::Cancelled,
+ ),
+ (Some("access_denied"), None, ConsentFailure::Cancelled),
+ (
+ Some("server_error"),
+ Some("AADSTS90033: A transient error has occurred."),
+ ConsentFailure::Failed,
+ ),
+ (Some("invalid_request"), None, ConsentFailure::Failed),
+ (None, None, ConsentFailure::Failed),
+ ] {
+ assert_eq!(
+ ConsentFailure::classify(error, description),
+ expected,
+ "{error:?} / {description:?}"
+ );
+ }
+}
+
+#[test]
+fn aadsts_codes_are_extracted_without_the_rest_of_the_description() {
+ assert_eq!(
+ aadsts_code(
+ "AADSTS65001: The user or administrator has not consented to use the application with ID 'a1b2' named 'Macro' for user [email protected]."
+ ),
+ Some("AADSTS65001")
+ );
+ assert_eq!(
+ aadsts_code("Error: AADSTS90094 Trace ID: 0000"),
+ Some("AADSTS90094")
+ );
+ assert_eq!(aadsts_code("AADSTS"), None);
+ assert_eq!(aadsts_code("User declined"), None);
+}
+
+#[test]
+fn callback_accepts_signed_admin_consent_state_for_its_provider() {
+ let consent = AdminConsentState {
+ kind: AdminConsentKind::AdminConsent,
+ provider: LinkProvider::Microsoft,
+ original_url: "https://macro.com/app/inbox-link-callback".into(),
+ };
+ let token = sign_admin_consent_state(&consent, &key()).unwrap();
+
+ match parse_callback_state(&token, "microsoft", &key(), NOW).unwrap() {
+ CallbackState::AdminConsent(verified) => assert_eq!(verified, consent),
+ other => panic!("expected admin consent state, got {other:?}"),
+ }
+ assert_eq!(
+ parse_callback_state(&token, "google", &key(), NOW).unwrap_err(),
+ CallbackStateError::ProviderMismatch {
+ issued_for: LinkProvider::Microsoft
+ }
+ );
+}
+
+fn redirect_query(response: Response) -> Vec<(String, String)> {
+ assert_eq!(response.status(), StatusCode::SEE_OTHER);
+ let location = response.headers()[axum::http::header::LOCATION]
+ .to_str()
+ .unwrap()
+ .to_owned();
+ Url::parse(&location)
+ .unwrap()
+ .query_pairs()
+ .into_owned()
+ .collect()
+}
+
+fn params(query: &str) -> Params {
+ serde_urlencoded::from_str(query).unwrap()
+}
+
+#[test]
+fn admin_consent_return_redirects_to_the_app_with_the_outcome() {
+ let consent = AdminConsentState {
+ kind: AdminConsentKind::AdminConsent,
+ provider: LinkProvider::Microsoft,
+ original_url: "https://macro.com/app/inbox-link-callback?view=all".into(),
+ };
+
+ let granted = admin_consent_outcome(
+ &params("state=s&admin_consent=True&tenant=cfc674f9-d10b-4b48-a2be-d018a76a6c27"),
+ &consent,
+ );
+ assert_eq!(
+ redirect_query(granted),
+ vec![
+ ("view".into(), "all".into()),
+ ("email_link_notice".into(), "admin_consent_granted".into()),
+ ("provider".into(), "outlook".into()),
+ ]
+ );
+
+ let declined = admin_consent_outcome(
+ &params(
+ "state=s&error=access_denied&error_description=AADSTS65004%3A+User+declined+to+consent",
+ ),
+ &consent,
+ );
+ assert_eq!(
+ redirect_query(declined),
+ vec![
+ ("view".into(), "all".into()),
+ ("email_link_error".into(), "cancelled".into()),
+ ("provider".into(), "outlook".into()),
+ ]
+ );
+}
+
+#[test]
+fn consent_failure_sends_a_link_flow_back_to_the_app() {
+ let link = link_state(LinkProvider::Microsoft, NOW + 60);
+
+ let response = consent_failure_response(
+ Some(&link),
+ &params(
+ "state=s&error=access_denied&error_description=AADSTS65001%3A+The+user+or+administrator+has+not+consented",
+ ),
+ );
+
+ assert_eq!(
+ redirect_query(response),
+ vec![
+ ("link_id".into(), link.link_id.to_string()),
+ ("email_link_error".into(), "admin_consent_required".into()),
+ ("provider".into(), "outlook".into()),
+ ]
+ );
+}
+
+#[test]
+fn consent_failure_during_sign_in_keeps_the_error_body() {
+ let response = consent_failure_response(None, &params("state=s&error=access_denied"));
+
+ assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
#[test]
fn verified_link_state_converts_to_provider_handler_state() {
let link = link_state(LinkProvider::Microsoft, NOW + 60);
diff --git a/services/authentication_service/src/domain/microsoft.rs b/services/authentication_service/src/domain/microsoft.rs
index 590d0d425f..85b9070869 100644
--- a/services/authentication_service/src/domain/microsoft.rs
+++ b/services/authentication_service/src/domain/microsoft.rs
@@ -191,6 +191,15 @@ pub trait MicrosoftGrantRepository: Send + Sync {
pub trait MicrosoftIdentityProvider: Send + Sync {
async fn identity_provider_id(&self) -> Result<String, MicrosoftAuthError>;
fn authorize(&self, attempt: &LinkAttempt) -> Result<String, MicrosoftAuthError>;
+ /// The tenant-wide consent page an administrator completes when their
+ /// directory refuses user consent; Microsoft returns to `redirect_uri`,
+ /// which then sends the browser on to `return_uri`.
+ fn admin_consent_url(
+ &self,
+ redirect_uri: &str,
+ return_uri: &str,
+ calendar: bool,
+ ) -> Result<String, MicrosoftAuthError>;
async fn exchange(
&self,
attempt: &LinkAttempt,
@@ -205,6 +214,14 @@ pub trait MicrosoftIdentityProvider: Send + Sync {
#[async_trait::async_trait]
pub trait MicrosoftAuth: Send + Sync {
fn new_connections_enabled(&self) -> bool;
+ /// Where an administrator grants Macro's delegated permissions for their
+ /// whole directory, for users whose consent attempt needs admin approval.
+ fn admin_consent_url(
+ &self,
+ redirect_uri: &str,
+ return_uri: &str,
+ calendar: bool,
+ ) -> Result<String, MicrosoftAuthError>;
async fn revoke_released_grant(
&self,
id: Uuid,
@@ -335,6 +352,15 @@ impl<R: MicrosoftGrantRepository, P: MicrosoftIdentityProvider> MicrosoftAuth
fn new_connections_enabled(&self) -> bool {
self.connections_enabled
}
+ fn admin_consent_url(
+ &self,
+ redirect_uri: &str,
+ return_uri: &str,
+ calendar: bool,
+ ) -> Result<String, MicrosoftAuthError> {
+ self.provider
+ .admin_consent_url(redirect_uri, return_uri, calendar)
+ }
async fn revoke_released_grant(
&self,
id: Uuid,
diff --git a/services/authentication_service/src/outbound/microsoft.rs b/services/authentication_service/src/outbound/microsoft.rs
index ea4e355a72..9d42558024 100644
--- a/services/authentication_service/src/outbound/microsoft.rs
+++ b/services/authentication_service/src/outbound/microsoft.rs
@@ -2,7 +2,8 @@
use crate::{
account_link_state::{
- AccountLinkState, AccountLinkStateKey, LinkProvider, sign_account_link_state,
+ AccountLinkState, AccountLinkStateKey, AdminConsentKind, AdminConsentState, LinkProvider,
+ sign_account_link_state, sign_admin_consent_state,
},
domain::microsoft::{token::MicrosoftRefreshToken, *},
};
@@ -62,6 +63,24 @@ impl MicrosoftIdentityProvider for MicrosoftOAuthProvider {
.map_err(|_| MicrosoftAuthError::NotConfigured)
}
+ fn admin_consent_url(
+ &self,
+ redirect_uri: &str,
+ return_uri: &str,
+ calendar: bool,
+ ) -> Result<String, MicrosoftAuthError> {
+ let state = AdminConsentState {
+ kind: AdminConsentKind::AdminConsent,
+ provider: LinkProvider::Microsoft,
+ original_url: return_uri.to_owned(),
+ };
+ let state = sign_admin_consent_state(&state, &self.state_key)
+ .map_err(|_| MicrosoftAuthError::Unavailable)?;
+ self.client
+ .construct_microsoft_admin_consent_url(redirect_uri, &state, calendar)
+ .map_err(|_| MicrosoftAuthError::NotConfigured)
+ }
+
async fn exchange(
&self,
attempt: &LinkAttempt,