Hi *|FNAME|*,
Here's what's new this week...
"""
content = {"html": html_content}
client.campaigns.set_content(campaign_id, content)
```
#### Send Test Email
```python
test_emails = {
"test_emails": ["test@example.com", "developer@example.com"],
"send_type": "html"
}
client.campaigns.send_test_email(campaign_id, test_emails)
print("Test email sent")
```
#### Schedule or Send Campaign
```python
# Send immediately
client.campaigns.send(campaign_id)
# Or schedule for later
from datetime import datetime, timedelta
schedule_time = datetime.utcnow() + timedelta(hours=2)
schedule_data = {
"schedule_time": schedule_time.isoformat() + "Z"
}
client.campaigns.schedule(campaign_id, schedule_data)
```
### 3. A/B Testing
```python
# Create A/B test campaign
ab_campaign = {
"type": "variate",
"recipients": {
"list_id": list_id
},
"variate_settings": {
"winner_criteria": "opens", # opens, clicks, manual, total_revenue
"wait_time": 60, # minutes to wait before sending winner
"test_size": 10, # percentage for testing
"subject_lines": [
"Subject Line A - Question?",
"Subject Line B - Statement!",
"Subject Line C - Emoji 🎉"
]
},
"settings": {
"title": "A/B Test Campaign",
"from_name": "My Company",
"reply_to": "hello@mycompany.com"
}
}
ab_test = client.campaigns.create(ab_campaign)
```
### 4. Automation Workflows
#### Create Automation
```python
automation_data = {
"recipients": {
"list_id": list_id
},
"settings": {
"title": "Welcome Series",
"from_name": "My Company",
"reply_to": "hello@mycompany.com"
},
"trigger_settings": {
"workflow_type": "welcomeSeries"
}
}
automation = client.automations.create(automation_data)
automation_id = automation["id"]
```
#### Add Email to Automation
```python
email_data = {
"settings": {
"subject_line": "Welcome to Our Community!",
"preview_text": "Thanks for joining us",
"title": "Welcome Email",
"from_name": "My Company",
"reply_to": "hello@mycompany.com"
},
"delay": {
"amount": 0,
"type": "now",
"direction": "after"
}
}
workflow_email = client.automations.add_workflow_email(automation_id, email_data)
```
### 5. Segmentation
```python
# Create segment based on conditions
segment_data = {
"name": "Active VIP Customers",
"static_segment": [],
"options": {
"match": "all",
"conditions": [
{
"condition_type": "TextMerge",
"field": "FNAME",
"op": "contains",
"value": ""
},
{
"condition_type": "Interests",
"field": "interests-123",
"op": "interestcontains",
"value": ["vip"]
}
]
}
}
segment = client.lists.create_segment(list_id, segment_data)
segment_id = segment["id"]
```
### 6. Analytics and Reporting
#### Get Campaign Reports
```python
# Get specific campaign report
report = client.reports.get_campaign_report(campaign_id)
print(f"Campaign: {report['campaign_title']}")
print(f"Emails sent: {report['emails_sent']}")
print(f"Opens: {report['opens']['opens_total']} ({report['opens']['open_rate']}%)")
print(f"Clicks: {report['clicks']['clicks_total']} ({report['clicks']['click_rate']}%)")
print(f"Unsubscribes: {report['unsubscribed']}")
```
#### Get Click Details
```python
# Get URLs clicked in campaign
click_details = client.reports.get_campaign_click_details(campaign_id)
for url in click_details["urls_clicked"]:
print(f"URL: {url['url']}")
print(f"Total clicks: {url['total_clicks']}")
print(f"Unique clicks: {url['unique_clicks']}")
```
#### Get Subscriber Activity
```python
# Get activity for specific subscriber
subscriber_hash = "subscriber-hash" # MD5 hash of lowercase email
activity = client.reports.get_email_activity_for_subscriber(
campaign_id,
subscriber_hash
)
for action in activity["activity"]:
print(f"{action['action']} at {action['timestamp']}")
```
### 7. Tags Management
```python
# Add tags to subscriber
subscriber_email = "subscriber@example.com"
import hashlib
subscriber_hash = hashlib.md5(subscriber_email.lower().encode()).hexdigest()
tag_data = {
"tags": [
{"name": "premium", "status": "active"},
{"name": "webinar-attendee", "status": "active"}
]
}
client.lists.update_list_member_tags(list_id, subscriber_hash, tag_data)
```
## Common Patterns
### Error Handling
```python
from mailchimp_marketing.api_client import ApiClientError
try:
response = client.lists.get_list(list_id)
except ApiClientError as error:
print(f"Error: {error.text}")
if error.status_code == 404:
print("List not found")
elif error.status_code == 401:
print("Invalid API key")
```
### Pagination for Large Datasets
```python
def get_all_subscribers(list_id):
offset = 0
count = 1000
all_members = []
while True:
response = client.lists.get_list_members_info(
list_id,
count=count,
offset=offset
)
all_members.extend(response["members"])
if len(response["members"]) < count:
break
offset += count
return all_members
```
### Update Subscriber Profile
```python
# Update or add subscriber (upsert)
subscriber_hash = hashlib.md5("user@example.com".lower().encode()).hexdigest()
update_data = {
"email_address": "user@example.com",
"status_if_new": "subscribed",
"merge_fields": {
"FNAME": "Updated Name",
"LNAME": "New Last Name",
"PHONE": "555-1234"
}
}
client.lists.set_list_member(list_id, subscriber_hash, update_data)
```
## Troubleshooting
### Invalid API Key
- Ensure `MAILCHIMP_API_KEY` is set correctly
- Verify the server prefix matches your account (check API key suffix)
- Test API key in Mailchimp dashboard under Account > Extras > API keys
### Rate Limiting
Mailchimp has rate limits (typically 10 requests/second):
```python
import time
def rate_limited_batch(items, process_func, delay=0.1):
results = []
for item in items:
results.append(process_func(item))
time.sleep(delay)
return results
```
### List Already Exists Error
When creating lists, use unique names or handle the error:
```python
try:
new_list = client.lists.create_list(list_data)
except ApiClientError as e:
if "already exists" in e.text.lower():
print("List name already in use")
```
### Subscriber Hash Calculation
Always use lowercase email and MD5 hash:
```python
import hashlib
def get_subscriber_hash(email):
return hashlib.md5(email.lower().strip().encode()).hexdigest()
```
### Testing Without Sending
Use the test email feature before sending to full lists:
```python
# Always send test first
client.campaigns.send_test_email(campaign_id, {
"test_emails": [os.getenv("TEST_EMAIL")],
"send_type": "html"
})
# Verify before sending
input("Press Enter to send to full list...")
client.campaigns.send(campaign_id)
```
## Best Practices
1. **Use batch operations** for adding multiple subscribers
2. **Implement proper error handling** for all API calls
3. **Respect rate limits** with delays between requests
4. **Store list IDs** in configuration rather than hardcoding
5. **Use merge tags** (`*|FNAME|*`) for personalization
6. **Test campaigns** before sending to full audiences
7. **Monitor analytics** regularly to optimize performance
8. **Clean lists** periodically by removing inactive subscribers