Merge pull request #2 from Devotel/feature/email-resource-implementation

feat(email): implement Email resource

Author: parman-devotel

.gitignore

@@ -190,3 +190,5 @@ Thumbs.db
 api_keys.txt
 secrets.json
 .api_key
+
+setup-dev-env.ps1

examples/email_example.py

@@ -1,6 +1,6 @@
 import os
 
-from devo_global_comms_python import DevoException
+from devo_global_comms_python import DevoCommsClient, DevoException
 
 
 def main():
@@ -9,42 +9,72 @@ def main():
         print("❌ Please set DEVO_API_KEY environment variable")
         return
 
+    client = DevoCommsClient(api_key=api_key)
     print("✅ Devo Email Client initialized successfully")
     print("=" * 60)
 
     try:
-        # Example 1: Send a simple email
+        # Example: Send an email using the Email API
         print("📧 EMAIL SEND EXAMPLE")
         print("-" * 30)
 
         print("📤 Sending email...")
-        print("⚠️  This is a placeholder implementation.")
-        print("   Update this example when Email API is implemented.")
-
-        # Placeholder email send - update when implementing Email resource
-        print("   ```python")
-        print("   email_response = client.email.send(")
-        print("       to='recipient@example.com',")
-        print("       subject='Test Email from Devo SDK',")
-        print("       body='This is a test email.',")
-        print("       html_body='<h1>Test</h1><p>This is a test email.</p>',")
-        print("       from_email='sender@yourdomain.com'")
-        print("   )")
-        print("   print(f'Email sent! ID: {email_response.id}')")
-        print("   ```")
+        email_response = client.email.send_email(
+            subject="Test Email from Devo SDK",
+            body="This is a test email sent using the Devo Global Communications Python SDK.",
+            sender="sender@example.com",
+            recipient="recipient@example.com",
+        )
+
+        print("✅ Email sent successfully!")
+        print(f"   📧 Message ID: {email_response.message_id}")
+        print(f"   📦 Bulk Email ID: {email_response.bulk_email_id}")
+        print(f"   📝 Subject: {email_response.subject}")
+        print(f"   📊 Status: {email_response.status}")
+        print(f"   💬 Message: {email_response.message}")
+        print(f"   🕐 Timestamp: {email_response.timestamp}")
+        print(f"   ✅ Success: {email_response.success}")
+
+        # Example with different content
+        print("\n📧 SENDING EMAIL WITH RICH CONTENT")
+        print("-" * 40)
+
+        rich_email_response = client.email.send_email(
+            subject="🎉 Welcome to Devo Communications!",
+            body=(
+                "Dear valued customer,\n\n"
+                "Welcome to our service! We're excited to have you on board.\n\n"
+                "Best regards,\nThe Devo Team"
+            ),
+            sender="welcome@yourcompany.com",
+            recipient="newcustomer@example.com",
+        )
+
+        print("✅ Rich content email sent!")
+        print(f"   📧 Message ID: {rich_email_response.message_id}")
+        print(f"   📊 Status: {rich_email_response.status}")
+        print(f"   ✅ Success: {rich_email_response.success}")
 
     except DevoException as e:
         print(f"❌ Email operation failed: {e}")
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
 
     print("\n" + "=" * 60)
     print("📊 EMAIL EXAMPLE SUMMARY")
     print("-" * 30)
-    print("⚠️  This is a placeholder example for Email functionality.")
-    print("💡 To implement:")
-    print("   1. Define Email API endpoints and specifications")
-    print("   2. Create Email Pydantic models")
-    print("   3. Implement EmailResource class")
-    print("   4. Update this example with real functionality")
+    print("✅ Email API implementation complete!")
+    print("📤 Successfully demonstrated:")
+    print("   • Basic email sending")
+    print("   • Email with rich content and emojis")
+    print("   • Response parsing and status checking")
+    print("   • Error handling")
+    print("\n💡 Features available:")
+    print("   • Subject and body content")
+    print("   • Sender and recipient validation")
+    print("   • Message tracking with unique IDs")
+    print("   • Status monitoring")
+    print("   • Timestamp tracking")
 
 
 if __name__ == "__main__":

src/devo_global_comms_python/models/email.py

@@ -4,15 +4,44 @@
 from pydantic import BaseModel, Field
 
 
+# Request Models
+class EmailSendRequest(BaseModel):
+    """
+    Request model for email send API.
+
+    Used for POST /user-api/email/send
+    """
+
+    subject: str = Field(..., description="Email subject")
+    body: str = Field(..., description="Email body content")
+    sender: str = Field(..., description="Sender email address")
+    recipient: str = Field(..., description="Recipient email address")
+
+
+# Response Models
+class EmailSendResponse(BaseModel):
+    """
+    Response model for email send API.
+
+    Returned from POST /user-api/email/send
+    """
+
+    success: bool = Field(..., description="Whether the email was sent successfully")
+    message_id: str = Field(..., description="Unique message identifier")
+    bulk_email_id: str = Field(..., description="Bulk email identifier")
+    subject: str = Field(..., description="Email subject")
+    status: str = Field(..., description="Message status")
+    message: str = Field(..., description="Status message")
+    timestamp: datetime = Field(..., description="Timestamp of the response")
+
+
 class EmailAttachment(BaseModel):
     """Email attachment model."""
 
     filename: str = Field(..., description="Attachment filename")
     content_type: str = Field(..., description="MIME content type")
     size: int = Field(..., description="File size in bytes")
-    content_id: Optional[str] = Field(
-        None, description="Content ID for inline attachments"
-    )
+    content_id: Optional[str] = Field(None, description="Content ID for inline attachments")
 
 
 class EmailMessage(BaseModel):
@@ -34,27 +63,17 @@ class EmailMessage(BaseModel):
     html_body: Optional[str] = Field(None, description="HTML email body")
     status: str = Field(..., description="Message status")
     direction: str = Field(..., description="Message direction (inbound/outbound)")
-    attachments: Optional[List[EmailAttachment]] = Field(
-        None, description="Email attachments"
-    )
+    attachments: Optional[List[EmailAttachment]] = Field(None, description="Email attachments")
     error_code: Optional[str] = Field(None, description="Error code if failed")
     error_message: Optional[str] = Field(None, description="Error message if failed")
-    date_created: Optional[datetime] = Field(
-        None, description="Message creation timestamp"
-    )
+    date_created: Optional[datetime] = Field(None, description="Message creation timestamp")
     date_sent: Optional[datetime] = Field(None, description="Message sent timestamp")
-    date_delivered: Optional[datetime] = Field(
-        None, description="Message delivered timestamp"
-    )
-    date_opened: Optional[datetime] = Field(
-        None, description="Message opened timestamp"
-    )
+    date_delivered: Optional[datetime] = Field(None, description="Message delivered timestamp")
+    date_opened: Optional[datetime] = Field(None, description="Message opened timestamp")
     date_clicked: Optional[datetime] = Field(None, description="Link clicked timestamp")
-    date_updated: Optional[datetime] = Field(
-        None, description="Message last updated timestamp"
-    )
+    date_updated: Optional[datetime] = Field(None, description="Message last updated timestamp")
     metadata: Optional[Dict[str, Any]] = Field(None, description="Custom metadata")
 
     class Config:
-        allow_population_by_field_name = True
+        validate_by_name = True
         json_encoders = {datetime: lambda v: v.isoformat() if v else None}

src/devo_global_comms_python/resources/email.py

@@ -4,22 +4,63 @@
 from .base import BaseResource
 
 if TYPE_CHECKING:
-    from ..models.email import EmailMessage
+    from ..models.email import EmailMessage, EmailSendResponse
 
 
 class EmailResource(BaseResource):
     """
     Email resource for sending and managing email messages.
 
     Example:
-        >>> message = client.email.send(
-        ...     to="recipient@example.com",
+        >>> response = client.email.send_email(
         ...     subject="Hello, World!",
-        ...     body="This is a test email."
+        ...     body="This is a test email.",
+        ...     sender="sender@example.com",
+        ...     recipient="recipient@example.com"
         ... )
-        >>> print(message.id)
+        >>> print(response.message_id)
     """
 
+    def send_email(
+        self,
+        subject: str,
+        body: str,
+        sender: str,
+        recipient: str,
+    ) -> "EmailSendResponse":
+        """
+        Send an email using the exact API specification.
+
+        Args:
+            subject: Email subject
+            body: Email body content
+            sender: Sender email address
+            recipient: Recipient email address
+
+        Returns:
+            EmailSendResponse: The email send response
+        """
+        # Validate inputs
+        subject = validate_required_string(subject, "subject")
+        body = validate_required_string(body, "body")
+        sender = validate_email(sender)
+        recipient = validate_email(recipient)
+
+        # Prepare request data matching the exact API specification
+        data = {
+            "subject": subject,
+            "body": body,
+            "sender": sender,
+            "recipient": recipient,
+        }
+
+        # Send request to the exact endpoint
+        response = self.client.post("email/send", json=data)
+
+        from ..models.email import EmailSendResponse
+
+        return EmailSendResponse.model_validate(response.json())
+
     def send(
         self,
         to: str,