hs_contact_by_email

Instructions

Implementation Reference

• src/index.ts:96-101 (registration)

  Registers the 'hs_contact_by_email' tool on the MCP server with a description, schema shape, and handler that delegates to contactByEmail.

  server.tool(
    "hs_contact_by_email",
    "Look up contacts by exact email address. Returns up to 5 matches.",
    ContactByEmailSchema.shape,
    async (args) => { try { return ok(await contactByEmail(args)); } catch (e) { return err(e); } },
  );

• src/tools/contacts.ts:35-37 (schema)

  Zod schema for the tool input: an 'email' field validated as a string email.

  export const ContactByEmailSchema = z.object({
    email: z.string().email().describe("Contact's email address"),
  });

• src/tools/contacts.ts:39-47 (handler)

  Handler function that calls the HubSpot API (POST /crm/v3/objects/contacts/search) filtering by exact email match, returning up to 5 results with standard contact properties.

  export async function contactByEmail(args: z.infer<typeof ContactByEmailSchema>) {
    return hubspot("/crm/v3/objects/contacts/search", "POST", {
      filterGroups: [{
        filters: [{ propertyName: "email", operator: "EQ", value: args.email }],
      }],
      properties: CONTACT_PROPS.split(","),
      limit: 5,
    });
  }

• src/tools/contacts.ts:4-8 (helper)

  Defines CONTACT_PROPS - a comma-joined list of standard contact property names used in the search.

  const CONTACT_PROPS = [
    "firstname", "lastname", "email", "phone", "company", "jobtitle",
    "lifecyclestage", "hs_lead_status", "createdate", "lastmodifieddate",
    "hubspot_owner_id", "hs_analytics_source",
  ].join(",");

• src/client.ts:16-48 (helper)

  Generic hubspot API client function that makes authenticated requests to the HubSpot REST API.

  export async function hubspot<T = unknown>(
    path: string,
    method: "GET" | "POST" | "PATCH" | "DELETE" = "GET",
    body?: unknown,
    params?: Record<string, string | number | boolean>,
  ): Promise<T> {
    const token = getToken();
  
    let url = `${BASE_URL}${path}`;
    if (params && method === "GET") {
      const qs = new URLSearchParams(
        Object.entries(params).map(([k, v]) => [k, String(v)]),
      ).toString();
      if (qs) url += `?${qs}`;
    }
  
    const res = await fetch(url, {
      method,
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      ...(body && method !== "GET" ? { body: JSON.stringify(body) } : {}),
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => res.statusText);
      throw new HubSpotError(`HubSpot API error (${res.status}): ${text}`, res.status);
    }
  
    if (res.status === 204) return undefined as T;
    return (await res.json()) as T;
  }