contacted 0.0.6

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': '[e-mail]',
    'to': '[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

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

options: Dict[str, Any] = {
    'subject': 'Email subject line',
    'from': '[e-mail]',
    'to': '[e-mail]',
    'prompt': 'Generate email content',
    'data': {'name': 'John'}
}

result = contacted.send(options)

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(options)

Send a message through the ContactedAI API.

Parameters:

• subject (string, required): Email subject (2-256 characters)
• from (str, required): Valid sender email address
• to (str, required): Valid receiver email address
• prompt (str, required): AI prompt (10-250 characters)
• data (dict, optional): Additional data for personalization

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.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': 'invalid-email',
        'to': '[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': '[e-mail]',
    'to': '[e-mail]', 
    'prompt': 'Create a welcome email for a new premium user',
    'data': {
        'username': 'john_doe',
        'plan': 'premium',
        'dashboard_url': 'https://app.myservice.com'
    }
})

With Error Handling

try:
    result = contacted.send(options)
    print(f'✅ Email sent successfully: {result["id"]}')
except ValueError as e:
    if 'Invalid' in str(e):
        print(f'❌ Validation error: {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
)

License

MIT

Support

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