AI Assistant Training Guide - BuffSend MCP

AI Assistant Training Guide

AI Training Best Practices

๐Ÿค– AI Assistant Training Guide for BuffSend MCP

๐ŸŽฏ Purpose

This guide ensures AI assistants use BuffSend MCP correctly, avoiding common mistakes with personalization tokens, sender selection, and delivery scheduling.

โš ๏ธ Common AI Mistakes to Avoid

1. WRONG Personalization Tokens โŒ

{{name}} โŒ WRONG
{first_name} โŒ WRONG  
[first_name] โŒ WRONG
$first_name โŒ WRONG

2. CORRECT Personalization Tokens โœ…

{{first_name}} โœ… CORRECT
{{last_name}} โœ… CORRECT
{{company}} โœ… CORRECT
{{email}} โœ… CORRECT
{{title}} โœ… CORRECT
{{phone}} โœ… CORRECT

๐Ÿ“ Personalization Token Reference

Available Tokens

Token Description Example
{{first_name}} Contact's first name "John"
{{last_name}} Contact's last name "Smith"
{{company}} Company name "TechCorp Inc"
{{email}} Email address "john@techcorp.com"
{{title}} Job title "Marketing Director"
{{phone}} Phone number "+1-555-0123"

โœ… CORRECT Email Examples

Subject: Quick question for {{first_name}} at {{company}}

Hi {{first_name}},

I noticed {{company}} is growing rapidly in the tech space. 
As {{title}}, you might be interested in our solution...

Best regards,
Sales Team

โŒ WRONG Email Examples

Subject: Quick question for {first_name} at {company} โŒ

Hi {{name}}, โŒ (use {{first_name}} instead)

I noticed {company} is growing... โŒ (missing second brace)

๐Ÿ‘ค Sender Selection Guide

Understanding Senders

  1. Check Available Senders First

    # ALWAYS do this before creating campaigns
    list_senders(api_key="your_key")
    
  2. Sender Response Format

    {
      "senders": [
        {
          "id": 1,
          "email": "sales@company.com",
          "display_name": "Sales Team",
          "status": "verified",
          "is_default": true,
          "provider": "gmail"
        }
      ]
    }
    
  3. How to Select Senders

    • If sender_id is not specified, uses default sender
    • Always use verified senders (status: "verified")
    • For campaigns, specify sender_id in campaign creation:
      create_campaign(
      api_key="key",
      name="Campaign",
      sequence_steps=[...],
      sender_id=1  # Use specific sender ID
      )
      

Adding New Senders

# For Gmail accounts
add_gmail_sender(
    api_key="key",
    email="newteam@company.com",
    display_name="New Team",
    is_default=False
)

โฐ Delivery Scheduling & Timing

Delay Units (Use Exact Values)

delay_unit Description
"minutes" Minutes delay
"hours" Hours delay
"days" Days delay
"weeks" Weeks delay

โœ… CORRECT Campaign Step Timing

sequence_steps = [
    {
        "subject": "Introduction to {{company}}",
        "body": "Hi {{first_name}}, ...",
        "delay_value": 0,  # Send immediately
        "delay_unit": "minutes"
    },
    {
        "subject": "Follow-up for {{first_name}}",
        "body": "Hi {{first_name}}, following up...",
        "delay_value": 3,  # Wait 3 days
        "delay_unit": "days"
    },
    {
        "subject": "Final follow-up",
        "body": "Hi {{first_name}}, last chance...",
        "delay_value": 1,  # Wait 1 week
        "delay_unit": "weeks"
    }
]

โŒ WRONG Timing Examples

# Wrong delay units
"delay_unit": "day" โŒ (should be "days")
"delay_unit": "minute" โŒ (should be "minutes")
"delay_unit": "hrs" โŒ (should be "hours")

# Missing delay_value
"delay_unit": "days" โŒ (need delay_value too)

Campaign Launch Scheduling

# Schedule for future launch
schedule_campaign_launch(
    api_key="key",
    campaign_id=123,
    launch_at="2024-12-25T09:00:00",  # ISO format
    timezone="America/New_York"  # Specify timezone
)

# Launch immediately
launch_campaign(api_key="key", campaign_id=123)

๐ŸŽฏ Complete Campaign Creation Workflow

Step 1: Check Prerequisites

# 1. Verify connection
get_account_stats(api_key="key")

# 2. Check credits
get_credit_balance(api_key="key")

# 3. List available senders
list_senders(api_key="key")

Step 2: Create Campaign with Proper Formatting

create_campaign(
    api_key="key",
    name="Q4 2024 Outreach Campaign",
    sequence_steps=[
        {
            "subject": "Partnership opportunity for {{company}}",
            "body": """
            <p>Hi {{first_name}},</p>

            <p>I came across {{company}} and was impressed by your work in the industry. 
            As {{title}}, you might be interested in exploring a partnership.</p>

            <p>Would you be open to a brief 15-minute call this week?</p>

            <p>Best regards,<br>
            Partnership Team</p>
            """,
            "delay_value": 0,
            "delay_unit": "minutes"
        },
        {
            "subject": "Following up on {{company}} partnership",
            "body": """
            <p>Hi {{first_name}},</p>

            <p>I wanted to follow up on my previous email about a potential 
            partnership with {{company}}.</p>

            <p>Are you the right person to discuss this, or should I reach 
            out to someone else on your team?</p>

            <p>Thanks,<br>
            Partnership Team</p>
            """,
            "delay_value": 5,
            "delay_unit": "days"
        }
    ],
    sender_id=1,  # Use verified sender
    send_immediately=False  # Don't auto-launch
)

Step 3: Add Contacts

add_contact_to_campaign(
    api_key="key",
    campaign_id=123,
    email="john.smith@techcorp.com",
    first_name="John",
    last_name="Smith",
    company="TechCorp Inc"
)

Step 4: Launch Campaign

launch_campaign(api_key="key", campaign_id=123)

๐Ÿšจ Critical Validation Rules

Before Creating Any Campaign:

  1. โœ… Check that {{tokens}} use double braces
  2. โœ… Verify sender_id exists in list_senders() response
  3. โœ… Confirm delay_unit uses exact values: "minutes", "hours", "days", "weeks"
  4. โœ… Ensure delay_value is a number, not string
  5. โœ… Use HTML formatting in email body for better rendering

Email Content Best Practices:

  • Subject Lines: Keep under 50 characters, include {{first_name}} or {{company}}
  • Email Body: Use HTML formatting (<p>, <br>, etc.)
  • Personalization: Include at least {{first_name}} and {{company}} in each email
  • Call to Action: Clear, specific request (meeting, demo, call)

๐Ÿ” Testing & Validation

Always Test With Sample Data:

# Create test campaign first
create_campaign(
    api_key="key",
    name="TEST - Email Format Check",
    sequence_steps=[{
        "subject": "Test for {{first_name}} at {{company}}",
        "body": "<p>Hi {{first_name}},</p><p>Testing personalization...</p>",
        "delay_value": 0,
        "delay_unit": "minutes"
    }],
    sender_id=1
)

# Add test contact
add_contact_to_campaign(
    api_key="key",
    campaign_id=TEST_ID,
    email="test@example.com",
    first_name="TestUser",
    company="TestCorp"
)

๐Ÿ“Š Monitoring & Analytics

Track Campaign Performance:

# Get campaign analytics
get_campaign_analytics(api_key="key", campaign_id=123)

# Monitor specific contact journey
get_contact_journey(
    api_key="key", 
    campaign_id=123, 
    contact_email="john@techcorp.com"
)

# Check step performance
get_step_performance(api_key="key", campaign_id=123)

๐ŸŽ“ AI Assistant Guidelines Summary

  1. ALWAYS use correct token format: {{first_name}} not {first_name}
  2. ALWAYS check available senders before creating campaigns
  3. ALWAYS use exact delay_unit values: "minutes", "hours", "days", "weeks"
  4. ALWAYS specify sender_id for campaigns to avoid using wrong sender
  5. ALWAYS use HTML formatting in email bodies
  6. TEST with sample campaigns before launching to real prospects
  7. MONITOR campaign performance and adjust based on analytics

โŒ Failure Examples to Learn From

Wrong Personalization:

# DON'T DO THIS
"subject": "Hi {name}"  # Wrong syntax
"body": "Dear [first_name]"  # Wrong brackets
"body": "Hello {{name}}"  # Wrong token (use {{first_name}})

Wrong Sender Selection:

# DON'T DO THIS
create_campaign(..., sender_id="sales@company.com")  # Use ID, not email
create_campaign(..., sender_id=999)  # Non-existent sender ID

Wrong Timing:

# DON'T DO THIS
"delay_value": "3",  # Should be number: 3
"delay_unit": "day",  # Should be "days"
"delay_unit": "hrs",  # Should be "hours"

Remember: BuffSend is a powerful platform. Following these guidelines ensures professional, effective email campaigns that respect recipients and deliver results.

๐Ÿงช Test the API Live

Ready to try out the BuffSend MCP API? Test the health endpoint to verify connectivity.