tosend 1.0.0__py3-none-any.whl

tosend/__init__.py

@@ -0,0 +1,34 @@
+"""
+ToSend Python SDK
+
+Official Python SDK for the ToSend email API.
+"""
+
+from .client import ToSend
+from .exceptions import ToSendError
+from .types import (
+    Address,
+    Attachment,
+    SendEmailRequest,
+    SendEmailResponse,
+    BatchEmailResult,
+    BatchEmailResponse,
+    Domain,
+    Account,
+    AccountInfo,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "ToSend",
+    "ToSendError",
+    "Address",
+    "Attachment",
+    "SendEmailRequest",
+    "SendEmailResponse",
+    "BatchEmailResult",
+    "BatchEmailResponse",
+    "Domain",
+    "Account",
+    "AccountInfo",
+]

tosend/client.py

@@ -0,0 +1,201 @@
+"""ToSend API client."""
+
+import json
+from typing import Optional, Dict, Any, List, Union
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError, URLError
+
+from .types import (
+    Address,
+    SendEmailRequest,
+    SendEmailResponse,
+    BatchEmailResponse,
+    AccountInfo,
+)
+from .exceptions import ToSendError
+
+
+class ToSend:
+    """ToSend API client."""
+
+    DEFAULT_BASE_URL = "https://api.tosend.com"
+    DEFAULT_TIMEOUT = 30
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: Optional[int] = None,
+    ):
+        """
+        Initialize ToSend client.
+
+        Args:
+            api_key: Your ToSend API key
+            base_url: Custom base URL (optional)
+            timeout: Request timeout in seconds (optional)
+        """
+        if not api_key or not api_key.strip():
+            raise ToSendError("API key is required", 401, "unauthorized")
+
+        self.api_key = api_key.strip()
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout or self.DEFAULT_TIMEOUT
+
+    def send(
+        self,
+        *,
+        from_address: Union[Address, Dict[str, str]],
+        to: List[Union[Address, Dict[str, str]]],
+        subject: str,
+        html: Optional[str] = None,
+        text: Optional[str] = None,
+        cc: Optional[List[Union[Address, Dict[str, str]]]] = None,
+        bcc: Optional[List[Union[Address, Dict[str, str]]]] = None,
+        reply_to: Optional[Union[Address, Dict[str, str]]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        attachments: Optional[List[Dict[str, str]]] = None,
+    ) -> SendEmailResponse:
+        """
+        Send a single email.
+
+        Args:
+            from_address: Sender address
+            to: List of recipient addresses
+            subject: Email subject
+            html: HTML content
+            text: Plain text content
+            cc: CC recipients
+            bcc: BCC recipients
+            reply_to: Reply-to address
+            headers: Custom headers
+            attachments: File attachments
+
+        Returns:
+            SendEmailResponse with message_id
+        """
+        data: Dict[str, Any] = {
+            "from": self._to_address_dict(from_address),
+            "to": [self._to_address_dict(addr) for addr in to],
+            "subject": subject,
+        }
+
+        if html:
+            data["html"] = html
+        if text:
+            data["text"] = text
+        if cc:
+            data["cc"] = [self._to_address_dict(addr) for addr in cc]
+        if bcc:
+            data["bcc"] = [self._to_address_dict(addr) for addr in bcc]
+        if reply_to:
+            data["reply_to"] = self._to_address_dict(reply_to)
+        if headers:
+            data["headers"] = headers
+        if attachments:
+            data["attachments"] = attachments
+
+        response = self._request("POST", "/v2/emails", data)
+        return SendEmailResponse.from_dict(response)
+
+    def batch(
+        self,
+        emails: List[Dict[str, Any]],
+    ) -> BatchEmailResponse:
+        """
+        Send multiple emails in a single request.
+
+        Args:
+            emails: List of email objects (same format as send())
+
+        Returns:
+            BatchEmailResponse with results for each email
+        """
+        if not emails:
+            raise ToSendError(
+                "Emails list is required and cannot be empty",
+                422,
+                "validation_error",
+                {"emails": {"required": "At least one email is required"}},
+            )
+
+        # Process each email to ensure proper format
+        processed_emails = []
+        for email in emails:
+            processed = {}
+            if "from_address" in email:
+                processed["from"] = self._to_address_dict(email["from_address"])
+            elif "from" in email:
+                processed["from"] = self._to_address_dict(email["from"])
+
+            if "to" in email:
+                processed["to"] = [self._to_address_dict(addr) for addr in email["to"]]
+
+            for key in ("subject", "html", "text", "headers", "attachments"):
+                if key in email:
+                    processed[key] = email[key]
+
+            for key in ("cc", "bcc"):
+                if key in email and email[key]:
+                    processed[key] = [self._to_address_dict(addr) for addr in email[key]]
+
+            if "reply_to" in email and email["reply_to"]:
+                processed["reply_to"] = self._to_address_dict(email["reply_to"])
+
+            processed_emails.append(processed)
+
+        response = self._request("POST", "/v2/emails/batch", {"emails": processed_emails})
+        return BatchEmailResponse.from_dict(response)
+
+    def get_account_info(self) -> AccountInfo:
+        """
+        Get account information and domains.
+
+        Returns:
+            AccountInfo with account details and domains
+        """
+        response = self._request("GET", "/v2/info")
+        return AccountInfo.from_dict(response)
+
+    def _to_address_dict(self, address: Union[Address, Dict[str, str]]) -> Dict[str, str]:
+        """Convert address to dict format."""
+        if isinstance(address, Address):
+            return address.to_dict()
+        return address
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make an HTTP request to the API."""
+        url = f"{self.base_url}{path}"
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+        body = json.dumps(data).encode("utf-8") if data else None
+
+        request = Request(url, data=body, headers=headers, method=method)
+
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                response_body = response.read().decode("utf-8")
+                if response_body:
+                    return json.loads(response_body)
+                return {}
+        except HTTPError as e:
+            try:
+                error_body = e.read().decode("utf-8")
+                error_data = json.loads(error_body)
+                raise ToSendError.from_response(error_data, e.code)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                raise ToSendError(str(e), e.code)
+        except URLError as e:
+            raise ToSendError(f"Request failed: {e.reason}")
+        except Exception as e:
+            raise ToSendError(f"Request failed: {str(e)}")

tosend/exceptions.py

@@ -0,0 +1,47 @@
+"""Exceptions for ToSend SDK."""
+
+from typing import Optional, Dict, Any
+
+
+class ToSendError(Exception):
+    """ToSend API error."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 0,
+        error_type: str = "unknown_error",
+        errors: Optional[Dict[str, Dict[str, str]]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type
+        self.errors = errors or {}
+
+    @classmethod
+    def from_response(cls, data: Dict[str, Any], status_code: int) -> "ToSendError":
+        return cls(
+            message=data.get("message", "Unknown error"),
+            status_code=status_code,
+            error_type=data.get("error_type", "unknown_error"),
+            errors=data.get("errors"),
+        )
+
+    @property
+    def is_validation_error(self) -> bool:
+        return self.error_type == "validation_error" or self.status_code == 422
+
+    @property
+    def is_authentication_error(self) -> bool:
+        return (
+            self.error_type in ("unauthorized", "forbidden")
+            or self.status_code in (401, 403)
+        )
+
+    @property
+    def is_rate_limit_error(self) -> bool:
+        return self.error_type == "rate_limit_exceeded" or self.status_code == 429
+
+    def __str__(self) -> str:
+        return f"ToSendError: {self.message} (status: {self.status_code}, type: {self.error_type})"

tosend/types.py

@@ -0,0 +1,154 @@
+"""Type definitions for ToSend SDK."""
+
+from dataclasses import dataclass, field, asdict
+from typing import Optional, List, Dict, Any
+
+
+@dataclass
+class Address:
+    """Email address with optional name."""
+    email: str
+    name: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {"email": self.email}
+        if self.name:
+            d["name"] = self.name
+        return d
+
+
+@dataclass
+class Attachment:
+    """Email attachment."""
+    type: str  # MIME type
+    name: str  # Filename
+    content: str  # Base64 encoded content
+
+    def to_dict(self) -> Dict[str, str]:
+        return {"type": self.type, "name": self.name, "content": self.content}
+
+
+@dataclass
+class SendEmailRequest:
+    """Request to send a single email."""
+    from_address: Address
+    to: List[Address]
+    subject: str
+    html: Optional[str] = None
+    text: Optional[str] = None
+    cc: Optional[List[Address]] = None
+    bcc: Optional[List[Address]] = None
+    reply_to: Optional[Address] = None
+    headers: Optional[Dict[str, str]] = None
+    attachments: Optional[List[Attachment]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "from": self.from_address.to_dict(),
+            "to": [addr.to_dict() for addr in self.to],
+            "subject": self.subject,
+        }
+        if self.html:
+            d["html"] = self.html
+        if self.text:
+            d["text"] = self.text
+        if self.cc:
+            d["cc"] = [addr.to_dict() for addr in self.cc]
+        if self.bcc:
+            d["bcc"] = [addr.to_dict() for addr in self.bcc]
+        if self.reply_to:
+            d["reply_to"] = self.reply_to.to_dict()
+        if self.headers:
+            d["headers"] = self.headers
+        if self.attachments:
+            d["attachments"] = [att.to_dict() for att in self.attachments]
+        return d
+
+
+@dataclass
+class SendEmailResponse:
+    """Response from sending an email."""
+    message_id: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SendEmailResponse":
+        return cls(message_id=data.get("message_id", ""))
+
+
+@dataclass
+class BatchEmailResult:
+    """Result of a single email in a batch."""
+    status: str
+    message_id: Optional[str] = None
+    message: Optional[str] = None
+    errors: Optional[Dict[str, Dict[str, str]]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BatchEmailResult":
+        return cls(
+            status=data.get("status", ""),
+            message_id=data.get("message_id"),
+            message=data.get("message"),
+            errors=data.get("errors"),
+        )
+
+
+@dataclass
+class BatchEmailResponse:
+    """Response from sending batch emails."""
+    results: List[BatchEmailResult]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BatchEmailResponse":
+        results = [BatchEmailResult.from_dict(r) for r in data.get("results", [])]
+        return cls(results=results)
+
+
+@dataclass
+class Domain:
+    """Verified domain."""
+    domain_name: str
+    verification_status: str
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Domain":
+        return cls(
+            domain_name=data.get("domain_name", ""),
+            verification_status=data.get("verification_status", ""),
+            created_at=data.get("created_at", ""),
+        )
+
+
+@dataclass
+class Account:
+    """Account information."""
+    title: str
+    plan_type: str
+    status: str
+    emails_usage_this_month: int
+    emails_sent_last_24hrs: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Account":
+        return cls(
+            title=data.get("title", ""),
+            plan_type=data.get("plan_type", ""),
+            status=data.get("status", ""),
+            emails_usage_this_month=data.get("emails_usage_this_month", 0),
+            emails_sent_last_24hrs=data.get("emails_sent_last_24hrs", 0),
+        )
+
+
+@dataclass
+class AccountInfo:
+    """Account info response."""
+    account: Account
+    domains: List[Domain]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AccountInfo":
+        return cls(
+            account=Account.from_dict(data.get("account", {})),
+            domains=[Domain.from_dict(d) for d in data.get("domains", [])],
+        )

tosend-1.0.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: tosend
+Version: 1.0.0
+Summary: Official Python SDK for the ToSend email API
+Author-email: ToSend <support@tosend.com>
+License: MIT
+Project-URL: Homepage, https://tosend.com
+Project-URL: Documentation, https://tosend.com/docs
+Project-URL: Repository, https://github.com/tosend/tosend-python
+Project-URL: Issues, https://github.com/tosend/tosend-python/issues
+Keywords: email,api,tosend,transactional,mail
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ToSend Python SDK
+
+Official Python SDK for the [ToSend](https://tosend.com) email API.
+
+[![PyPI version](https://badge.fury.io/py/tosend.svg)](https://badge.fury.io/py/tosend)
+[![Python Versions](https://img.shields.io/pypi/pyversions/tosend.svg)](https://pypi.org/project/tosend/)
+
+## Installation
+
+```bash
+pip install tosend
+```
+
+## Examples
+
+See the [examples](examples) folder for complete working examples:
+
+- [Send Email](examples/send_email.py) - Send a single email
+- [Batch Send](examples/batch_send.py) - Send multiple emails in one request
+- [Account Info](examples/account_info.py) - Get account information and domains
+
+```bash
+export TOSEND_API_KEY=tsend_your_api_key
+python examples/send_email.py
+```
+
+## Quick Start
+
+```python
+from tosend import ToSend
+
+client = ToSend("tsend_your_api_key")
+
+response = client.send(
+    from_address={"email": "hello@yourdomain.com", "name": "Your App"},
+    to=[{"email": "user@example.com"}],
+    subject="Welcome!",
+    html="<h1>Hello!</h1><p>Thanks for signing up.</p>",
+)
+
+print(response.message_id)
+```
+
+## Usage
+
+### Send an Email
+
+```python
+response = client.send(
+    from_address={"email": "hello@yourdomain.com", "name": "Your App"},
+    to=[
+        {"email": "user@example.com"},
+        {"email": "another@example.com", "name": "John Doe"},
+    ],
+    subject="Hello!",
+    html="<h1>Welcome</h1>",
+    text="Welcome",  # optional
+)
+```
+
+### With CC, BCC, and Reply-To
+
+```python
+response = client.send(
+    from_address={"email": "hello@yourdomain.com"},
+    to=[{"email": "user@example.com"}],
+    cc=[{"email": "cc@example.com"}],
+    bcc=[{"email": "bcc@example.com"}],
+    reply_to={"email": "support@yourdomain.com", "name": "Support"},
+    subject="Hello",
+    html="<p>Hello World</p>",
+)
+```
+
+### With Attachments
+
+```python
+import base64
+
+with open("invoice.pdf", "rb") as f:
+    content = base64.b64encode(f.read()).decode()
+
+response = client.send(
+    from_address={"email": "hello@yourdomain.com"},
+    to=[{"email": "user@example.com"}],
+    subject="Your Invoice",
+    html="<p>Please find your invoice attached.</p>",
+    attachments=[
+        {
+            "type": "application/pdf",
+            "name": "invoice.pdf",
+            "content": content,
+        }
+    ],
+)
+```
+
+### Batch Sending
+
+Send multiple emails in a single request:
+
+```python
+response = client.batch([
+    {
+        "from": {"email": "hello@yourdomain.com"},
+        "to": [{"email": "user1@example.com"}],
+        "subject": "Hello User 1",
+        "html": "<p>Welcome!</p>",
+    },
+    {
+        "from": {"email": "hello@yourdomain.com"},
+        "to": [{"email": "user2@example.com"}],
+        "subject": "Hello User 2",
+        "html": "<p>Welcome!</p>",
+    },
+])
+
+for result in response.results:
+    if result.status == "success":
+        print(f"Sent: {result.message_id}")
+    else:
+        print(f"Failed: {result.message}")
+```
+
+### Get Account Info
+
+```python
+info = client.get_account_info()
+
+print(info.account.title)
+print(info.account.emails_usage_this_month)
+print(info.account.emails_sent_last_24hrs)
+
+for domain in info.domains:
+    print(f"{domain.domain_name}: {domain.verification_status}")
+```
+
+## Configuration
+
+### With Options
+
+```python
+client = ToSend(
+    api_key="tsend_your_api_key",
+    base_url="https://api.tosend.com",  # optional
+    timeout=60,  # optional, in seconds
+)
+```
+
+## Error Handling
+
+```python
+from tosend import ToSend, ToSendError
+
+client = ToSend("tsend_your_api_key")
+
+try:
+    response = client.send(
+        from_address={"email": "hello@yourdomain.com"},
+        to=[{"email": "user@example.com"}],
+        subject="Hello",
+        html="<p>Hello</p>",
+    )
+except ToSendError as e:
+    print(f"Error: {e.message}")
+    print(f"Status: {e.status_code}")
+    print(f"Type: {e.error_type}")
+    print(f"Details: {e.errors}")
+
+    if e.is_validation_error:
+        # Handle validation error (422)
+        pass
+
+    if e.is_authentication_error:
+        # Handle auth error (401/403)
+        pass
+
+    if e.is_rate_limit_error:
+        # Handle rate limit (429)
+        pass
+```
+
+## Type Hints
+
+The SDK includes full type hints. You can also use the provided dataclasses:
+
+```python
+from tosend import ToSend, Address, SendEmailRequest
+
+client = ToSend("tsend_your_api_key")
+
+# Using Address dataclass
+from_addr = Address(email="hello@yourdomain.com", name="Your App")
+to_addr = Address(email="user@example.com")
+
+response = client.send(
+    from_address=from_addr,
+    to=[to_addr],
+    subject="Hello!",
+    html="<h1>Welcome!</h1>",
+)
+```
+
+## Requirements
+
+- Python 3.8 or higher
+- No external dependencies (uses only standard library)
+
+## License
+
+MIT

tosend-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tosend/__init__.py,sha256=LE5rGqMteWuW8lPEozNirvAkpAzqbEyyKIN6wHtn304,572
+tosend/client.py,sha256=wWtKUOI95G1vFhqZ0awaVeCBbl9gQul7spCer2xbUQI,6586
+tosend/exceptions.py,sha256=9WB6V2Ny-hR6qFRiFXfzTuFeeGmSHD0jrzTkOvYw9sk,1441
+tosend/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tosend/types.py,sha256=UXe6npV9CZIpkFNU1tAb2zJ7DrIqdmODAObbWycesS4,4273
+tosend-1.0.0.dist-info/licenses/LICENSE,sha256=KSVUBGoT4K7d_-vdmjkix5VDIv5vJPbnrvIAdhV0rZU,1063
+tosend-1.0.0.dist-info/METADATA,sha256=wi8rdRXN1lRJaq80pebEo1qX5WpCBrpUGHF9-OtbPCU,5775
+tosend-1.0.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+tosend-1.0.0.dist-info/top_level.txt,sha256=tRqARDnjKno214JLFYAmchYTQPhd1hMgbgP7wbNqw9A,7
+tosend-1.0.0.dist-info/RECORD,,

tosend-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tosend-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ToSend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tosend-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tosend