Of course! Here’s a comprehensive guide on how to use the GetResponse API with Python, covering everything from setup to practical examples.

Prerequisites

Before you start, you need two things:

1. A GetResponse Account: You need an active GetResponse account.
2. Your API Key: This is the most crucial part.
   • Log in to your GetResponse account.
   • Go to Settings > API.
   • Click Create new API key.
   • Give your key a descriptive name (e.g., "My Python Script").
   • Important: Copy the generated API key immediately. You will not be able to see it again. Treat it like a password.

Installing the Official GetResponse Library

The easiest and most reliable way to interact with the GetResponse API is to use their official Python client library. It handles authentication, request formatting, and response parsing for you.

You can install it using pip:

pip install getresponse-api-client

Authentication

All requests to the GetResponse API must be authenticated using your API key. The official library makes this very simple. You just need to pass your key to the client.

from getresponse_api_client import Configuration
# Replace 'YOUR_API_KEY' with the actual key you copied
api_key = 'YOUR_API_KEY'
# Create an API configuration object
config = Configuration()
config.access_token = api_key
# You can also set the base URL if you're using a different region
# config.host = 'https://api3.getresponse.com' # Default

Making Your First API Call

Let's make a simple call to verify your connection and get your account details. This is a great way to ensure everything is set up correctly.

We'll use the ApiClient and AccountApi from the library.

from getresponse_api_client import ApiClient, AccountApi
# --- Setup (from the previous step) ---
api_key = 'YOUR_API_KEY'
config = Configuration()
config.access_token = api_key
# Create an API client instance
api_client = ApiClient(config)
# Create an instance of the Account API
account_api = AccountApi(api_client)
# --- Make the API Call ---
try:
    # Get the current account's details
    account_details = account_account_get()
    # Print the results
    print("API Connection Successful!")
    print(f"Account ID: {account_details.account_id}")
    print(f"Email: {account_details.email}")
    print(f"Name: {account_details.name}")
except Exception as e:
    print(f"An error occurred: {e}")

If this runs without errors and prints your account information, you are ready to go!

Common Practical Examples

Here are some of the most common tasks you'll want to perform with the GetResponse API using Python.

Example A: Manage Contacts (Subscribers)

This is the most frequent use case. We'll cover adding a new contact.

from getresponse_api_client import ApiClient, ContactsApi
from getresponse_api_client.model.contact import Contact
# --- Setup ---
api_key = 'YOUR_API_KEY'
config = Configuration()
config.access_token = api_key
api_client = ApiClient(config)
contacts_api = ContactsApi(api_client)
# --- Define the New Contact ---
# The 'name' field is required.
new_contact_data = {
    'name': 'John Doe',
    'email': 'john.doe@example.com',
    # Optional fields:
    'campaign': {'campaignId': 'YOUR_CAMPAIGN_ID'}, # Add to a campaign
    'dayOfCycle': 0, # Day of the campaign cycle to add the contact to
    'ipAddress': '123.45.67.89', # IP address of the subscriber
    'customFieldValues': [
        {
            'customFieldId': 'YOUR_CUSTOM_FIELD_ID',
            'value': ['Premium Member'] # Custom fields can be arrays
        }
    ]
}
try:
    # Create the contact object
    contact_to_create = Contact(**new_contact_data)
    # Make the API call to add the contact
    created_contact = contacts_api.create_contact(contact_to_create)
    print(f"Successfully added contact: {created_contact.contactId}")
    print(f"Email: {created_contact.email}")
except Exception as e:
    print(f"Error adding contact: {e}")

Note: To add a contact to a specific campaign, you need the campaignId. You can find this in the URL of your campaign in the GetResponse interface (e.g., https://app.getresponse.com/campaigns/view/abc123xyz...). The ID is the last part of the URL.

Example B: Manage Campaigns

Let's retrieve a list of all your campaigns.

from getresponse_api_client import ApiClient, CampaignsApi
from getresponse_api_client.model.campaign import Campaign
# --- Setup ---
api_key = 'YOUR_API_KEY'
config = Configuration()
config.access_token = api_key
api_client = ApiClient(config)
campaigns_api = CampaignsApi(api_client)
try:
    # Get all campaigns. You can use query parameters for pagination, filtering, etc.
    # For example, to get only active campaigns:
    # campaigns = campaigns_api.get_campaigns(query='status=active')
    all_campaigns = campaigns_api.get_campaigns()
    print("--- Your Campaigns ---")
    for campaign in all_campaigns:
        # The API returns a list of Campaign objects
        print(f"Name: {campaign.name}")
        print(f"ID: {campaign.campaign_id}")
        print(f"Status: {campaign.status}")
        print("-" * 20)
except Exception as e:
    print(f"Error fetching campaigns: {e}")

Example C: Send a Newsletter (Transactional Campaign)

This is for sending one-off emails, like a welcome email or a receipt. It's different from an automated campaign.

from getresponse_api_client import ApiClient, MessagesApi
from getresponse_api_client.model.message import Message
# --- Setup ---
api_key = 'YOUR_API_KEY'
config = Configuration()
config.access_token = api_key
api_client = ApiClient(config)
messages_api = MessagesApi(api_client)
# --- Define the Message ---
# You need a 'fromFieldId' and a 'replyToFieldId'.
# You can get these from the GetResponse UI (Settings -> My account -> Sender details)
message_data = {
    'fromField': {'fromFieldId': 'YOUR_FROM_FIELD_ID'},
    'replyTo': {'replyToFieldId': 'YOUR_REPLY_TO_FIELD_ID'},
    'subject': 'Hello from Python!',
    'text': 'This is a test transactional email sent via the GetResponse API.',
    'to': [{'contact': {'contactId': 'CONTACT_ID_TO_SEND_TO'}}] # Send to a specific contact
}
try:
    # Create the message object
    message_to_send = Message(**message_data)
    # Send the message
    sent_message = messages_api.send_message(message_to_send)
    print(f"Successfully sent message with ID: {sent_message.message_id}")
except Exception as e:
    print(f"Error sending message: {e}")

Handling API Limits (Rate Limiting)

The GetResponse API has rate limits to prevent abuse. If you make too many requests in a short period, you will get a 429 Too Many Requests error. The official library helps you handle this automatically with a built-in rate limiter.

However, it's good practice to be aware of it. The library will wait and retry the request after the specified time (Retry-After header) if it receives a 429 status, so you usually don't need to write extra code for it.

Error Handling

Always wrap your API calls in a try...except block. The library raises exceptions for various errors, including:

• ApiException: For general API errors (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found).
• ValueError or TypeError: For issues with your data (e.g., missing required fields).

Checking the status attribute of the ApiException object is very useful for debugging.

from getresponse_api_client.rest import ApiException
try:
    # ... some API call ...
    account_details = account_account_get()
except ApiException as e:
    print(f"API Error: {e.body}")
    print(f"Status Code: {e.status}")
    if e.status == 401:
        print("Error: Check your API key.")
    elif e.status == 404:
        print("Error: Resource not found.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Summary and Best Practices

1. Use the Official Library: It's the most robust and up-to-date way to interact with the API.
2. Secure Your API Key: Never hardcode your API key directly in your script if you plan to share it. Use environment variables or a configuration file.

   import os
   api_key = os.environ.get('GETRESPONSE_API_KEY')

3. Handle Errors Gracefully: Always use try...except blocks to make your scripts robust.
4. Check the Official Documentation: The GetResponse API Documentation is the ultimate source of truth. It details all endpoints, request/response models, and query parameters.
5. Pagination: For lists (like contacts or campaigns), the API returns them in pages. The library handles this, but be aware that you might need to loop through pages if you have a very large number of items.