addContactToList

Instructions

Implementation Reference

• src/apicalls/contactManagement.ts:11-42 (handler)

  The main handler function that makes the POST request to Mailmodo API (https://api.mailmodo.com/api/v1/addToList) with the contact payload and API key. Validates email and listName are present, then returns response data.

  export async function addContactToList(
      mmApiKey: string,
      payload: MailmodoContact
  ): Promise<AddContactToListResponse> {
  
      if (!payload.email || !payload.listName) {
          throw new Error('Email and listname are required fields');
      }
  
      try {
          const response = await axios.post<AddContactToListResponse>(
              'https://api.mailmodo.com/api/v1/addToList',
              {
                  ...payload,
              },
              {
                  headers: {
                      'Accept': 'application/json',
                      'Content-Type': 'application/json',
                      'mmApiKey': mmApiKey || ''
                  }
              }
          );
  
          return response.data;
      } catch (error) {
          if (error instanceof AxiosError) {
              return {success: false}
          }
          throw new Error('An unexpected error occurred');
      }
  }

• src/server.ts:153-195 (registration)

  The MCP server tool registration for 'addContactToList'. Defines input schema (email, listName, optional data/created_at/last_click/last_open/timezone), calls the handler, and formats the response.

  server.tool(
    "addContactToList",
    "Add Contact to list ",
    {
        email: z.string(),
        listName: z.string(),
        data: contactPropertiesSchema.optional(),
        created_at: datetimeSchema.optional(),
        last_click: datetimeSchema.optional(),
        last_open: datetimeSchema.optional(),
        timezone: z
          .string()
          .regex(
            timezoneRegex,
            { message: "Must be a valid region-format timezone string" }
          )
          .optional(),
    },
    async (params) => {
      try {
        const respone = await addContactToList(mmApiKey,params);
        
        // Here you would typically integrate with your event sending system
        // For example: eventBus.emit(eventName, eventData)
        
        // For demonstration, we'll just return a success message
        return {
          content: [{
            type: "text",
            text: respone.success?`Successfully added contact '${params.email}' to list ${params.listName} with message ${respone.message}.`: `Something went wrong. Please check if the email is correct`,
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: error instanceof Error ? error.message : "Failed to send event",
          }],
          isError: true
        };
      }
    }
  );

• src/types/addContactsTypes.ts:31-39 (schema)

  The MailmodoContact interface defining the input shape for the addContactToList handler: email, listName, data (UserProperties), created_at, last_click, last_open, and timezone.

  export interface MailmodoContact {
      email: string;
      listName: string;
      data?: UserProperties;
      created_at?: string;  // ISO 8601 or UNIX timestamp
      last_click?: string;  // ISO 8601 or UNIX timestamp
      last_open?: string;   // ISO 8601 or UNIX timestamp
      timezone?: string;   // Region format timezone
  }

• src/types/addContactsTypes.ts:77-81 (schema)

  The AddContactToListResponse interface defining the API response shape with success boolean and optional message string.

  export interface AddContactToListResponse {
      // Define your expected response structure here
      success: boolean;
      message?: string;
  }

• src/types/addContactsTypes.ts:54-76 (helper)

  The contactPropertiesSchema Zod schema used for the optional 'data' field in the tool input. Supports standard contact fields (name, email, phone, address, etc.) with catchall for custom properties.

  export const contactPropertiesSchema = z.object({
    first_name: z.string().describe("First name of the user").optional(),
    last_name: z.string().describe("Last name of the user").optional(),
    name: z.string().describe("Full name of the user").optional(),
    gender: z.string().describe("Gender of the user").optional(),
    age: z.number().int().describe("Age of the user in numbers").optional(),
    birthday: dateSchema.describe("Birthdate of the user (ISO format or UNIX timestamp)").optional(),
    phone: z.string().describe("Primary phone number of the user").optional(),
    address1: z.string().describe("Line 1 of the address of the user").optional(),
    address2: z.string().describe("Line 2 of the address of the user").optional(),
    city: z.string().describe("City/district/village of the user").optional(),
    state: z.string().describe("State, region or province of the user").optional(),
    country: z.string().describe("Country of the user").optional(),
    postal_code: z.string().describe("PIN/ZIP Code of the user").optional(),
    designation: z.string().describe("Designation of the user").optional(),
    company: z.string().describe("Company of the user").optional(),
    industry: z.string().describe("Industry of the user").optional(),
    description: z.string().describe("Description of the user").optional(),
    anniversary_date: dateSchema.describe("Anniversary date (ISO format or UNIX timestamp)").optional(),
  }).catchall(
    // Allow any additional key-value pairs of types: string, number, boolean, or undefined
    z.union([z.string(), z.number(), z.boolean(), z.undefined()])
  );