smartlead_create_automated_placement_test

Create automated email placement tests on a schedule to evaluate deliverability across spam filters, check link domains, and monitor inbox placement using Smart Delivery.

Instructions

Create an automated placement test that runs on a schedule using Smart Delivery.

Input Schema

TableJSON Schema

Name	Required	Description
`all_email_sent_without_time_gap`	Yes	Set true to send all emails simultaneously
`campaign_id`	Yes	Campaign ID for which you want to select the sequence to test
`days`	Yes	Days of the week to run the test (1-7, where 1 is Monday)
`description`	No	Description for your test to reference later
`every_days`	Yes	Frequency of how often to run a new test
`folder_id`	No	Folder ID to assign the test to
`is_warmup`	Yes	Set true to receive positive intent responses and move emails from spam to inbox
`link_checker`	Yes	Enable to check if domains for links in email body are blacklisted
`min_time_btwn_emails`	Yes	Time gap between each email from each mailbox (if time gap enabled)
`min_time_unit`	Yes	Time unit for the time gap (minutes, hours, days)
`provider_ids`	Yes	Array of provider IDs to send test emails to
`schedule_start_time`	Yes	Start date and time to schedule or run the test (ISO format)
`sender_accounts`	Yes	Array of email addresses to use as senders
`sequence_mapping_id`	Yes	The ID of the sequence or variant you would like to test
`spam_filters`	Yes	Array of spam filters to test across, e.g. ["spam_assassin"]
`starHour`	No	Test start time
`test_end_date`	Yes	End date to stop running your test (YYYY-MM-DD format)
`test_name`	Yes	Name of your test
`tz`	Yes	Timezone for scheduling

Implementation Reference

src/handlers/smartDelivery.ts:225-263 (handler)

The core handler function that validates input parameters using isCreateAutomatedPlacementTestParams, creates a Smart Delivery API client, performs a POST request to '/spam-test/schedule' endpoint with the provided arguments, and returns the formatted response or error.

async function handleCreateAutomatedPlacementTest(
  args: unknown, 
  apiClient: AxiosInstance,
  withRetry: <T>(operation: () => Promise<T>, context: string) => Promise<T>
) {
  if (!isCreateAutomatedPlacementTestParams(args)) {
    throw new McpError(
      ErrorCode.InvalidParams,
      'Invalid arguments for smartlead_create_automated_placement_test'
    );
  }

  try {
    const smartDeliveryClient = createSmartDeliveryClient(apiClient);
    
    const response = await withRetry(
      async () => smartDeliveryClient.post('/spam-test/schedule', args),
      'create automated placement test'
    );

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
      isError: false,
    };
  } catch (error: any) {
    return {
      content: [{ 
        type: 'text', 
        text: `API Error: ${error.response?.data?.message || error.message}` 
      }],
      isError: true,
    };
  }
}

src/tools/smartDelivery.ts:82-172 (schema)

Defines the tool metadata, description, category, and complete inputSchema specifying all parameters, their types, descriptions, and required fields for creating an automated placement test.

export const CREATE_AUTOMATED_PLACEMENT_TEST_TOOL: CategoryTool = {
  name: 'smartlead_create_automated_placement_test',
  description: 'Create an automated placement test that runs on a schedule using Smart Delivery.',
  category: ToolCategory.SMART_DELIVERY,
  inputSchema: {
    type: 'object',
    properties: {
      test_name: {
        type: 'string',
        description: 'Name of your test',
      },
      description: {
        type: 'string',
        description: 'Description for your test to reference later',
      },
      spam_filters: {
        type: 'array',
        items: { type: 'string' },
        description: 'Array of spam filters to test across, e.g. ["spam_assassin"]',
      },
      link_checker: {
        type: 'boolean',
        description: 'Enable to check if domains for links in email body are blacklisted',
      },
      campaign_id: {
        type: 'integer',
        description: 'Campaign ID for which you want to select the sequence to test',
      },
      sequence_mapping_id: {
        type: 'integer',
        description: 'The ID of the sequence or variant you would like to test',
      },
      provider_ids: {
        type: 'array',
        items: { type: 'integer' },
        description: 'Array of provider IDs to send test emails to',
      },
      sender_accounts: {
        type: 'array',
        items: { type: 'string' },
        description: 'Array of email addresses to use as senders',
      },
      all_email_sent_without_time_gap: {
        type: 'boolean',
        description: 'Set true to send all emails simultaneously',
      },
      min_time_btwn_emails: {
        type: 'integer',
        description: 'Time gap between each email from each mailbox (if time gap enabled)',
      },
      min_time_unit: {
        type: 'string',
        description: 'Time unit for the time gap (minutes, hours, days)',
      },
      is_warmup: {
        type: 'boolean',
        description: 'Set true to receive positive intent responses and move emails from spam to inbox',
      },
      schedule_start_time: {
        type: 'string',
        description: 'Start date and time to schedule or run the test (ISO format)',
      },
      test_end_date: {
        type: 'string',
        description: 'End date to stop running your test (YYYY-MM-DD format)',
      },
      every_days: {
        type: 'integer',
        description: 'Frequency of how often to run a new test',
      },
      tz: {
        type: 'string',
        description: 'Timezone for scheduling',
      },
      days: {
        type: 'array',
        items: { type: 'integer' },
        description: 'Days of the week to run the test (1-7, where 1 is Monday)',
      },
      starHour: {
        type: 'string',
        description: 'Test start time',
      },
      folder_id: {
        type: 'integer',
        description: 'Folder ID to assign the test to',
      },
    },
    required: ['test_name', 'spam_filters', 'link_checker', 'campaign_id', 'sequence_mapping_id', 'provider_ids', 'sender_accounts', 'all_email_sent_without_time_gap', 'min_time_btwn_emails', 'min_time_unit', 'is_warmup', 'schedule_start_time', 'test_end_date', 'every_days', 'tz', 'days'],
  },
};

src/index.ts:217-219 (registration)
Registers the array of Smart Delivery tools (including smartlead_create_automated_placement_test) with the tool registry if the smartDelivery category is enabled by license.
```
if (enabledCategories.smartDelivery) {
  toolRegistry.registerMany(smartDeliveryTools);
}
```
src/index.ts:354-356 (registration)
Routes calls to tools in SMART_DELIVERY category (including this tool) to the handleSmartDeliveryTool dispatcher function.
```
case ToolCategory.SMART_DELIVERY:
  return await handleSmartDeliveryTool(name, toolArgs, apiClient, withRetry);
case ToolCategory.WEBHOOKS:
```
src/handlers/smartDelivery.ts:50-52 (handler)
Switch case dispatcher within handleSmartDeliveryTool that directs to the specific handler for this tool.
```
case 'smartlead_create_automated_placement_test': {
  return handleCreateAutomatedPlacementTest(args, apiClient, withRetry);
}
```

Smartlead Simplified MCP Server