fastmail-mcp-server 0.2.2 → 0.4.1

package/README.md

@@ -4,12 +4,15 @@ MCP server for Fastmail. Read, search, organize, and send emails through Claude
 
 ## Features
 
-- **Full read/write** - list, search, send, reply, move, mark as spam
+- **Full read/write** - list, search, send, reply, forward, move, mark as spam
 - **Safe sending** - preview→confirm flow prevents accidental sends
+- **Masked emails** - create/manage disposable email addresses
+- **Advanced search** - filter by date, sender, attachments, unread, flagged status
+- **Thread support** - get_email returns full conversation context
 - **Attachment text extraction** - PDFs, Word docs, Excel, PowerPoint extracted as readable text
 - **Legacy .doc support** - uses macOS `textutil` for old Word formats
 - **Image attachments** - returned as viewable content for Claude's built-in OCR
-- **CC/BCC support** - full addressing on send and reply
+- **CC/BCC support** - full addressing on send, reply, and forward
 
 ### Comparison
 
@@ -17,12 +20,16 @@ MCP server for Fastmail. Read, search, organize, and send emails through Claude
 | --------------------------------- | :----------: | :-----: | :---------: |
 | Read emails                       |      ✅      |   ✅    |     ✅      |
 | Search emails                     |      ✅      |   ✅    |     ✅      |
+| Advanced search filters           |      ✅      |   ❌    |     ❌      |
 | Send emails                       |      ✅      |   ❌    |     ✅      |
 | Reply to threads                  |      ✅      |   ❌    |     ❌      |
+| Forward emails                    |      ✅      |   ❌    |     ❌      |
 | CC/BCC support                    |      ✅      |   ❌    |     ✅      |
 | Safe send (preview→confirm)       |      ✅      |   ❌    |     ❌      |
 | Move/organize emails              |      ✅      |   ❌    |     ❌      |
 | Mark as spam                      |      ✅      |   ❌    |     ❌      |
+| **Masked emails**                 |      ✅      |   ❌    |     ❌      |
+| **Thread context**                |      ✅      |   ❌    |     ❌      |
 | List attachments                  |      ✅      |   ❌    |     ❌      |
 | **Extract text from PDF/DOCX**    |      ✅      |   ❌    |     ❌      |
 | **Extract text from legacy .doc** |      ✅      |   ❌    |     ❌      |
@@ -59,6 +66,16 @@ Token format: `fmu1-xxxxxxxx-xxxxxxxxxxxx...`
 
 ### 2. Configure Claude Desktop
 
+Install the server globally:
+
+```bash
+# Via mise (recommended)
+mise use -g npm:fastmail-mcp-server
+
+# Or via npm
+npm install -g fastmail-mcp-server
+```
+
 Open the Claude Desktop config file:
 
 ```bash
@@ -76,8 +93,7 @@ Add the fastmail server config:
 {
   "mcpServers": {
     "fastmail": {
-      "command": "bunx",
-      "args": ["-y", "fastmail-mcp-server"],
+      "command": "fastmail-mcp-server",
       "env": {
         "FASTMAIL_API_TOKEN": "fmu1-your-token-here"
       }
@@ -86,6 +102,8 @@ Add the fastmail server config:
 }
 ```
 
+> **Note:** If Claude Desktop can't find the command, use the full path from `which fastmail-mcp-server`
+
 ### 3. Restart Claude Desktop
 
 Quit Claude Desktop completely (Cmd+Q) and reopen it. The Fastmail tools should now appear.
@@ -142,6 +160,17 @@ Claude receives actual text content, not binary blobs - just like when you drag-
 | `mark_as_spam`   | Move to Junk + train filter  | **Yes**      |
 | `send_email`     | Send a new email             | **Yes**      |
 | `reply_to_email` | Reply to an email thread     | **Yes**      |
+| `forward_email`  | Forward an email             | **Yes**      |
+
+### Masked Email Operations
+
+| Tool                   | Description                        |
+| ---------------------- | ---------------------------------- |
+| `list_masked_emails`   | List all masked email addresses    |
+| `create_masked_email`  | Create a new disposable address    |
+| `enable_masked_email`  | Re-enable a disabled masked email  |
+| `disable_masked_email` | Stop receiving at a masked address |
+| `delete_masked_email`  | Permanently delete a masked email  |
 
 ## Example Prompts
 
@@ -152,13 +181,23 @@ Claude receives actual text content, not binary blobs - just like when you drag-
 
 "Search for emails from john@example.com"
 
+"Find unread emails from last week with attachments"
+
+"Show me flagged emails from December"
+
 "What would be a good response to the latest email from the solicitor?"
 
 "Draft a reply to that insurance email explaining the situation"
 
+"Forward that receipt to my accountant"
+
 "Move all the newsletters to Archive"
 
 "Mark that spam email as junk"
+
+"Create a masked email for signing up to this sketchy website"
+
+"List my masked emails and disable the one for that service I cancelled"
 ```
 
 ## Troubleshooting

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "fastmail-mcp-server",
-  "version": "0.2.2",
+  "version": "0.4.1",
   "description": "MCP server for Fastmail - read, search, and send emails via Claude",
   "type": "module",
   "main": "src/index.ts",
+  "bin": {
+    "fastmail-mcp-server": "src/index.ts"
+  },
   "files": [
     "src/**/*"
   ],

package/src/index.ts

@@ -7,24 +7,34 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { parseOffice } from "officeparser";
 import { z } from "zod";
 import {
+	buildForward,
 	buildReply,
+	createMaskedEmail,
 	downloadAttachment,
 	getAttachments,
 	getEmail,
 	getMailboxByName,
+	getThreadEmails,
 	listEmails,
 	listMailboxes,
+	listMaskedEmails,
 	markAsRead,
 	markAsSpam,
 	moveEmail,
 	searchEmails,
 	sendEmail,
+	updateMaskedEmail,
 } from "./jmap/methods.js";
-import type { Email, EmailAddress, Mailbox } from "./jmap/types.js";
+import type {
+	Email,
+	EmailAddress,
+	Mailbox,
+	MaskedEmail,
+} from "./jmap/types.js";
 
 const server = new McpServer({
 	name: "fastmail",
-	version: "0.2.2",
+	version: "0.4.0",
 });
 
 // ============ Formatters ============
@@ -145,7 +155,7 @@ server.tool(
 
 server.tool(
 	"get_email",
-	"Get the full content of a specific email by its ID. Returns complete email with headers, body text, and attachment info.",
+	"Get the full content of a specific email by its ID. Automatically includes the full thread context (all emails in the conversation) sorted oldest-first.",
 	{
 		email_id: z
 			.string()
@@ -162,33 +172,106 @@ server.tool(
 			};
 		}
 
-		const text = formatEmailFull(email);
-		return { content: [{ type: "text" as const, text }] };
+		// Get full thread context
+		const threadEmails = await getThreadEmails(email.threadId);
+
+		if (threadEmails.length <= 1) {
+			// Single email, no thread
+			const text = formatEmailFull(email);
+			return { content: [{ type: "text" as const, text }] };
+		}
+
+		// Format thread with all emails
+		const threadText = threadEmails
+			.map((e, i) => {
+				const marker = e.id === email_id ? ">>> SELECTED EMAIL <<<\n" : "";
+				return `${marker}[${i + 1}/${threadEmails.length}]\n${formatEmailFull(e)}`;
+			})
+			.join("\n\n========== THREAD ==========\n\n");
+
+		return {
+			content: [
+				{
+					type: "text" as const,
+					text: `Thread contains ${threadEmails.length} emails:\n\n${threadText}`,
+				},
+			],
+		};
 	},
 );
 
 server.tool(
 	"search_emails",
-	"Search for emails across all mailboxes. Supports full-text search of email content, subjects, and addresses.",
+	"Search for emails with flexible filters. Use 'query' for general search, or specific fields for precise filtering. Supports date ranges, attachment filtering, unread/flagged status.",
 	{
 		query: z
 			.string()
-			.describe(
-				"Search query - searches subject, body, and addresses. Examples: 'from:alice@example.com', 'subject:invoice', 'meeting notes'",
-			),
+			.optional()
+			.describe("General search - searches subject, body, from, and to fields"),
+		from: z.string().optional().describe("Search sender address/name"),
+		to: z.string().optional().describe("Search recipient address/name"),
+		cc: z.string().optional().describe("Search CC recipients"),
+		subject: z.string().optional().describe("Search subject line only"),
+		body: z.string().optional().describe("Search email body only"),
+		mailbox: z
+			.string()
+			.optional()
+			.describe("Limit search to a specific mailbox/folder"),
+		has_attachment: z
+			.boolean()
+			.optional()
+			.describe("Only emails with attachments"),
+		before: z
+			.string()
+			.optional()
+			.describe("Emails before this date (YYYY-MM-DD or ISO 8601)"),
+		after: z
+			.string()
+			.optional()
+			.describe("Emails after this date (YYYY-MM-DD or ISO 8601)"),
+		unread: z.boolean().optional().describe("Only unread emails"),
+		flagged: z.boolean().optional().describe("Only flagged/starred emails"),
 		limit: z
 			.number()
 			.optional()
 			.describe("Maximum number of results (default 25, max 100)"),
 	},
-	async ({ query, limit }) => {
-		const emails = await searchEmails(query, Math.min(limit || 25, 100));
+	async ({
+		query,
+		from,
+		to,
+		cc,
+		subject,
+		body,
+		mailbox,
+		has_attachment,
+		before,
+		after,
+		unread,
+		flagged,
+		limit,
+	}) => {
+		const emails = await searchEmails(
+			{
+				query,
+				from,
+				to,
+				cc,
+				subject,
+				body,
+				mailbox,
+				hasAttachment: has_attachment,
+				before,
+				after,
+				unread,
+				flagged,
+			},
+			Math.min(limit || 25, 100),
+		);
 
 		if (emails.length === 0) {
 			return {
-				content: [
-					{ type: "text" as const, text: `No emails found for: ${query}` },
-				],
+				content: [{ type: "text" as const, text: "No emails found." }],
 			};
 		}
 
@@ -478,6 +561,79 @@ Email ID: ${emailId}`,
 	},
 );
 
+server.tool(
+	"forward_email",
+	"Forward an email to new recipients. CRITICAL: You MUST call with action='preview' first, show the user the draft, get explicit approval, then call again with action='confirm'. NEVER skip the preview step.",
+	{
+		action: z
+			.enum(["preview", "confirm"])
+			.describe(
+				"'preview' to see the draft, 'confirm' to send - ALWAYS preview first",
+			),
+		email_id: z.string().describe("The email ID to forward"),
+		to: z.string().describe("Recipient email address(es), comma-separated"),
+		body: z
+			.string()
+			.describe("Your message to include above the forwarded content"),
+		cc: z.string().optional().describe("CC recipients, comma-separated"),
+		bcc: z
+			.string()
+			.optional()
+			.describe("BCC recipients (hidden), comma-separated"),
+	},
+	async ({ action, email_id, to, body, cc, bcc }) => {
+		const parseAddresses = (s: string): EmailAddress[] =>
+			s.split(",").map((e) => ({ name: null, email: e.trim() }));
+
+		const forwardParams = await buildForward(email_id, body);
+		forwardParams.to = parseAddresses(to);
+
+		if (cc) {
+			forwardParams.cc = parseAddresses(cc);
+		}
+		if (bcc) {
+			forwardParams.bcc = parseAddresses(bcc);
+		}
+
+		if (action === "preview") {
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `📧 FORWARD PREVIEW - Review before sending:
+
+To: ${formatAddressList(forwardParams.to)}
+CC: ${forwardParams.cc ? formatAddressList(forwardParams.cc) : "(none)"}
+BCC: ${forwardParams.bcc ? formatAddressList(forwardParams.bcc) : "(none)"}
+Subject: ${forwardParams.subject}
+Forwarding from: ${forwardParams.originalFrom}
+
+--- Your Message + Forwarded Content ---
+${forwardParams.textBody}
+
+---
+To send this forward, call this tool again with action: "confirm" and the same parameters.`,
+					},
+				],
+			};
+		}
+
+		const emailId = await sendEmail(forwardParams);
+
+		return {
+			content: [
+				{
+					type: "text" as const,
+					text: `✓ Email forwarded successfully!
+To: ${formatAddressList(forwardParams.to)}
+Subject: ${forwardParams.subject}
+Email ID: ${emailId}`,
+				},
+			],
+		};
+	},
+);
+
 // ============ Attachment Tools ============
 
 server.tool(
@@ -685,6 +841,135 @@ server.tool(
 	},
 );
 
+// ============ Masked Email Tools ============
+
+function formatMaskedEmail(m: MaskedEmail): string {
+	const status = m.state || "unknown";
+	const domain = m.forDomain ? ` (${m.forDomain})` : "";
+	const desc = m.description ? ` - ${m.description}` : "";
+	const lastMsg = m.lastMessageAt
+		? `\n   Last message: ${new Date(m.lastMessageAt).toLocaleString()}`
+		: "";
+	return `${m.email}${domain}${desc}\n   Status: ${status}${lastMsg}\n   ID: ${m.id}`;
+}
+
+server.tool(
+	"list_masked_emails",
+	"List all masked email addresses (aliases) in the account. Masked emails let you create disposable addresses that forward to your inbox.",
+	{},
+	async () => {
+		const maskedEmails = await listMaskedEmails();
+
+		if (maskedEmails.length === 0) {
+			return {
+				content: [{ type: "text" as const, text: "No masked emails found." }],
+			};
+		}
+
+		// Sort by state (enabled first), then by email
+		const sorted = maskedEmails.sort((a, b) => {
+			if (a.state === "enabled" && b.state !== "enabled") return -1;
+			if (a.state !== "enabled" && b.state === "enabled") return 1;
+			return a.email.localeCompare(b.email);
+		});
+
+		const text = sorted.map(formatMaskedEmail).join("\n\n");
+		return {
+			content: [
+				{
+					type: "text" as const,
+					text: `Masked Emails (${maskedEmails.length}):\n\n${text}`,
+				},
+			],
+		};
+	},
+);
+
+server.tool(
+	"create_masked_email",
+	"Create a new masked email address. Perfect for signups where you want a disposable address. The masked email forwards to your inbox.",
+	{
+		for_domain: z
+			.string()
+			.optional()
+			.describe(
+				"The website/domain this masked email is for (e.g., 'netflix.com')",
+			),
+		description: z
+			.string()
+			.optional()
+			.describe(
+				"A note to remember what this is for (e.g., 'Netflix account')",
+			),
+		prefix: z
+			.string()
+			.optional()
+			.describe(
+				"Custom prefix for the email address (optional, random if not specified)",
+			),
+	},
+	async ({ for_domain, description, prefix }) => {
+		const maskedEmail = await createMaskedEmail({
+			forDomain: for_domain,
+			description,
+			emailPrefix: prefix,
+		});
+
+		return {
+			content: [
+				{
+					type: "text" as const,
+					text: `Created masked email:\n\n${formatMaskedEmail(maskedEmail)}`,
+				},
+			],
+		};
+	},
+);
+
+server.tool(
+	"enable_masked_email",
+	"Enable a disabled masked email address so it can receive emails again.",
+	{
+		id: z.string().describe("The masked email ID (from list_masked_emails)"),
+	},
+	async ({ id }) => {
+		await updateMaskedEmail(id, "enabled");
+		return {
+			content: [{ type: "text" as const, text: `Masked email ${id} enabled.` }],
+		};
+	},
+);
+
+server.tool(
+	"disable_masked_email",
+	"Disable a masked email address. Emails sent to it will be rejected but the address is preserved.",
+	{
+		id: z.string().describe("The masked email ID (from list_masked_emails)"),
+	},
+	async ({ id }) => {
+		await updateMaskedEmail(id, "disabled");
+		return {
+			content: [
+				{ type: "text" as const, text: `Masked email ${id} disabled.` },
+			],
+		};
+	},
+);
+
+server.tool(
+	"delete_masked_email",
+	"Permanently delete a masked email address. This cannot be undone!",
+	{
+		id: z.string().describe("The masked email ID (from list_masked_emails)"),
+	},
+	async ({ id }) => {
+		await updateMaskedEmail(id, "deleted");
+		return {
+			content: [{ type: "text" as const, text: `Masked email ${id} deleted.` }],
+		};
+	},
+);
+
 // ============ Resources ============
 
 // Expose attachments as resources with blob content

package/src/jmap/client.ts

@@ -53,6 +53,7 @@ export class JMAPClient {
 				"urn:ietf:params:jmap:core",
 				"urn:ietf:params:jmap:mail",
 				"urn:ietf:params:jmap:submission",
+				"https://www.fastmail.com/dev/maskedemail",
 			],
 			methodCalls,
 		};

package/src/jmap/methods.ts

@@ -5,6 +5,7 @@ import type {
 	EmailCreate,
 	Identity,
 	Mailbox,
+	MaskedEmail,
 } from "./types.js";
 
 // Standard properties to fetch for email listings
@@ -121,17 +122,143 @@ export async function getEmail(emailId: string): Promise<Email | null> {
 	return result.list[0] || null;
 }
 
+export async function getThreadEmails(threadId: string): Promise<Email[]> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	// Get thread to find all email IDs
+	const threadResult = await client.call<{
+		list: { id: string; emailIds: string[] }[];
+	}>("Thread/get", {
+		accountId,
+		ids: [threadId],
+	});
+
+	const thread = threadResult.list[0];
+	if (!thread || thread.emailIds.length === 0) {
+		return [];
+	}
+
+	// Fetch all emails in the thread
+	const emailResult = await client.call<{ list: Email[] }>("Email/get", {
+		accountId,
+		ids: thread.emailIds,
+		properties: EMAIL_FULL_PROPERTIES,
+		fetchTextBodyValues: true,
+		fetchHTMLBodyValues: true,
+		maxBodyValueBytes: 1024 * 1024,
+	});
+
+	// Sort by receivedAt ascending (oldest first)
+	return emailResult.list.sort(
+		(a, b) =>
+			new Date(a.receivedAt).getTime() - new Date(b.receivedAt).getTime(),
+	);
+}
+
+export interface SearchFilter {
+	query?: string; // General search across subject, from, to, body
+	from?: string;
+	to?: string;
+	cc?: string;
+	bcc?: string;
+	subject?: string;
+	body?: string;
+	mailbox?: string; // Mailbox name or ID
+	hasAttachment?: boolean;
+	minSize?: number;
+	maxSize?: number;
+	before?: string; // ISO date or YYYY-MM-DD
+	after?: string; // ISO date or YYYY-MM-DD
+	unread?: boolean;
+	flagged?: boolean;
+}
+
 export async function searchEmails(
-	query: string,
+	filter: string | SearchFilter,
 	limit = 25,
 ): Promise<Email[]> {
 	const client = getClient();
 	const accountId = await client.getAccountId();
 
-	// Query for email IDs with text filter
+	// Handle simple string query (backwards compat)
+	if (typeof filter === "string") {
+		filter = { query: filter };
+	}
+
+	// Build JMAP filter
+	const jmapFilter: Record<string, unknown> = {};
+
+	// General query - OR across multiple fields (Fastmail doesn't support "text")
+	if (filter.query) {
+		const queryResult = await client.call<{ ids: string[] }>("Email/query", {
+			accountId,
+			filter: {
+				operator: "OR",
+				conditions: [
+					{ subject: filter.query },
+					{ from: filter.query },
+					{ to: filter.query },
+					{ body: filter.query },
+				],
+			},
+			sort: [{ property: "receivedAt", isAscending: false }],
+			limit,
+		});
+
+		if (queryResult.ids.length === 0) {
+			return [];
+		}
+
+		const getResult = await client.call<{ list: Email[] }>("Email/get", {
+			accountId,
+			ids: queryResult.ids,
+			properties: EMAIL_LIST_PROPERTIES,
+		});
+
+		return getResult.list;
+	}
+
+	// Specific field filters
+	if (filter.from) jmapFilter.from = filter.from;
+	if (filter.to) jmapFilter.to = filter.to;
+	if (filter.cc) jmapFilter.cc = filter.cc;
+	if (filter.bcc) jmapFilter.bcc = filter.bcc;
+	if (filter.subject) jmapFilter.subject = filter.subject;
+	if (filter.body) jmapFilter.body = filter.body;
+
+	// Mailbox filter
+	if (filter.mailbox) {
+		const mailbox = await getMailboxByName(filter.mailbox);
+		if (mailbox) {
+			jmapFilter.inMailbox = mailbox.id;
+		}
+	}
+
+	// Boolean/size filters
+	if (filter.hasAttachment) jmapFilter.hasAttachment = true;
+	if (filter.minSize) jmapFilter.minSize = filter.minSize;
+	if (filter.maxSize) jmapFilter.maxSize = filter.maxSize;
+
+	// Date filters - normalize to ISO 8601
+	if (filter.before) {
+		jmapFilter.before = filter.before.includes("T")
+			? filter.before
+			: `${filter.before}T00:00:00Z`;
+	}
+	if (filter.after) {
+		jmapFilter.after = filter.after.includes("T")
+			? filter.after
+			: `${filter.after}T00:00:00Z`;
+	}
+
+	// Keyword filters
+	if (filter.unread) jmapFilter.notKeyword = "$seen";
+	if (filter.flagged) jmapFilter.hasKeyword = "$flagged";
+
 	const queryResult = await client.call<{ ids: string[] }>("Email/query", {
 		accountId,
-		filter: { text: query },
+		filter: jmapFilter,
 		sort: [{ property: "receivedAt", isAscending: false }],
 		limit,
 	});
@@ -524,3 +651,152 @@ export async function buildReply(
 		references: references.length > 0 ? references : undefined,
 	};
 }
+
+// Helper to build a forward
+export async function buildForward(
+	originalEmailId: string,
+	forwardBody: string,
+): Promise<
+	SendEmailParams & { originalSubject: string; originalFrom: string }
+> {
+	const original = await getEmail(originalEmailId);
+	if (!original) {
+		throw new Error(`Original email not found: ${originalEmailId}`);
+	}
+
+	// Build subject (add Fwd: if not present)
+	let subject = original.subject || "";
+	if (!subject.toLowerCase().startsWith("fwd:")) {
+		subject = `Fwd: ${subject}`;
+	}
+
+	// Get original body
+	let originalBodyText = "";
+	if (original.bodyValues) {
+		const textPart = original.textBody?.[0];
+		if (textPart?.partId && original.bodyValues[textPart.partId]) {
+			originalBodyText = original.bodyValues[textPart.partId]?.value ?? "";
+		} else {
+			const firstValue = Object.values(original.bodyValues)[0];
+			if (firstValue) {
+				originalBodyText = firstValue.value;
+			}
+		}
+	}
+
+	// Format sender
+	const sender = original.from?.[0];
+	const senderStr = sender
+		? sender.name
+			? `${sender.name} <${sender.email}>`
+			: sender.email
+		: "unknown";
+
+	const date = original.receivedAt
+		? new Date(original.receivedAt).toLocaleString()
+		: "unknown date";
+
+	// Build full body with attribution
+	const fullBody = `${forwardBody}
+
+---------- Forwarded message ---------
+From: ${senderStr}
+Date: ${date}
+Subject: ${original.subject || ""}
+
+${originalBodyText}`;
+
+	return {
+		to: [], // Caller must provide
+		subject,
+		textBody: fullBody,
+		originalSubject: original.subject || "",
+		originalFrom: senderStr,
+	};
+}
+
+// ============ Masked Email Methods ============
+
+export async function listMaskedEmails(): Promise<MaskedEmail[]> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const result = await client.call<{ list: MaskedEmail[] }>("MaskedEmail/get", {
+		accountId,
+		ids: null, // null = get all
+	});
+
+	return result.list;
+}
+
+export interface CreateMaskedEmailParams {
+	forDomain?: string;
+	description?: string;
+	emailPrefix?: string;
+}
+
+export async function createMaskedEmail(
+	params: CreateMaskedEmailParams = {},
+): Promise<MaskedEmail> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const createObj: Record<string, unknown> = {
+		state: "enabled",
+	};
+
+	if (params.forDomain) {
+		createObj.forDomain = params.forDomain;
+	}
+	if (params.description) {
+		createObj.description = params.description;
+	}
+	if (params.emailPrefix) {
+		createObj.emailPrefix = params.emailPrefix;
+	}
+
+	const result = await client.call<{
+		created?: Record<string, MaskedEmail>;
+		notCreated?: Record<string, { type: string; description?: string }>;
+	}>("MaskedEmail/set", {
+		accountId,
+		create: { new: createObj },
+	});
+
+	if (result.notCreated?.new) {
+		const err = result.notCreated.new;
+		throw new Error(
+			`Failed to create masked email: ${err.type}${err.description ? ` - ${err.description}` : ""}`,
+		);
+	}
+
+	const created = result.created?.new;
+	if (!created) {
+		throw new Error("No masked email returned from create");
+	}
+
+	return created;
+}
+
+export async function updateMaskedEmail(
+	id: string,
+	state: "enabled" | "disabled" | "deleted",
+): Promise<void> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const result = await client.call<{
+		updated?: Record<string, unknown>;
+		notUpdated?: Record<string, { type: string; description?: string }>;
+	}>("MaskedEmail/set", {
+		accountId,
+		update: { [id]: { state } },
+	});
+
+	if (result.notUpdated?.[id]) {
+		const err = result.notUpdated[id];
+		throw new Error(
+			`Failed to update masked email: ${err.type}${err.description ? ` - ${err.description}` : ""}`,
+		);
+	}
+}

package/src/jmap/types.ts

@@ -202,3 +202,16 @@ export interface EmailCreate {
 	messageId?: string[];
 	headers?: EmailHeader[];
 }
+
+// Masked Email Types (Fastmail-specific)
+export interface MaskedEmail {
+	id: string;
+	email: string;
+	state?: string; // pending, enabled, disabled, deleted
+	forDomain?: string | null;
+	description?: string | null;
+	lastMessageAt?: string | null;
+	createdAt?: string | null;
+	createdBy?: string | null;
+	url?: string | null;
+}