@mcp-z/email

Email processing toolkit with base schemas, normalization utilities, and shared constants for Gmail/Outlook integration

Common uses

• Normalize Gmail/Outlook messages to a shared shape
• Parse and format email addresses
• Build shared query schemas across providers
• Extract clean text from HTML threads

Install

npm install @mcp-z/email
Copy

Quick start

Parse addresses

import { parseAddresses, formatAddresses } from '@mcp-z/email';

const parsed = parseAddresses('John Doe <john@example.com>, jane@example.com');
const formatted = formatAddresses(parsed);
console.log(formatted); // john@example.com, jane@example.com
Copy

Base query fields

import { baseEmailQueryFields } from '@mcp-z/email';
import { z } from 'zod';

const QuerySchema = z.object({
  ...baseEmailQueryFields
});
Copy

Examples by category

Parsing and normalization

import { normalizeDateToISO, stripHtml } from '@mcp-z/email';

const iso = normalizeDateToISO('Wed, 11 Sep 2024 10:30:00 -0400');
const text = stripHtml('<div>Hello <b>World</b></div>');
Copy

Thread extraction

import { extractCurrentMessageFromHtmlToText, extractCurrentMessageFromText } from '@mcp-z/email';

const textFromHtml = extractCurrentMessageFromHtmlToText('<div>New reply</div><blockquote>Old</blockquote>');
const textFromPlain = extractCurrentMessageFromText('New reply\n\n> Old message');
Copy

Query schemas

import { baseEmailQueryFields, FieldOperatorSchema } from '@mcp-z/email';
import { z } from 'zod';

const QuerySchema = z.object({
  ...baseEmailQueryFields,
  label: FieldOperatorSchema.optional()
});
Copy

Tool input schemas

import { ComposeContentTypeSchema, createEmailRecipientsSchema } from '@mcp-z/email';
import { z } from 'zod';

const InputSchema = z.object({
  to: createEmailRecipientsSchema('To recipients'),
  body: z.string().min(1),
  contentType: ComposeContentTypeSchema.optional()
});
Copy

Response helpers

import { buildContentForItems } from '@mcp-z/email';

const content = buildContentForItems([{ id: '1', subject: 'Hello' }], 'emails');
Copy

API overview

• Address helpers: parseAddresses(), formatAddresses()
• HTML/text helpers: stripHtml(), extractCurrentMessageFromHtml(), extractCurrentMessageFromHtmlToText(), extractCurrentMessageFromText()
• Date helpers: normalizeDateToISO()
• Query helpers: baseEmailQueryFields, FieldOperatorSchema, EMAIL_FIELDS, EMAIL_FIELD_DESCRIPTIONS, EMAIL_COMMON_PATTERNS
• Schemas: EmailSummarySchema, EmailDetailSchema, EmailContentTypeSchema, ExcludeThreadHistorySchema
• Tool helpers: createEmailRecipientsSchema(), createMessageResultSchema(), ComposeContentTypeSchema
• Content helpers: buildContentForItems()
• Utils: safeBase64UrlDecode()

Requirements

• Node.js >= 16

The package uses zod for its exported schemas. Install zod directly when your application imports it, as in the schema examples above: npm install zod.

Documentation

API Docs