A comprehensive Python client for interacting with the GetResponse API v3. This library provides easy-to-use methods for managing contacts, campaigns, and performing email marketing operations.
- ✅ Contact Management: Add, remove, update, and search contacts
- ✅ Campaign Operations: Get campaign lists and details
- ✅ Error Handling: Comprehensive error handling and validation
- ✅ Environment Variables: Secure API key management
- ✅ Type Hints: Full type annotations for better development experience
- ✅ Documentation: Extensive docstrings and examples
- Install dependencies:
pip install -r requirements.txt
2. **Set up environment variables**:
```bash
cp .env.example .env
# Edit .env and add your GetResponse API key
```
3. **Get your API key**:
* Go to [https://app.getresponse.com/api](https://app.getresponse.com/api)
* Generate a new API key
* Add it to your `.env` file
## Quick Start
```python
from getresponse_client import GetResponseClient
# Initialize client (automatically loads API key from .env)
client = GetResponseClient()
# Test connection
if client.test_connection():
print("Connected successfully!")
# Get all campaigns
campaigns = client.get_campaigns()
for campaign in campaigns:
print(f"{campaign['name']}: {campaign['campaignId']}")
# Add a contact to first campaign
if campaigns:
result = client.add_contact(
email='user@example.com',
campaign_id=campaigns[0]['campaignId'],
name='John Doe'
)
print(f"Contact added: {result}")
```
## Available Methods
### Contact Management
* `add_contact(email, campaign_id, name=None, day_of_cycle=None, custom_fields=None)`
* `remove_contact(contact_id)`
* `remove_contact_by_email(email, campaign_id=None)`
* `get_contact(contact_id)`
* `get_contact_by_email(email, campaign_id=None)`
* `search_contacts(query=None, campaign_id=None, email=None, limit=100)`
* `update_contact(contact_id, name=None, campaign_id=None, custom_fields=None)`
### Campaign Management
* `get_campaigns()`
* `get_campaign_by_name(campaign_name)`
* `get_campaign_by_id(campaign_id)`
#### Example: Get Campaign Details by ID
```python
campaign = client.get_campaign_by_id("MV2gN")
import json
print(json.dumps(campaign, indent=2, ensure_ascii=False))
```
This returns detailed campaign information including confirmation settings, opt-in types, and postal profile data.
### Account Operations
* `get_account_info()`
* `test_connection()`
## Examples
### Add a Contact
```python
client.add_contact(
email='john@example.com',
campaign_id='abc123',
name='John Smith',
day_of_cycle=0,
custom_fields={'field1': 'value1'}
)
```
### Remove a Contact by Email
```python
success = client.remove_contact_by_email('john@example.com')
if success:
print("Contact removed successfully")
```
### Search Contacts
```python
# Search by name or email
contacts = client.search_contacts(query='john')
# Search by exact email
contact = client.get_contact_by_email('john@example.com')
# Search in specific campaign
contacts = client.search_contacts(campaign_id='abc123', limit=50)
```
## Error Handling
The client includes comprehensive error handling:
```python
try:
client.add_contact(email='invalid', campaign_id='abc123')
except ValueError as e:
print(f"Error: {e}")
```
Common errors:
* `ValueError: Unauthorized: Invalid API key` - Check your API key
* `ValueError: Resource not found` - Invalid campaign or contact ID
* `ValueError: Rate limit exceeded` - Too many requests
## File Structure
```
.
├── getresponse_client.py # Main client class
├── example_usage.py # Basic usage examples
├── practical_example.py # Advanced usage examples
├── requirements.txt # Python dependencies
├── .env.example # Environment template
└── README.md # This file
```
## Support
For GetResponse API issues, refer to the official documentation:
* [GetResponse API Docs](https://apidocs.getresponse.com/v3)
* [API Reference](https://apireference.getresponse.com/)
## License
This project is provided as-is for educational and integration purposes.
---
**Note:** The entire repository was written by large language models (LLMs) managed and instructed through [Agent Zero](https://github.com/agent0ai/agent-zero).