# Contacted Python SDK
Official Python SDK for the Contacted API.
[](https://badge.fury.io/py/contacted)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/contacted/)
## Getting Started
### 1. Get Your API Key
First, sign up and get your API key at [https://contacted.io](https://contacted.io)
### 2. Installation
```bash
pip install contacted
```
## Quick Start
```python
from contacted import ContactedAI
contacted = ContactedAI(api_key='your-api-key-here')
# Send a message
result = contacted.send({
'from': 'sender@example.com',
'to': 'receiver@example.com',
'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:
```python
from contacted import ContactedAI
from typing import Dict, Any
contacted = ContactedAI(api_key='your-api-key-here')
options: Dict[str, Any] = {
'from': 'sender@example.com',
'to': 'receiver@example.com',
'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:**
- `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:**
- 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:
```python
try:
contacted.send({
'from': 'invalid-email',
'to': 'user@example.com',
'prompt': 'short'
})
except ValueError as e:
print(f'Error: {e}')
# "Invalid 'from' email address format"
```
## Examples
### Basic Usage
```python
from contacted import ContactedAI
import os
contacted = ContactedAI(api_key=os.getenv('CONTACTED_API_KEY'))
result = contacted.send({
'from': 'noreply@myapp.com',
'to': 'user@example.com',
'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
```python
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
```python
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: support@contacted.io
- 🐛 Issues: [GitHub Issues](https://github.com/LawrenceGB/contacted-python/issues)
- 📖 Documentation: [contacted.gitbook.io](https://contacted.gitbook.io)
Raw data
{
"_id": null,
"home_page": "https://github.com/LawrenceGB/contacted-python",
"name": "contacted",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "email, api, contacted, transactional-email",
"author": "Your Name",
"author_email": "ContactedAI <lawrence@contacted.io>",
"download_url": "https://files.pythonhosted.org/packages/29/d8/63dfb6046a785bbf8efe1da26b048171a0f8d4dbd119b018ca51a0488df2/contacted-0.0.4.tar.gz",
"platform": null,
"description": "# Contacted Python SDK\n\nOfficial Python SDK for the Contacted API.\n\n[](https://badge.fury.io/py/contacted)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/contacted/)\n\n## Getting Started\n\n### 1. Get Your API Key\n\nFirst, sign up and get your API key at [https://contacted.io](https://contacted.io)\n\n### 2. Installation\n\n```bash\npip install contacted\n```\n\n## Quick Start\n\n```python\nfrom contacted import ContactedAI\n\ncontacted = ContactedAI(api_key='your-api-key-here')\n\n# Send a message\nresult = contacted.send({\n 'from': 'sender@example.com',\n 'to': 'receiver@example.com',\n 'prompt': 'Generate a personalized welcome email',\n 'data': {\n 'name': 'John Doe',\n 'link': 'https://example.com'\n }\n})\n\nprint('Message sent:', result)\n```\n\n## Type Hints Support\n\nThe SDK includes comprehensive type hints for better IDE support:\n\n```python\nfrom contacted import ContactedAI\nfrom typing import Dict, Any\n\ncontacted = ContactedAI(api_key='your-api-key-here')\n\noptions: Dict[str, Any] = {\n 'from': 'sender@example.com',\n 'to': 'receiver@example.com',\n 'prompt': 'Generate email content',\n 'data': {'name': 'John'}\n}\n\nresult = contacted.send(options)\n```\n\n## API Reference\n\n### `ContactedAI(api_key, base_url=None, timeout=30)`\n\nCreates a new ContactedAI client instance.\n\n**Parameters:**\n- `api_key` (str, required): Your ContactedAI API key\n- `base_url` (str, optional): Custom API base URL\n- `timeout` (int, optional): Request timeout in seconds (default: 30)\n\n### `contacted.send(options)`\n\nSend a message through the ContactedAI API.\n\n**Parameters:**\n- `from` (str, required): Valid sender email address\n- `to` (str, required): Valid receiver email address\n- `prompt` (str, required): AI prompt (10-250 characters)\n- `data` (dict, optional): Additional data for personalization\n\n**Validation Rules:**\n- Email addresses must be valid format\n- Prompt must be 10-250 characters\n- Data keys cannot contain spaces\n- Data keys must be non-empty strings\n\n**Returns:** `dict` - API response\n\n**Raises:** `ValueError` - If validation fails or API error occurs\n\n### `contacted.status()`\n\nCheck the API status and health.\n\n**Returns:** `dict` - Status information\n\n## Error Handling\n\nThe SDK provides detailed error messages for validation and API errors:\n\n```python\ntry:\n contacted.send({\n 'from': 'invalid-email',\n 'to': 'user@example.com',\n 'prompt': 'short'\n })\nexcept ValueError as e:\n print(f'Error: {e}')\n # \"Invalid 'from' email address format\"\n```\n\n## Examples\n\n### Basic Usage\n```python\nfrom contacted import ContactedAI\nimport os\n\ncontacted = ContactedAI(api_key=os.getenv('CONTACTED_API_KEY'))\n\nresult = contacted.send({\n 'from': 'noreply@myapp.com',\n 'to': 'user@example.com', \n 'prompt': 'Create a welcome email for a new premium user',\n 'data': {\n 'username': 'john_doe',\n 'plan': 'premium',\n 'dashboard_url': 'https://app.myservice.com'\n }\n})\n```\n\n### With Error Handling\n```python\ntry:\n result = contacted.send(options)\n print(f'\u2705 Email sent successfully: {result[\"id\"]}')\nexcept ValueError as e:\n if 'Invalid' in str(e):\n print(f'\u274c Validation error: {e}')\n else:\n print(f'\u274c API error: {e}')\n```\n\n### Environment Variables\n```python\nimport os\nfrom contacted import ContactedAI\n\n# Use environment variable for API key\ncontacted = ContactedAI(\n api_key=os.getenv('CONTACTED_API_KEY'),\n timeout=60 # Custom timeout\n)\n```\n\n## License\n\nMIT\n\n## Support\n\n- \ud83d\udce7 Email: support@contacted.io\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/LawrenceGB/contacted-python/issues)\n- \ud83d\udcd6 Documentation: [contacted.gitbook.io](https://contacted.gitbook.io)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Contacted email API service",
"version": "0.0.4",
"project_urls": {
"Documentation": "https://contacted.gitbook.io",
"Homepage": "https://contacted.io",
"Repository": "https://github.com/LawrenceGB/contacted-python"
},
"split_keywords": [
"email",
" api",
" contacted",
" transactional-email"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "743655446c2b369741914047785cc1914dc7cecaf7e40471b0aac02b80d94c22",
"md5": "3a24a99b4278e3190223ae041e9019b7",
"sha256": "ce3d80e20710f9bff38757815469147b4eef4c10c3ef63c813d045df38802662"
},
"downloads": -1,
"filename": "contacted-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a24a99b4278e3190223ae041e9019b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5942,
"upload_time": "2025-05-24T06:52:47",
"upload_time_iso_8601": "2025-05-24T06:52:47.143095Z",
"url": "https://files.pythonhosted.org/packages/74/36/55446c2b369741914047785cc1914dc7cecaf7e40471b0aac02b80d94c22/contacted-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "29d863dfb6046a785bbf8efe1da26b048171a0f8d4dbd119b018ca51a0488df2",
"md5": "a216294ab8531caf2b3b3b1d08d1d892",
"sha256": "56449f3f3be305798fa53ba8489b883357d9e9a6dfaa8dd579ecfd62ae2bd0ae"
},
"downloads": -1,
"filename": "contacted-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "a216294ab8531caf2b3b3b1d08d1d892",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8317,
"upload_time": "2025-05-24T06:52:48",
"upload_time_iso_8601": "2025-05-24T06:52:48.600245Z",
"url": "https://files.pythonhosted.org/packages/29/d8/63dfb6046a785bbf8efe1da26b048171a0f8d4dbd119b018ca51a0488df2/contacted-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-05-24 06:52:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LawrenceGB",
"github_project": "contacted-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
}
],
"lcname": "contacted"
}
JSON
