# Maylng Python SDK
Python SDK for agentic email management - create email addresses and send emails programmatically for AI agents.
## Installation
```bash
pip install maylng
```
## Quick Start
```python
from maylng import Mayl
# Initialize the SDK
mayl = Mayl(api_key="your-api-key")
# Create a temporary email
email = mayl.email_addresses.create(
type="temporary",
expiration_minutes=30
)
# Send an email
sent_email = mayl.emails.send(
from_email_id=email.id,
to=[{"email": "user@example.com", "name": "User"}],
subject="Hello from AI Agent",
text="This email was sent by an AI agent!"
)
print(f"Email sent with ID: {sent_email.id}")
```
## Features
- 🚀 **Email Address Management**: Create temporary and persistent email addresses
- 📧 **Email Sending**: Send emails with attachments, scheduling, and threading
- 🤖 **AI Agent Focused**: Built specifically for AI agent email workflows
- 📊 **Analytics**: Track email delivery, opens, and clicks
- 🔒 **Secure**: API key authentication with rate limiting
- 🐍 **Pythonic**: Follows Python best practices with type hints and async support
## Advanced Usage
### Async Support
```python
import asyncio
from maylng import AsyncMayl
async def main():
mayl = AsyncMayl(api_key="your-api-key")
# Create email address
email = await mayl.email_addresses.create(
type="persistent",
prefix="support"
)
# Send email with attachment
await mayl.emails.send(
from_email_id=email.id,
to=[{"email": "user@example.com"}],
subject="Important Document",
text="Please find the attached document.",
attachments=[
{
"filename": "document.pdf",
"content_type": "application/pdf",
"content": "base64_encoded_content"
}
]
)
asyncio.run(main())
```
### Email Address Management
```python
# Create temporary email (expires in 1 hour)
temp_email = mayl.email_addresses.create(
type="temporary",
expiration_minutes=60,
prefix="agent-temp",
metadata={"purpose": "verification"}
)
# Create persistent email
persistent_email = mayl.email_addresses.create(
type="persistent",
prefix="support",
domain="custom-domain.com", # Optional
metadata={"department": "customer-service"}
)
# List all email addresses
emails = mayl.email_addresses.list(
type="temporary",
status="active",
page=1,
limit=10
)
# Extend temporary email expiration
extended_email = mayl.email_addresses.extend(
email_id=temp_email.id,
additional_minutes=30
)
# Update email metadata
updated_email = mayl.email_addresses.update(
email_id=persistent_email.id,
metadata={"updated": True},
status="active"
)
```
### Email Sending
```python
# Simple text email
simple_email = mayl.emails.send(
from_email_id=email.id,
to=[{"email": "recipient@example.com"}],
subject="Simple Text Email",
text="Hello from Maylng!"
)
# HTML email with attachments
html_email = mayl.emails.send(
from_email_id=email.id,
to=[
{"email": "user1@example.com", "name": "User One"},
{"email": "user2@example.com", "name": "User Two"}
],
cc=[{"email": "manager@example.com"}],
subject="Monthly Report",
html="""
<h2>Monthly Report</h2>
<p>Please find the monthly report attached.</p>
<p>Best regards,<br>AI Assistant</p>
""",
attachments=[
{
"filename": "report.pdf",
"content_type": "application/pdf",
"content": base64_content
}
],
metadata={"campaign": "monthly-reports"}
)
# Scheduled email
from datetime import datetime, timedelta
scheduled_email = mayl.emails.send(
from_email_id=email.id,
to=[{"email": "recipient@example.com"}],
subject="Scheduled Email",
text="This email was scheduled!",
scheduled_at=datetime.now() + timedelta(hours=1)
)
# Reply to existing thread
reply_email = mayl.emails.send(
from_email_id=email.id,
to=[{"email": "original-sender@example.com"}],
subject="Re: Original Subject",
text="This is a reply to your email.",
thread_id="thread_123"
)
```
### Email Management
```python
# List sent emails
sent_emails = mayl.emails.list(
from_email_id=email.id,
status="delivered",
since=datetime.now() - timedelta(days=7),
page=1,
limit=20
)
# Get email details
email_details = mayl.emails.get(email_id="email_123")
# Get delivery status
delivery_status = mayl.emails.get_delivery_status(email_id="email_123")
print(f"Status: {delivery_status.status}")
print(f"Opens: {delivery_status.opens}")
print(f"Clicks: {delivery_status.clicks}")
# Cancel scheduled email
mayl.emails.cancel(email_id="scheduled_email_123")
# Resend failed email
resent_email = mayl.emails.resend(email_id="failed_email_123")
```
### Error Handling
```python
from maylng.errors import (
MaylError,
AuthenticationError,
ValidationError,
RateLimitError,
EmailSendError
)
try:
email = mayl.emails.send(
from_email_id="invalid_id",
to=[{"email": "invalid-email"}],
subject="Test",
text="Test message"
)
except AuthenticationError:
print("Invalid API key")
except ValidationError as e:
print(f"Validation error: {e.message}")
if e.field:
print(f"Field: {e.field}")
except RateLimitError as e:
print(f"Rate limited. Retry after: {e.retry_after} seconds")
except EmailSendError as e:
print(f"Failed to send email: {e.message}")
print(f"Request ID: {e.request_id}")
except MaylError as e:
print(f"General Mayl error: {e.message}")
```
### Configuration
```python
# Basic configuration
mayl = Mayl(api_key="your-api-key")
# Custom configuration
mayl = Mayl(
api_key="your-api-key",
base_url="http://api.mayl.ng:8080",
timeout=60, # seconds
max_retries=3,
retry_delay=1.0 # seconds
)
# Update configuration
mayl.update_api_key("new-api-key")
mayl.update_base_url("https://new-api.example.com")
```
### Account Information
```python
# Health check
health = mayl.health_check()
print(f"API Status: {health.status}")
# Account details
account = mayl.get_account_info()
print(f"Plan: {account.plan}")
print(f"Emails used: {account.emails_sent_this_month}/{account.email_limit_per_month}")
print(f"Email addresses: {account.email_address_used}/{account.email_address_limit}")
```
## Type Safety
The Python SDK includes comprehensive type hints for better IDE support and type checking:
```python
from maylng.types import (
EmailAddress,
SentEmail,
CreateEmailAddressOptions,
SendEmailOptions,
EmailRecipient,
EmailAttachment
)
# Type-safe email creation
options: CreateEmailAddressOptions = {
"type": "temporary",
"expiration_minutes": 60,
"metadata": {"purpose": "demo"}
}
email: EmailAddress = mayl.email_addresses.create(**options)
```
## Requirements
- Python 3.8+
- httpx >= 0.25.0
- pydantic >= 2.0.0
## Error Reference
- `AuthenticationError` - Invalid API key
- `AuthorizationError` - Insufficient permissions
- `ValidationError` - Invalid input parameters
- `NotFoundError` - Resource not found
- `RateLimitError` - Rate limit exceeded
- `NetworkError` - Network connectivity issues
- `ServerError` - Server-side errors
- `TimeoutError` - Request timeout
- `EmailAddressError` - Email address specific errors
- `EmailSendError` - Email sending specific errors
## Support
- 📖 [Documentation](https://docs.maylng.com)
- 💬 [Discord Community](https://discord.gg/maylng)
- 🐛 [Issue Tracker](https://github.com/maylng/mayl-sdk/issues)
- 📧 [Email Support](mailto:support@maylng.com)
## License
MIT License - see [LICENSE](../LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "maylng",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "agentic, agents, ai, automation, email, email-api, maylng, python, sdk, smtp, temporary-email",
"author": null,
"author_email": "KnextKoder <hello@knextkoder.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/ea/e2fcff70519c81931fe72ca3ce55a203deb03738bbc97d474f0186931a68/maylng-0.3.1b2.tar.gz",
"platform": null,
"description": "# Maylng Python SDK\n\nPython SDK for agentic email management - create email addresses and send emails programmatically for AI agents.\n\n## Installation\n\n```bash\npip install maylng\n```\n\n## Quick Start\n\n```python\nfrom maylng import Mayl\n\n# Initialize the SDK\nmayl = Mayl(api_key=\"your-api-key\")\n\n# Create a temporary email\nemail = mayl.email_addresses.create(\n type=\"temporary\",\n expiration_minutes=30\n)\n\n# Send an email\nsent_email = mayl.emails.send(\n from_email_id=email.id,\n to=[{\"email\": \"user@example.com\", \"name\": \"User\"}],\n subject=\"Hello from AI Agent\",\n text=\"This email was sent by an AI agent!\"\n)\n\nprint(f\"Email sent with ID: {sent_email.id}\")\n```\n\n## Features\n\n- \ud83d\ude80 **Email Address Management**: Create temporary and persistent email addresses\n- \ud83d\udce7 **Email Sending**: Send emails with attachments, scheduling, and threading \n- \ud83e\udd16 **AI Agent Focused**: Built specifically for AI agent email workflows\n- \ud83d\udcca **Analytics**: Track email delivery, opens, and clicks\n- \ud83d\udd12 **Secure**: API key authentication with rate limiting\n- \ud83d\udc0d **Pythonic**: Follows Python best practices with type hints and async support\n\n## Advanced Usage\n\n### Async Support\n\n```python\nimport asyncio\nfrom maylng import AsyncMayl\n\nasync def main():\n mayl = AsyncMayl(api_key=\"your-api-key\")\n \n # Create email address\n email = await mayl.email_addresses.create(\n type=\"persistent\",\n prefix=\"support\"\n )\n \n # Send email with attachment\n await mayl.emails.send(\n from_email_id=email.id,\n to=[{\"email\": \"user@example.com\"}],\n subject=\"Important Document\",\n text=\"Please find the attached document.\",\n attachments=[\n {\n \"filename\": \"document.pdf\",\n \"content_type\": \"application/pdf\",\n \"content\": \"base64_encoded_content\"\n }\n ]\n )\n\nasyncio.run(main())\n```\n\n### Email Address Management\n\n```python\n# Create temporary email (expires in 1 hour)\ntemp_email = mayl.email_addresses.create(\n type=\"temporary\",\n expiration_minutes=60,\n prefix=\"agent-temp\",\n metadata={\"purpose\": \"verification\"}\n)\n\n# Create persistent email\npersistent_email = mayl.email_addresses.create(\n type=\"persistent\",\n prefix=\"support\",\n domain=\"custom-domain.com\", # Optional\n metadata={\"department\": \"customer-service\"}\n)\n\n# List all email addresses\nemails = mayl.email_addresses.list(\n type=\"temporary\",\n status=\"active\",\n page=1,\n limit=10\n)\n\n# Extend temporary email expiration\nextended_email = mayl.email_addresses.extend(\n email_id=temp_email.id,\n additional_minutes=30\n)\n\n# Update email metadata\nupdated_email = mayl.email_addresses.update(\n email_id=persistent_email.id,\n metadata={\"updated\": True},\n status=\"active\"\n)\n```\n\n### Email Sending\n\n```python\n# Simple text email\nsimple_email = mayl.emails.send(\n from_email_id=email.id,\n to=[{\"email\": \"recipient@example.com\"}],\n subject=\"Simple Text Email\",\n text=\"Hello from Maylng!\"\n)\n\n# HTML email with attachments\nhtml_email = mayl.emails.send(\n from_email_id=email.id,\n to=[\n {\"email\": \"user1@example.com\", \"name\": \"User One\"},\n {\"email\": \"user2@example.com\", \"name\": \"User Two\"}\n ],\n cc=[{\"email\": \"manager@example.com\"}],\n subject=\"Monthly Report\",\n html=\"\"\"\n <h2>Monthly Report</h2>\n <p>Please find the monthly report attached.</p>\n <p>Best regards,<br>AI Assistant</p>\n \"\"\",\n attachments=[\n {\n \"filename\": \"report.pdf\",\n \"content_type\": \"application/pdf\",\n \"content\": base64_content\n }\n ],\n metadata={\"campaign\": \"monthly-reports\"}\n)\n\n# Scheduled email\nfrom datetime import datetime, timedelta\n\nscheduled_email = mayl.emails.send(\n from_email_id=email.id,\n to=[{\"email\": \"recipient@example.com\"}],\n subject=\"Scheduled Email\",\n text=\"This email was scheduled!\",\n scheduled_at=datetime.now() + timedelta(hours=1)\n)\n\n# Reply to existing thread\nreply_email = mayl.emails.send(\n from_email_id=email.id,\n to=[{\"email\": \"original-sender@example.com\"}],\n subject=\"Re: Original Subject\",\n text=\"This is a reply to your email.\",\n thread_id=\"thread_123\"\n)\n```\n\n### Email Management\n\n```python\n# List sent emails\nsent_emails = mayl.emails.list(\n from_email_id=email.id,\n status=\"delivered\",\n since=datetime.now() - timedelta(days=7),\n page=1,\n limit=20\n)\n\n# Get email details\nemail_details = mayl.emails.get(email_id=\"email_123\")\n\n# Get delivery status\ndelivery_status = mayl.emails.get_delivery_status(email_id=\"email_123\")\nprint(f\"Status: {delivery_status.status}\")\nprint(f\"Opens: {delivery_status.opens}\")\nprint(f\"Clicks: {delivery_status.clicks}\")\n\n# Cancel scheduled email\nmayl.emails.cancel(email_id=\"scheduled_email_123\")\n\n# Resend failed email\nresent_email = mayl.emails.resend(email_id=\"failed_email_123\")\n```\n\n### Error Handling\n\n```python\nfrom maylng.errors import (\n MaylError,\n AuthenticationError,\n ValidationError,\n RateLimitError,\n EmailSendError\n)\n\ntry:\n email = mayl.emails.send(\n from_email_id=\"invalid_id\",\n to=[{\"email\": \"invalid-email\"}],\n subject=\"Test\",\n text=\"Test message\"\n )\nexcept AuthenticationError:\n print(\"Invalid API key\")\nexcept ValidationError as e:\n print(f\"Validation error: {e.message}\")\n if e.field:\n print(f\"Field: {e.field}\")\nexcept RateLimitError as e:\n print(f\"Rate limited. Retry after: {e.retry_after} seconds\")\nexcept EmailSendError as e:\n print(f\"Failed to send email: {e.message}\")\n print(f\"Request ID: {e.request_id}\")\nexcept MaylError as e:\n print(f\"General Mayl error: {e.message}\")\n```\n\n### Configuration\n\n```python\n# Basic configuration\nmayl = Mayl(api_key=\"your-api-key\")\n\n# Custom configuration\nmayl = Mayl(\n api_key=\"your-api-key\",\n base_url=\"http://api.mayl.ng:8080\",\n timeout=60, # seconds\n max_retries=3,\n retry_delay=1.0 # seconds\n)\n\n# Update configuration\nmayl.update_api_key(\"new-api-key\")\nmayl.update_base_url(\"https://new-api.example.com\")\n```\n\n### Account Information\n\n```python\n# Health check\nhealth = mayl.health_check()\nprint(f\"API Status: {health.status}\")\n\n# Account details\naccount = mayl.get_account_info()\nprint(f\"Plan: {account.plan}\")\nprint(f\"Emails used: {account.emails_sent_this_month}/{account.email_limit_per_month}\")\nprint(f\"Email addresses: {account.email_address_used}/{account.email_address_limit}\")\n```\n\n## Type Safety\n\nThe Python SDK includes comprehensive type hints for better IDE support and type checking:\n\n```python\nfrom maylng.types import (\n EmailAddress,\n SentEmail,\n CreateEmailAddressOptions,\n SendEmailOptions,\n EmailRecipient,\n EmailAttachment\n)\n\n# Type-safe email creation\noptions: CreateEmailAddressOptions = {\n \"type\": \"temporary\",\n \"expiration_minutes\": 60,\n \"metadata\": {\"purpose\": \"demo\"}\n}\n\nemail: EmailAddress = mayl.email_addresses.create(**options)\n```\n\n## Requirements\n\n- Python 3.8+\n- httpx >= 0.25.0\n- pydantic >= 2.0.0\n\n## Error Reference\n\n- `AuthenticationError` - Invalid API key\n- `AuthorizationError` - Insufficient permissions \n- `ValidationError` - Invalid input parameters\n- `NotFoundError` - Resource not found\n- `RateLimitError` - Rate limit exceeded\n- `NetworkError` - Network connectivity issues\n- `ServerError` - Server-side errors\n- `TimeoutError` - Request timeout\n- `EmailAddressError` - Email address specific errors\n- `EmailSendError` - Email sending specific errors\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://docs.maylng.com)\n- \ud83d\udcac [Discord Community](https://discord.gg/maylng)\n- \ud83d\udc1b [Issue Tracker](https://github.com/maylng/mayl-sdk/issues)\n- \ud83d\udce7 [Email Support](mailto:support@maylng.com)\n\n## License\n\nMIT License - see [LICENSE](../LICENSE) for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Maylng - Python SDK for agentic email management. Create email addresses and send emails programmatically for AI agents.",
"version": "0.3.1b2",
"project_urls": {
"Documentation": "https://docs.maylng.com",
"Homepage": "https://github.com/maylng/mayl-sdk",
"Issues": "https://github.com/maylng/mayl-sdk/issues",
"Repository": "https://github.com/maylng/mayl-sdk.git"
},
"split_keywords": [
"agentic",
" agents",
" ai",
" automation",
" email",
" email-api",
" maylng",
" python",
" sdk",
" smtp",
" temporary-email"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0add9bc500042c61aad40ec4e856d8483811b1fc2a35d95d22ab0d92f2ba4f40",
"md5": "1f384e850884ea049f65fe0918fc1b08",
"sha256": "bab3947082109b33291eb8609ce8cbece40920c3f81b1ce1c5aeed832a26df51"
},
"downloads": -1,
"filename": "maylng-0.3.1b2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f384e850884ea049f65fe0918fc1b08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22337,
"upload_time": "2025-07-08T20:53:29",
"upload_time_iso_8601": "2025-07-08T20:53:29.338111Z",
"url": "https://files.pythonhosted.org/packages/0a/dd/9bc500042c61aad40ec4e856d8483811b1fc2a35d95d22ab0d92f2ba4f40/maylng-0.3.1b2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0eae2fcff70519c81931fe72ca3ce55a203deb03738bbc97d474f0186931a68",
"md5": "c25d040067a3597ab6343f60560492a5",
"sha256": "0c61e7f80263c7a47fdca43ecb472f608cbb9e3c045bf43b760a1d6890c83f5d"
},
"downloads": -1,
"filename": "maylng-0.3.1b2.tar.gz",
"has_sig": false,
"md5_digest": "c25d040067a3597ab6343f60560492a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19391,
"upload_time": "2025-07-08T20:53:30",
"upload_time_iso_8601": "2025-07-08T20:53:30.555205Z",
"url": "https://files.pythonhosted.org/packages/f0/ea/e2fcff70519c81931fe72ca3ce55a203deb03738bbc97d474f0186931a68/maylng-0.3.1b2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 20:53:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maylng",
"github_project": "mayl-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "maylng"
}
JSON
