Mailmodo

Instructions

Implementation Reference

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

  MCP tool registration, input schema, and handler function for 'addContactToList'. The handler calls the API helper, handles errors, and returns a text 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/apicalls/contactManagement.ts:11-42 (helper)

  Helper function implementing the core logic: validates input, makes axios POST to Mailmodo API /addToList endpoint, returns typed response or error.

  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/types/addContactsTypes.ts:54-81 (schema)

  Zod schema for contact properties (data field) and TypeScript interface for the API response used in addContactToList.

  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()])
  );
  export interface AddContactToListResponse {
      // Define your expected response structure here
      success: boolean;
      message?: string;
  }

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

  TypeScript interface defining the payload structure for MailmodoContact used in the addContactToList API call.

  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
  }