contacted

Contacted Python API Library

Official Python SDK for the Contacted API.

Getting Started

1. Get Your API Key

First, sign up and get your API key at https://contacted.io

2. Installation

pip install contacted

Quick Start

from contacted import ContactedAI

contacted = ContactedAI(api_key='your-api-key-here')

# Send a message
result = contacted.send(
    subject='Thank you for signing up with Example',
    from_email='[e-mail]',
    to_email='[e-mail]',
    prompt='Generate a personalized welcome email',
    data={
        'name': 'John Doe',
        'link': 'https://example.com'
    }
)

print('Message sent:', result)

Type Hints Support

The SDK includes comprehensive type hints for better IDE support:

from contacted import ContactedAI
from typing import Dict, Any, Optional

contacted = ContactedAI(api_key='your-api-key-here')

# All parameters are strongly typed
result = contacted.send(
    subject="Email subject line",
    from_email="[e-mail]",
    to_email="[e-mail]", 
    prompt="Generate email content",
    data={'name': 'John'},
    sending_profile="profile-id"  # Optional
)

API Reference

ContactedAI(api_key, base_url=None, timeout=30)

Creates a new ContactedAI client instance.

Parameters:

• api_key (str, required): Your ContactedAI API key
• base_url (str, optional): Custom API base URL
• timeout (int, optional): Request timeout in seconds (default: 30)

contacted.send(subject, from_email, to_email, prompt, data=None, sending_profile=None)

Send a message through the ContactedAI API.

Parameters:

• subject (str, required): Email subject (2-256 characters)
• from_email (str, required): Valid sender email address
• to_email (str, required): Valid receiver email address
• prompt (str, required): AI prompt (10-2000 characters)
• data (dict, optional): Additional data for personalization
• sending_profile (str, optional): Sending profile ID

Validation Rules:

• Subject must be 2-256 characters
• Email addresses must be valid format
• Prompt must be 10-2000 characters
• Data keys cannot contain spaces
• Data keys must be non-empty strings

Returns: dict - API response

Raises: ValueError - If validation fails or API error occurs

contacted.get_message_status(message_id)

Get the status of a sent message.

Parameters:

• message_id (str, required): The unique message ID returned from send()

Returns: dict - Message status information containing:

• id (str): Message ID
• status (str): Current status (queued, sent, failed)
• message (str): Human-readable status message
• created_at (str): Message creation timestamp
• updated_at (str): Last status update timestamp
• sent_at (str, optional): Delivery timestamp (when status is 'sent')
• error_reason (str, optional): Error description (when status is 'failed')

Raises: ValueError - If message_id is invalid or API error occurs

contacted.status()

Check the API status and health.

Returns: dict - Status information

Error Handling

The SDK provides detailed error messages for validation and API errors:

try:
    contacted.send(
        subject='test error',
        from_email='invalid-email',
        to_email='[e-mail]',
        prompt='short'
    )
except ValueError as e:
    print(f'Error: {e}')
    # "Invalid 'from' email address format"

Examples

Basic Usage

from contacted import ContactedAI
import os

contacted = ContactedAI(api_key=os.getenv('CONTACTED_API_KEY'))

result = contacted.send(
    subject='A warm welcome from my service',
    from_email='[e-mail]',
    to_email='[e-mail]', 
    prompt='Create a welcome email for a new premium user',
    data={
        'username': 'john_doe',
        'plan': 'premium',
        'dashboard_url': 'https://app.myservice.com'
    }
)

Send and Track Message Status

from contacted import ContactedAI
import time

contacted = ContactedAI(api_key='your-api-key-here')

# Send message
result = contacted.send(
    subject='Your order confirmation',
    from_email='[e-mail]',
    to_email='[e-mail]',
    prompt='Generate an order confirmation email',
    data={
        'order_id': '12345',
        'total': '$99.99',
        'delivery_date': '2024-01-20'
    }
)

message_id = result['id']
print(f'✅ Message queued with ID: {message_id}')

# Check status
status = contacted.get_message_status(message_id)
print(f'📧 Status: {status["status"]} - {status["message"]}')

# Poll for completion (optional)
while status['status'] == 'queued':
    time.sleep(2)
    status = contacted.get_message_status(message_id)
    print(f'📧 Status: {status["status"]}')

if status['status'] == 'sent':
    print(f'✅ Message delivered at {status["sent_at"]}')
elif status['status'] == 'failed':
    print(f'❌ Message failed: {status["error_reason"]}')

With Error Handling

try:
    result = contacted.send(
        subject='Order confirmation',
        from_email='[e-mail]',
        to_email='[e-mail]',
        prompt='Generate order confirmation with tracking info',
        data={'order_id': '12345'}
    )
    print(f'✅ Email sent successfully: {result["id"]}')
    
    # Check status
    status = contacted.get_message_status(result['id'])
    print(f'📧 Current status: {status["status"]}')
    
except ValueError as e:
    if 'Invalid' in str(e):
        print(f'❌ Validation error: {e}')
    elif 'not found' in str(e):
        print(f'❌ Message not found: {e}')
    else:
        print(f'❌ API error: {e}')

Environment Variables

import os
from contacted import ContactedAI

# Use environment variable for API key
contacted = ContactedAI(
    api_key=os.getenv('CONTACTED_API_KEY'),
    timeout=60  # Custom timeout
)

result = contacted.send(
    subject='Weekly newsletter',
    from_email='[e-mail]',
    to_email='[e-mail]',
    prompt='Create an engaging weekly newsletter',
    data={'subscriber_name': 'Alex'}
)

License

MIT

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: contacted.gitbook.io