Spam Trap Analysis

Instructions

Implementation Reference

• deliveriq-mcp/src/tools/intelligence.ts:254-287 (handler)

  The handler function that executes the deliveriq_spam_trap_analysis tool logic: calls client.tools.spamTrapAnalysis(params.email) and formats the response with risk level, trap type, confidence score, and all 13 signals.

    async (params) => {
      try {
        const res = await client.tools.spamTrapAnalysis(params.email);
        const r = res.result;
  
        const lines = [
          `# Spam Trap Analysis: ${res.email}`,
          '',
          `**Risk Level**: ${r.riskLevel.toUpperCase()} | **Trap Type**: ${r.trapType} | **Confidence**: ${(r.confidence * 100).toFixed(0)}%`,
          `**Score**: ${r.score.toFixed(3)}`,
          '',
          '## Signals',
          `| Signal | Value |`,
          `|--------|-------|`,
          `| Domain age | ${r.signals.domainAge ? `${r.signals.domainAge.ageDays} days (${r.signals.domainAge.riskLevel})` : 'Unknown'} |`,
          `| DNSBL listed | ${r.signals.dnsblListed ? `Yes (${r.signals.dnsblHitCount} hits)` : 'No'} |`,
          `| Disposable | ${r.signals.isDisposable ? 'Yes' : 'No'} |`,
          `| Role-based | ${r.signals.isRoleBased ? 'Yes' : 'No'} |`,
          `| Has Gravatar | ${r.signals.hasGravatar ? 'Yes' : 'No'} |`,
          `| Has MX | ${r.signals.hasMx ? 'Yes' : 'No'} |`,
          `| Local part entropy | ${r.signals.localPartEntropy.toFixed(2)} |`,
          `| Email pattern trust | ${(r.signals.emailPatternTrust * 100).toFixed(0)}% |`,
          `| Email pattern | ${r.signals.emailPattern ?? 'None detected'} |`,
          `| Has suggestion | ${r.signals.hasSuggestion ? 'Yes (possible typo)' : 'No'} |`,
          `| MX has PTR | ${r.signals.mxHasPtrRecord === null ? 'Unknown' : r.signals.mxHasPtrRecord ? 'Yes' : 'No'} |`,
          `| MX IP DNSBL listed | ${r.signals.mxIpDnsblListed === null ? 'Unknown' : r.signals.mxIpDnsblListed ? 'Yes' : 'No'} |`,
        ];
  
        return successResponse(lines.join('\n'));
      } catch (error) {
        return handleSdkError(error);
      }
    },
  );

• deliveriq-mcp/src/tools/intelligence.ts:228-287 (registration)

  Registers the 'deliveriq_spam_trap_analysis' tool on the MCP server with title, description, input schema, and annotations. Part of the registerIntelligenceTools function.

    // ── 9. deliveriq_spam_trap_analysis ───────────────────────────
  
    server.registerTool(
      'deliveriq_spam_trap_analysis',
      {
        title: 'Spam Trap Analysis',
        description: `Analyze an email address for spam trap risk using 13 signals including domain age, DNSBL listing, disposability, role-based detection, entropy, and email pattern trust.
  
  Args:
    - email (string): Email address to analyze
  
  Returns:
    Risk level (low/medium/high), trap type (pristine/recycled/typo/none), confidence score, and all 13 signals.
  
  Examples:
    - "Is user@example.com a spam trap?" -> { email: "user@example.com" }
  
  Credit cost: 1 credit`,
        inputSchema: SpamTrapAnalysisSchema,
        annotations: {
          readOnlyHint: false,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async (params) => {
        try {
          const res = await client.tools.spamTrapAnalysis(params.email);
          const r = res.result;
  
          const lines = [
            `# Spam Trap Analysis: ${res.email}`,
            '',
            `**Risk Level**: ${r.riskLevel.toUpperCase()} | **Trap Type**: ${r.trapType} | **Confidence**: ${(r.confidence * 100).toFixed(0)}%`,
            `**Score**: ${r.score.toFixed(3)}`,
            '',
            '## Signals',
            `| Signal | Value |`,
            `|--------|-------|`,
            `| Domain age | ${r.signals.domainAge ? `${r.signals.domainAge.ageDays} days (${r.signals.domainAge.riskLevel})` : 'Unknown'} |`,
            `| DNSBL listed | ${r.signals.dnsblListed ? `Yes (${r.signals.dnsblHitCount} hits)` : 'No'} |`,
            `| Disposable | ${r.signals.isDisposable ? 'Yes' : 'No'} |`,
            `| Role-based | ${r.signals.isRoleBased ? 'Yes' : 'No'} |`,
            `| Has Gravatar | ${r.signals.hasGravatar ? 'Yes' : 'No'} |`,
            `| Has MX | ${r.signals.hasMx ? 'Yes' : 'No'} |`,
            `| Local part entropy | ${r.signals.localPartEntropy.toFixed(2)} |`,
            `| Email pattern trust | ${(r.signals.emailPatternTrust * 100).toFixed(0)}% |`,
            `| Email pattern | ${r.signals.emailPattern ?? 'None detected'} |`,
            `| Has suggestion | ${r.signals.hasSuggestion ? 'Yes (possible typo)' : 'No'} |`,
            `| MX has PTR | ${r.signals.mxHasPtrRecord === null ? 'Unknown' : r.signals.mxHasPtrRecord ? 'Yes' : 'No'} |`,
            `| MX IP DNSBL listed | ${r.signals.mxIpDnsblListed === null ? 'Unknown' : r.signals.mxIpDnsblListed ? 'Yes' : 'No'} |`,
          ];
  
          return successResponse(lines.join('\n'));
        } catch (error) {
          return handleSdkError(error);
        }
      },
    );

• deliveriq-mcp/src/schemas/intelligence.ts:26-29 (schema)

  Zod schema for spam trap analysis input validation: requires a valid email string.

  export const SpamTrapAnalysisSchema = z.object({
    email: z.string().email('Must be a valid email address')
      .describe('Email address to analyze for spam trap risk (e.g. "user@example.com")'),
  }).strict();

• deliveriq-sdk/src/resources/tools.ts:25-27 (helper)

  SDK method that makes the POST request to /tools/spam-trap-analysis endpoint.

  /** Evaluate an email against 13 spam trap signals. Costs 1 credit. */
  async spamTrapAnalysis(email: string, opts?: RequestOptions): Promise<SpamTrapAnalysisResponse> {
    return this.http.post<SpamTrapAnalysisResponse>('/tools/spam-trap-analysis', { email }, opts);

• deliveriq-sdk/src/types.ts:329-355 (helper)

  TypeScript type definitions for SpamTrapSignals (13 signals) and SpamTrapAnalysisResponse (riskLevel, trapType, confidence, score, signals).

  export interface SpamTrapSignals {
    hasSuggestion: boolean;
    domainAge: DomainAgeResult | null;
    dnsblListed: boolean;
    dnsblHitCount: number;
    isDisposable: boolean;
    isRoleBased: boolean;
    hasGravatar: boolean;
    hasMx: boolean;
    localPartEntropy: number;
    emailPatternTrust: number;
    emailPattern: string | null;
    mxHasPtrRecord: boolean | null;
    mxIpDnsblListed: boolean | null;
  }
  
  export interface SpamTrapAnalysisResponse {
    success: true;
    email: string;
    result: {
      score: number;
      riskLevel: 'low' | 'medium' | 'high';
      trapType: 'pristine' | 'recycled' | 'typo' | 'none' | 'unknown';
      confidence: number;
      signals: SpamTrapSignals;
    };
  }