contacted 0.0.11

Python SDK for Contacted email API service

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-250 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-250 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