Quick Navigation
Quick Links
๐ค 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
Check Available Senders First
# ALWAYS do this before creating campaigns list_senders(api_key="your_key")
Sender Response Format
{ "senders": [ { "id": 1, "email": "sales@company.com", "display_name": "Sales Team", "status": "verified", "is_default": true, "provider": "gmail" } ] }
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 )
- If
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:
- โ
Check that
{{tokens}}
use double braces - โ
Verify sender_id exists in
list_senders()
response - โ Confirm delay_unit uses exact values: "minutes", "hours", "days", "weeks"
- โ Ensure delay_value is a number, not string
- โ 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
- ALWAYS use correct token format:
{{first_name}}
not{first_name}
- ALWAYS check available senders before creating campaigns
- ALWAYS use exact delay_unit values: "minutes", "hours", "days", "weeks"
- ALWAYS specify sender_id for campaigns to avoid using wrong sender
- ALWAYS use HTML formatting in email bodies
- TEST with sample campaigns before launching to real prospects
- 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.