@adrata/adrata-mcp 1.0.0

package/tools/email-tools.js

@@ -0,0 +1,652 @@
+/**
+ * Enterprise-only email infrastructure tools for Adrata MCP Server.
+ *
+ * Provides domain management, email account provisioning, and sequence
+ * management tools. All tools require enterprise tier (OAuth workspace
+ * connection) and call existing Rust API endpoints.
+ *
+ * Domain tools:
+ *   - search_domains: find available domains for purchase
+ *   - purchase_domain: buy a domain through Adrata
+ *   - setup_domain: configure DNS records (SPF, DKIM, DMARC)
+ *   - verify_domain: check DNS propagation status
+ *   - list_domains: all workspace domains with health status
+ *
+ * Email account tools:
+ *   - create_email_account: provision a mailbox on an owned domain
+ *   - list_email_accounts: list mailboxes, optionally filtered by domain
+ *   - warmup_email: start or stop gradual sending warmup
+ *   - get_email_health: deliverability score for an account
+ *
+ * Sequence tools:
+ *   - create_sequence: build a multi-step email sequence
+ *   - list_sequences_full: list sequences with status and metrics
+ *   - add_sequence_step: add a step to an existing sequence
+ *   - activate_sequence: start sending to enrolled contacts
+ *   - pause_sequence: pause a running sequence
+ *   - get_sequence_analytics: open/reply/bounce rates
+ *   - enroll_contacts: add contacts to a sequence
+ */
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all email infrastructure tools on the MCP server.
+ *
+ * @param {McpServer} server - The MCP server instance (already tier-gated)
+ * @param {object} deps - Dependencies: { z, api, AUTH, ok, API_BASE }
+ */
+export function registerEmailTools(server, { z, api, AUTH, ok, API_BASE }) {
+  /**
+   * Resolve a domain name (or id) to the workspace email-domain record.
+   * The provisioning API keys verify/dns-records routes by domain ID, while
+   * MCP tools accept the human-friendly domain name.
+   */
+  async function findDomainRecord(domainOrId) {
+    const data = await api('GET', '/api/v1/email-provisioning/domains', {
+      params: { limit: 200, page: 1 },
+    });
+    const items = data?.data || [];
+    const needle = String(domainOrId || '')
+      .trim()
+      .toLowerCase();
+    return (
+      items.find(
+        (d) => (d.domain && String(d.domain).toLowerCase() === needle) || d.id === domainOrId
+      ) || null
+    );
+  }
+
+  // =========================================================================
+  // DOMAIN TOOLS
+  // =========================================================================
+
+  server.tool(
+    'search_domains',
+    'Search for available domains to purchase for email sending. Returns matching domains with pricing and availability. Enterprise only.',
+    {
+      query: z.string().describe('Domain search query (e.g. "acme", "outreach-co")'),
+      tlds: z
+        .array(z.string())
+        .optional()
+        .describe('TLDs to search (default: ["com", "io", "co"]). Example: ["com", "net", "org"]'),
+    },
+    async (args) => {
+      // The API checks one fully-qualified domain per request, so fan out
+      // across the requested TLDs (or the defaults) and aggregate.
+      const candidates = args.query.includes('.')
+        ? [args.query]
+        : (args.tlds && args.tlds.length > 0 ? args.tlds : ['com', 'io', 'co']).map(
+            (tld) => `${args.query}.${tld.replace(/^\./, '')}`
+          );
+
+      const results = await Promise.all(
+        candidates.map(async (domain) => {
+          try {
+            const data = await api('GET', '/api/v1/email-provisioning/domain-purchases/search', {
+              params: { domain },
+            });
+            return data?.data || data;
+          } catch (err) {
+            return { domain, available: false, message: err.message };
+          }
+        })
+      );
+
+      const available = results.filter((r) => r?.available);
+      return ok({
+        query: args.query,
+        domains: results,
+        message:
+          available.length === 0
+            ? 'No available domains found. Try a different query or different TLDs.'
+            : undefined,
+      });
+    }
+  );
+
+  server.tool(
+    'purchase_domain',
+    'Purchase a domain for email sending through Adrata. The domain will be added to your workspace and ready for DNS setup. Enterprise only.',
+    {
+      domain: z.string().describe('Full domain name to purchase (e.g. "outreach-acme.com")'),
+      autoSetup: z
+        .boolean()
+        .optional()
+        .describe('Automatically configure DNS records after purchase (default: true)'),
+    },
+    async (args) => {
+      // Domain purchases go through a Stripe checkout session; the API does
+      // not charge directly. Payment completion triggers provisioning.
+      const data = await api('POST', '/api/v1/email-provisioning/domain-purchases/checkout', {
+        body: {
+          domain: args.domain,
+          returnUrl: API_BASE,
+          mailboxCount: 0,
+        },
+      });
+      const details = data?.data || data;
+      return ok({
+        purchased: false,
+        checkoutRequired: true,
+        domain: args.domain,
+        orderId: details?.orderId,
+        checkoutUrl: details?.checkoutUrl || details?.checkout_url,
+        totalCents: details?.totalCents,
+        details,
+        nextSteps:
+          'Open checkoutUrl to complete payment. After payment, DNS and email provisioning run automatically' +
+          (args.autoSetup !== false
+            ? '. Use verify_domain to check propagation status once provisioned.'
+            : '. Use setup_domain to review DNS records, then verify_domain to check propagation.'),
+      });
+    }
+  );
+
+  server.tool(
+    'setup_domain',
+    'Configure DNS records (SPF, DKIM, DMARC) for an email sending domain. Required before sending emails from the domain. Enterprise only.',
+    {
+      domain: z.string().describe('Domain name to configure (e.g. "outreach-acme.com")'),
+    },
+    async (args) => {
+      // If the domain is not registered in the workspace yet, add it (which
+      // returns the DNS records to configure). Otherwise fetch its records.
+      const existing = await findDomainRecord(args.domain);
+      if (!existing) {
+        const data = await api('POST', '/api/v1/email-provisioning/domains', {
+          body: { domain: args.domain },
+        });
+        const created = data?.data || data;
+        return ok({
+          domain: args.domain,
+          setup: created,
+          dnsRecords: created?.dnsRecords,
+          message:
+            'Domain added. Add the returned SPF, DKIM, and DMARC records at your DNS host, then use verify_domain to check propagation.',
+        });
+      }
+      const data = await api(
+        'GET',
+        `/api/v1/email-provisioning/domains/${encodeURIComponent(existing.id)}/dns-records`
+      );
+      return ok({
+        domain: args.domain,
+        setup: data?.data || data,
+        message:
+          'These are the DNS records required for this domain. Add any missing records at your DNS host, then use verify_domain to check propagation.',
+      });
+    }
+  );
+
+  server.tool(
+    'verify_domain',
+    'Check DNS propagation status for an email domain. Returns verification status for SPF, DKIM, and DMARC records. Enterprise only.',
+    {
+      domain: z.string().describe('Domain name to verify (e.g. "outreach-acme.com")'),
+    },
+    async (args) => {
+      const record = await findDomainRecord(args.domain);
+      if (!record) {
+        return ok({
+          error: 'domain_not_found',
+          domain: args.domain,
+          message: `Domain ${args.domain} is not registered in this workspace. Use setup_domain to add it first.`,
+        });
+      }
+      const data = await api(
+        'POST',
+        `/api/v1/email-provisioning/domains/${encodeURIComponent(record.id)}/verify`,
+        {
+          body: {},
+        }
+      );
+      return ok({
+        domain: args.domain,
+        verification: data?.data || data,
+      });
+    }
+  );
+
+  server.tool(
+    'list_domains',
+    'List all email sending domains in your workspace with health status. Shows verification state, deliverability scores, and active mailbox counts. Enterprise only.',
+    {
+      status: z.string().optional().describe('Filter by status: verified, pending, failed'),
+    },
+    async (args) => {
+      const params = {};
+      if (args.status) params.status = args.status;
+      const data = await api('GET', '/api/v1/email-provisioning/domains', { params });
+      return ok({
+        domains: data?.data || [],
+        total: data?.total || data?.meta?.total || (data?.data || []).length,
+      });
+    }
+  );
+
+  // =========================================================================
+  // EMAIL ACCOUNT TOOLS
+  // =========================================================================
+
+  server.tool(
+    'create_email_account',
+    'Provision a new email mailbox on an owned domain. Creates the account and optionally starts warmup. Enterprise only.',
+    {
+      domain: z
+        .string()
+        .describe('Domain to create the account on (must be a verified domain in your workspace)'),
+      username: z
+        .string()
+        .describe('Username/local part of the email (e.g. "sarah" for sarah@domain.com)'),
+      displayName: z.string().describe('Display name for the sender (e.g. "Sarah Johnson")'),
+      autoWarmup: z
+        .boolean()
+        .optional()
+        .describe('Start warmup immediately after creation (default: false)'),
+    },
+    async (args) => {
+      const email = `${args.username}@${args.domain}`;
+      // The mailbox API takes a full email address plus optional domainId.
+      const domainRecord = await findDomainRecord(args.domain).catch(() => null);
+      const body = {
+        email,
+        displayName: args.displayName,
+      };
+      if (domainRecord?.id) body.domainId = domainRecord.id;
+
+      const data = await api('POST', '/api/v1/email-provisioning/mailboxes', { body });
+
+      const account = data?.data || data;
+
+      // Optionally start warmup
+      if (args.autoWarmup && account?.id) {
+        try {
+          await api('POST', `/api/v1/email-provisioning/mailboxes/${account.id}/warmup`, {
+            body: { enable: true },
+          });
+          return ok({
+            created: true,
+            account,
+            email,
+            warmupStarted: true,
+            message: `Email account ${email} created and warmup started. Use get_email_health to monitor deliverability.`,
+          });
+        } catch (warmupErr) {
+          return ok({
+            created: true,
+            account,
+            email,
+            warmupStarted: false,
+            warmupError: warmupErr.message,
+            message: `Email account created but warmup could not be started. Use warmup_email to start manually.`,
+          });
+        }
+      }
+
+      return ok({
+        created: true,
+        account,
+        email: `${args.username}@${args.domain}`,
+        message: `Email account ${args.username}@${args.domain} created. Use warmup_email to begin gradual sending warmup before using in sequences.`,
+      });
+    }
+  );
+
+  server.tool(
+    'list_email_accounts',
+    'List email mailboxes in your workspace. Optionally filter by domain. Shows warmup status and health scores. Enterprise only.',
+    {
+      domain: z.string().optional().describe('Filter by domain name'),
+      status: z.string().optional().describe('Filter by status: active, warming, paused, disabled'),
+      limit: z.number().optional().describe('Results per page (default 25)'),
+      page: z.number().optional().describe('Page number'),
+    },
+    async (args) => {
+      const params = {
+        limit: args.limit || 25,
+        page: args.page || 1,
+      };
+      if (args.status) params.status = args.status;
+      const [provisionedResult, connectedResult] = await Promise.allSettled([
+        api('GET', '/api/v1/email-provisioning/mailboxes', { params }),
+        api('GET', '/api/v1/oauth/email/providers'),
+      ]);
+      const provisionedData =
+        provisionedResult.status === 'fulfilled' ? provisionedResult.value : null;
+      const connectedData = connectedResult.status === 'fulfilled' ? connectedResult.value : null;
+      // The connected-inbox read carries its own answerPolicy from the API
+      // (see /api/v1/oauth/email/providers): a caller with no per-user
+      // identity bound (e.g. a bare OAuth client-credentials token) gets
+      // abstain:true rather than a silent empty list. A 200 response is NOT
+      // by itself proof the caller could see connected inboxes — only
+      // answerPolicy.abstain === false is.
+      const connectedAnswerPolicy = connectedData?.answerPolicy || null;
+      const connectedVisibilityAbstained = connectedAnswerPolicy?.abstain === true;
+      let accounts = [
+        ...(provisionedData?.data || []).map((mailbox) => ({
+          ...mailbox,
+          source: 'provisioned',
+          syncStatus: null,
+        })),
+        ...(connectedData?.data || []).map((provider) => ({
+          id: provider.id,
+          email: provider.email,
+          provider: provider.provider,
+          status: provider.isExpired ? 'reauth_required' : provider.status,
+          source: 'connected',
+          syncStatus: provider.lastSyncStatus || (provider.lastSyncAt ? 'succeeded' : 'pending'),
+          lastSyncAt: provider.lastSyncAt,
+          lastSyncMessageCount: provider.lastSyncMessageCount,
+          warmupStatus: provider.warmupStatus || provider.warmup_status || 'unknown',
+          reputationScore: provider.reputationScore || provider.reputation_score || null,
+        })),
+      ];
+      if (args.status) {
+        accounts = accounts.filter((account) => account.status === args.status);
+      }
+      // Neither API has a domain filter; apply it client-side on the email suffix.
+      if (args.domain) {
+        const suffix = `@${String(args.domain).trim().toLowerCase()}`;
+        accounts = accounts.filter((m) =>
+          String(m.email || '')
+            .toLowerCase()
+            .endsWith(suffix)
+        );
+      }
+      return ok({
+        accounts,
+        total: accounts.length,
+        page: args.page || 1,
+        // Mirrors the answerPolicy.abstain contract used elsewhere (e.g.
+        // get_deal_close_probability, mutual_action_plan): abstain when this
+        // result cannot support the claim "these are all the accounts."
+        answerPolicy: {
+          abstain: connectedVisibilityAbstained,
+          reason: connectedVisibilityAbstained
+            ? connectedAnswerPolicy.reason
+            : 'Connected-inbox and provisioned-mailbox reads were both scoped to this caller\'s own identity; an empty or partial account list reflects what exists, not a blind spot in this caller\'s visibility.',
+        },
+        coverage: {
+          connectedInboxReadSucceeded: connectedResult.status === 'fulfilled',
+          // True only when the connected-inbox read both succeeded AND was
+          // not forced to abstain for lack of a per-user identity. A prior
+          // version of this field was `true` whenever the HTTP call
+          // completed, even when it was structurally blind (scoped to an
+          // OAuth client identity with zero possible matches) — that made an
+          // empty result read as "checked, none exist" when the true state
+          // was "could not see."
+          connectedInboxVisible: connectedResult.status === 'fulfilled' && !connectedVisibilityAbstained,
+          provisionedMailboxReadSucceeded: provisionedResult.status === 'fulfilled',
+          unifiedRepliesRequireConnectedInbox: true,
+        },
+      });
+    }
+  );
+
+  server.tool(
+    'warmup_email',
+    'Start or stop gradual sending warmup for an email account. Warmup builds sender reputation by slowly increasing send volume. Enterprise only.',
+    {
+      accountId: z.string().describe('Email account/mailbox ID'),
+      action: z.enum(['start', 'stop']).describe('Start or stop the warmup process'),
+    },
+    async (args) => {
+      const data = await api(
+        'POST',
+        `/api/v1/email-provisioning/mailboxes/${args.accountId}/warmup`,
+        {
+          body: { enable: args.action === 'start' },
+        }
+      );
+      return ok({
+        accountId: args.accountId,
+        action: args.action,
+        warmup: data?.data || data,
+        message:
+          args.action === 'start'
+            ? 'Warmup started. Send volume will gradually increase over the next 2-4 weeks. Use get_email_health to monitor progress.'
+            : 'Warmup stopped. The account will no longer send warmup emails.',
+      });
+    }
+  );
+
+  server.tool(
+    'get_email_health',
+    'Get the deliverability health score for an email account. Returns sender reputation, bounce rate, spam complaints, and warmup progress. Enterprise only.',
+    {
+      accountId: z.string().describe('Email account/mailbox ID'),
+    },
+    async (args) => {
+      // There is no dedicated /health route; the mailbox record carries
+      // status, warmup state, and send-limit/health fields.
+      const data = await api('GET', `/api/v1/email-provisioning/mailboxes/${args.accountId}`);
+      return ok({
+        accountId: args.accountId,
+        health: data?.data || data,
+      });
+    }
+  );
+
+  // =========================================================================
+  // SEQUENCE TOOLS
+  // =========================================================================
+
+  server.tool(
+    'create_sequence',
+    'Create a new multi-step email sequence. Define the name and optionally include initial steps. Steps specify delay, subject, and body template. Enterprise only.',
+    {
+      name: z.string().describe('Sequence name (e.g. "Cold Outreach Q2 2026")'),
+      description: z.string().optional().describe('Sequence description'),
+      steps: z
+        .array(
+          z.object({
+            order: z.number().describe('Step order (1-based)'),
+            delayDays: z
+              .number()
+              .describe(
+                'Days to wait before sending this step (0 for first step = send immediately)'
+              ),
+            subject: z
+              .string()
+              .describe('Email subject line (supports {{firstName}}, {{company}} variables)'),
+            body: z
+              .string()
+              .describe(
+                'Email body template (supports {{firstName}}, {{company}}, {{title}} variables)'
+              ),
+            type: z
+              .string()
+              .optional()
+              .describe(
+                'Step type: email (default), linkedin_view, linkedin_connect, call, manual'
+              ),
+          })
+        )
+        .optional()
+        .describe('Initial sequence steps. Can also add steps later with add_sequence_step.'),
+      mailboxId: z.string().optional().describe('Default mailbox ID to send from'),
+    },
+    async (args) => {
+      const createBody = {
+        name: args.name,
+      };
+      if (args.description) createBody.description = args.description;
+      if (args.steps) createBody.steps = args.steps;
+      if (args.mailboxId) createBody.mailboxId = args.mailboxId;
+
+      const data = await api('POST', '/api/v1/sequences', { body: createBody });
+      const sequence = data?.data || data;
+
+      return ok({
+        created: true,
+        sequence,
+        message:
+          args.steps && args.steps.length > 0
+            ? `Sequence "${args.name}" created with ${args.steps.length} steps. Use activate_sequence to start sending, or enroll_contacts to add recipients.`
+            : `Sequence "${args.name}" created. Use add_sequence_step to add steps, then activate_sequence to start.`,
+      });
+    }
+  );
+
+  server.tool(
+    'list_sequences_full',
+    'List email sequences with full details including status, step count, and enrollment metrics. Enterprise only.',
+    {
+      status: z.string().optional().describe('Filter by status: draft, active, paused, completed'),
+      limit: z.number().optional().describe('Results per page (default 25)'),
+      page: z.number().optional().describe('Page number'),
+    },
+    async (args) => {
+      const params = {
+        limit: args.limit || 25,
+        page: args.page || 1,
+      };
+      if (args.status) params.status = args.status;
+      const data = await api('GET', '/api/v1/sequences', { params });
+      return ok({
+        sequences: data?.data || [],
+        total: data?.total || data?.meta?.total || (data?.data || []).length,
+        page: args.page || 1,
+      });
+    }
+  );
+
+  server.tool(
+    'add_sequence_step',
+    'Add a step to an existing sequence. Steps are executed in order with configurable delays between them. Enterprise only.',
+    {
+      sequenceId: z.string().describe('Sequence ID to add the step to'),
+      order: z.number().describe('Step order (1-based). Inserts at this position.'),
+      delayDays: z
+        .number()
+        .describe('Days to wait before sending this step (relative to previous step)'),
+      subject: z
+        .string()
+        .describe('Email subject line (supports {{firstName}}, {{company}} variables)'),
+      body: z
+        .string()
+        .describe('Email body template (supports {{firstName}}, {{company}}, {{title}} variables)'),
+      type: z
+        .string()
+        .optional()
+        .describe('Step type: email (default), linkedin_view, linkedin_connect, call, manual'),
+    },
+    async (args) => {
+      const stepBody = {
+        order: args.order,
+        delayDays: args.delayDays,
+        subject: args.subject,
+        body: args.body,
+      };
+      if (args.type) stepBody.type = args.type;
+
+      const data = await api('POST', `/api/v1/sequences/${args.sequenceId}/steps`, {
+        body: stepBody,
+      });
+      return ok({
+        sequenceId: args.sequenceId,
+        step: data?.data || data,
+        message: `Step ${args.order} added to sequence. Subject: "${args.subject}"`,
+      });
+    }
+  );
+
+  server.tool(
+    'activate_sequence',
+    'Activate a sequence to start sending emails to enrolled contacts. The sequence must have at least one step and enrolled contacts. Enterprise only.',
+    {
+      sequenceId: z.string().describe('Sequence ID to activate'),
+    },
+    async (args) => {
+      // The sequences API models activation as resume (pause/resume pair).
+      const data = await api('POST', `/api/v1/sequences/${args.sequenceId}/resume`, {
+        body: {},
+      });
+      return ok({
+        sequenceId: args.sequenceId,
+        activated: true,
+        details: data?.data || data,
+        message: 'Sequence activated. Emails will begin sending according to the step schedule.',
+      });
+    }
+  );
+
+  server.tool(
+    'pause_sequence',
+    'Pause a running sequence. Enrolled contacts will stop receiving emails until the sequence is reactivated. Enterprise only.',
+    {
+      sequenceId: z.string().describe('Sequence ID to pause'),
+    },
+    async (args) => {
+      const data = await api('POST', `/api/v1/sequences/${args.sequenceId}/pause`, {
+        body: {},
+      });
+      return ok({
+        sequenceId: args.sequenceId,
+        paused: true,
+        details: data?.data || data,
+        message: 'Sequence paused. No further emails will be sent until reactivated.',
+      });
+    }
+  );
+
+  server.tool(
+    'get_sequence_analytics',
+    'Get performance analytics for a sequence. Returns open rates, reply rates, bounce rates, unsubscribe rates, and per-step metrics. Enterprise only.',
+    {
+      sequenceId: z.string().describe('Sequence ID to get analytics for'),
+    },
+    async (args) => {
+      const data = await api('GET', `/api/v1/sequences/${args.sequenceId}/analytics`);
+      return ok({
+        sequenceId: args.sequenceId,
+        analytics: data?.data || data,
+      });
+    }
+  );
+
+  server.tool(
+    'enroll_contacts',
+    'Enroll contacts into a sequence. Contacts will begin receiving sequence emails according to the step schedule. Enterprise only.',
+    {
+      sequenceId: z.string().describe('Sequence ID to enroll contacts into'),
+      contactIds: z.array(z.string()).describe('Array of person/contact IDs to enroll'),
+      mailboxId: z.string().optional().describe('Override mailbox ID for these enrollments'),
+    },
+    async (args) => {
+      if (args.contactIds.length === 0) {
+        return ok({
+          error: 'empty_contacts',
+          message: 'No contact IDs provided. Provide at least one contact ID to enroll.',
+        });
+      }
+
+      if (args.contactIds.length > 500) {
+        return ok({
+          error: 'too_many_contacts',
+          message: `Cannot enroll ${args.contactIds.length} contacts at once. Maximum is 500. Split into smaller batches.`,
+        });
+      }
+
+      const enrollBody = {
+        contactIds: args.contactIds,
+      };
+      if (args.mailboxId) enrollBody.mailboxId = args.mailboxId;
+
+      const data = await api('POST', `/api/v1/sequences/${args.sequenceId}/enroll`, {
+        body: enrollBody,
+      });
+
+      return ok({
+        sequenceId: args.sequenceId,
+        enrolled: data?.data?.enrolled || args.contactIds.length,
+        skipped: data?.data?.skipped || 0,
+        details: data?.data || data,
+        message: `Enrolled ${data?.data?.enrolled || args.contactIds.length} contacts into sequence.`,
+      });
+    }
+  );
+}