Integration Architecture and Data Flow
Core Integration Patterns
Amazon SES integrates with Odoo 18 through two primary architectural patterns: SMTP relay and API direct integration. The SMTP method leverages Odoo’s native outgoing mail server configuration, acting as a straightforward relay for all outgoing messages. This approach requires minimal code modification but offers limited control over advanced SES features like templates and analytics. The API integration method replaces Odoo’s default mail delivery mechanism with direct Python calls to the SES API, enabling full utilization of SES capabilities including template management, configuration sets, and detailed delivery metrics.
The API integration architecture introduces a custom Odoo mail delivery module that intercepts outgoing messages before they enter the standard mail queue. This module transforms Odoo’s internal message format into SES API requests, handling attachments, HTML content, and recipient management. The integration maintains Odoo’s existing email composition interface while redirecting delivery through AWS. This approach preserves user experience while leveraging SES’s superior infrastructure for actual message transmission.
Data Flow Sequence
Outgoing email flow begins when a user sends a message through any Odoo module—sales quotations from CRM, invoice notifications from accounting, or marketing campaigns from mass mailing. The Odoo mail module processes the message, applies any template formatting, and routes it to the outgoing mail queue. Our custom SES integration intercepts messages at this point, converting them to SES-compatible format with proper headers, MIME encoding, and attachment processing.
For incoming bounce and complaint processing, Amazon SES sends notifications to an SNS topic configured in your AWS account. The Odoo integration includes an SNS webhook endpoint that receives these notifications, processes them, and updates corresponding Odoo records. Bounce handling automatically disables email sending to invalid addresses, while complaint processing handles abuse reports to protect your sending reputation. This bidirectional data flow ensures comprehensive email management within your Odoo environment.
System Components Integration
The complete architecture incorporates multiple AWS services beyond SES. IAM roles manage secure access between Odoo and AWS, while SNS handles event notifications for bounces and complaints. CloudWatch provides monitoring and logging for troubleshooting delivery issues. Within Odoo, the integration spans core mail modules, the CRM for lead communication tracking, and marketing automation for campaign performance analytics. This multi-service approach creates a robust email ecosystem rather than a simple mail relay replacement.
Step-by-Step Configuration
AWS Infrastructure Setup
Begin with AWS SES service verification in your target region. Navigate to the SES console and verify your domain using DNS TXT records for authentication. This domain verification establishes your authority to send emails from your business domain through SES. Complete the verification process before proceeding to ensure all test emails originate from a validated source. For production systems, request SES production access by submitting a use case description and initial volume projections to AWS.
Configure IAM policies with precise permissions for Odoo SES access. Create a dedicated IAM user with programmatic access keys rather than using root credentials. Apply the AmazonSESFullAccess managed policy initially, then refine permissions for production security. The minimal policy should include ses:SendRawEmail, ses:SendEmail, and ses:GetSendStatistics actions restricted to your verified domains. Implement strict resource constraints to prevent credential misuse if keys become exposed.
Create SNS topics for bounce and complaint notifications. Configure these topics to receive feedback events from SES and connect them to Lambda functions or direct HTTP endpoints. The SNS configuration requires proper access policies that permit SES service to publish messages. Test the notification flow using the SNS console before integrating with Odoo to verify the entire AWS-side infrastructure operates correctly.
Odoo Outgoing Mail Configuration
Install the base Odoo mail modules if not already active, including ‘mass_mailing’ and ‘mail’ core applications. Navigate to Settings > Technical > Outgoing Mail Servers and create a new SMTP server record. Enter your SES SMTP endpoint specific to your AWS region—for example, email-smtp.us-east-1.amazonaws.com for the US East region. Use TLS encryption on port 587 with your IAM user SMTP credentials, which differ from your console access keys.
Configure the outgoing mail server parameters with your verified SES domain as the default FROM address. Set the server priority to ensure it handles all outgoing mail rather than Odoo’s default sendmail configuration. Test the connection using the built-in test feature with a validated recipient address. This initial SMTP configuration provides basic sending capability while we develop the full API integration for advanced features.
Custom SES Module Development
Create a new Odoo module with Python dependencies for boto3 and requests. Implement a custom mail delivery method that inherits from IrMailServer and overrides the send_email method. This custom method intercepts outgoing messages and redirects them through the SES API instead of standard SMTP. The module requires proper dependency declaration in the manifest.py file and model registration in the init.py structure.
Develop the core sending function using boto3 SES client initialization with AWS credentials stored in Odoo parameters. The function constructs SES SendRawEmail requests from Odoo message objects, handling encoding for HTML content, text alternatives, and file attachments. Implement proper error handling for SES API responses, converting AWS exceptions to Odoo-compatible error messages for user notification.
Create configuration settings within Odoo’s general settings interface for AWS access key management, default configuration sets, and sending rate limits. Store sensitive credentials using Odoo’s parameter encryption rather than plaintext in the database. This configuration interface allows administrators to manage SES settings without code modification after deployment.
Advanced Feature Implementation
Implement SES template support for Odoo’s mass mailing campaigns. Create a synchronization function that maps Odoo email templates to SES templates, maintaining version control when templates update. Develop template rendering logic that merges Odoo record data with SES template variables, handling the different syntax conventions between the systems.
Configure custom configuration sets for different email types—transactional versus marketing messages. Apply appropriate configuration sets based on the Odoo module originating the email, enabling detailed analytics tracking per email category. Implement open and click tracking through SES configuration sets, with webhook endpoints that capture these events and update Odoo mailing statistics.
Set up bounce processing with automatic recipient list management. Create methods that parse SNS bounce notifications and disable email sending to problematic addresses within Odoo. Implement complaint handling that immediately suspends sending to recipients who report spam, protecting your sender reputation. Connect these processing functions to your SNS webhook endpoint with proper signature verification for security.
Data Mapping and Transformation
Email Message Structure Conversion
Odoo’s internal message representation requires significant transformation to match SES API requirements. The Odoo mail.message object contains HTML body content, subject headers, and recipient lists in a single structure, while SES expects separate parameters for each component. Our transformation logic extracts these elements and constructs a MIME-compliant email message with proper content-type headers for multipart alternative messages.
Address formatting presents a particular challenge in the mapping process. Odoo supports display names with email addresses in “Name email@domain.com” format, while SES requires RFC-complient address encoding. Our transformation function parses Odoo’s address format, extracts the email component for SES delivery, and preserves the display name in the MIME headers. This ensures recipient inboxes show familiar names rather than raw email addresses.
Attachment handling requires MIME encoding conversion. Odoo stores attachments as binary fields in the database with associated filenames and MIME types. The transformation process encodes these binaries as base64 MIME parts with appropriate content-disposition headers. For large attachments, we implement streaming encoding to prevent memory overload during message construction for bulk email operations.
Template Variable Mapping
SES template system uses a different variable syntax than Odoo’s QWeb templates. Odoo’s ${object.field_name} format must transform to SES’s {{variableName}} convention. Our mapping function identifies Odoo template variables and converts them to SES-compatible placeholders while maintaining the data context from Odoo records. This enables seamless template migration between the systems without manual variable rewriting.
We handle complex data types like dates, currencies, and related records through preprocessing before template rendering. Odoo’s ORM returns Python objects for related fields, while SES templates expect simple strings or numbers. Our transformation logic flattens these relationships into simple values, formats dates according to locale settings, and converts currencies to formatted strings with appropriate symbols.
Multi-language template support requires maintaining parallel template versions in Odoo and SES. We implement a synchronization mechanism that tracks template changes in Odoo and updates corresponding SES templates in all configured languages. This ensures marketing campaigns maintain consistent design and variable structure across language versions while leveraging SES’s template rendering performance.
Bounce Notification Processing
Amazon SNS delivers bounce notifications in JSON format with complex nested structures. Our mapping logic extracts the critical information—recipient email address, bounce type, and timestamp—then converts this to Odoo’s bounce tracking model. We categorize bounces as transient or permanent based on the SES bounce subtype, applying different handling rules for each category.
The transformation process updates multiple Odoo models from a single bounce notification. For mass mailing recipients, we update the mailing.contact bounce counter and disable future sending if thresholds exceed limits. For individual messages, we log the bounce in the message tracking history and trigger alert notifications to system administrators for investigation of delivery problems.
Complaint notifications require immediate action to protect sender reputation. Our mapping logic identifies complaint events and applies more aggressive suppression than standard bounces. We create blacklist entries that prevent any future communication with complaining recipients across all Odoo modules, not just the originating campaign or message type.
Error Handling and Resilience
Common SES Integration Errors
SES quota exceptions occur when your sending limits exceed allocated throughput. Odoo’s default behavior retries failed messages, creating sending loops that exacerbate quota problems. Our error handling implements exponential backoff with jitter, gradually increasing retry delays while distributing load across the rate limit window. We track sending volumes against known SES limits and preemptively queue messages when approaching thresholds.
Authentication failures typically stem from expired IAM credentials or incorrect region configuration. Our error detection differentiates between temporary token failures and permanent configuration issues. Temporary authentication problems trigger credential refresh procedures, while configuration errors generate administrator alerts with specific remediation guidance. We implement credential validation during system startup and at regular intervals to catch problems before they impact email delivery.
Message formatting errors arise from invalid email addresses, encoding problems, or oversized attachments. Our preprocessing validates recipient addresses against RFC standards before attempting SES delivery, rejecting malformed addresses with detailed error messages. We detect character encoding conflicts and normalize content to UTF-8, preventing delivery failures from special characters in subject lines or body content.
System Resilience Strategies
Implement circuit breaker patterns for SES API interactions. When error rates exceed configured thresholds, the system temporarily fails fast rather than attempting doomed requests. This prevents cascading failures during AWS service disruptions while conserving system resources for recovery. The circuit breaker monitors error patterns and automatically restores normal operation when the underlying issues resolve.
Design idempotent retry mechanisms for duplicate-prone operations. SES may experience temporary failures that succeed on retry, but Odoo might interpret these as separate send attempts. Our implementation tracks message IDs across retry attempts, ensuring duplicate deliveries never occur even with multiple delivery attempts. We maintain retry counters with exponential backoff to prevent endless retry loops for permanently undeliverable messages.
Create fallback delivery mechanisms for critical communications. When SES experiences prolonged outages, the system can reroute high-priority messages through alternative channels including Odoo’s native SMTP or third-party services. We implement priority-based routing that identifies must-send messages like password resets and order confirmations, ensuring business continuity during integration failures.
Debugging and Monitoring
Develop comprehensive logging with correlation IDs that track messages across Odoo and AWS systems. Each outgoing message receives a unique identifier that persists through Odoo processing, SES API calls, and SNS notifications. This enables end-to-end tracing when investigating delivery problems or performance issues. We structure logs for easy integration with Odoo’s native logging system and external monitoring tools.
Implement real-time dashboards for delivery metrics and error rates. Create Odoo views that display current SES sending statistics, bounce rates, and complaint volumes alongside business metrics like campaign performance. This integrated monitoring helps administrators correlate technical issues with business impact, prioritizing fixes based on actual operational disruption rather than just technical error counts.
Establish alert escalation procedures for different error categories. Configuration errors trigger immediate administrator notifications, while temporary service disruptions generate lower-priority alerts. We define clear response procedures for each error type, including automated remediation for common problems and manual intervention checklists for complex issues.
Testing and Validation
Pre-Deployment Test Scenarios
Develop comprehensive test cases that cover all Odoo modules generating email. Create test scenarios for sales order confirmations, invoice notifications, CRM follow-ups, and marketing campaigns. Each test verifies not just successful delivery but also proper content rendering, attachment handling, and recipient management. Execute tests in a staging environment that mirrors production configuration but uses SES sandbox mode to prevent accidental external communication.
Validate bounce and complaint processing with simulated SNS notifications. Use the SES mailbox simulator to generate controlled bounces and complaints without affecting your sending reputation. Verify that Odoo properly processes these notifications and updates recipient status accordingly. Test both hard bounces (invalid addresses) and soft bounces (mailbox full) to ensure different handling for each scenario.
Perform load testing to verify integration stability under production volumes. Generate synthetic email traffic that matches your expected production patterns, including bulk marketing campaigns and transactional message spikes. Monitor system resources during load tests to identify potential bottlenecks in message processing, API rate limiting, or database performance under high email volumes.
Integration Validation Checklist
Verify domain authentication and DKIM signing for all sending domains. Use email header analysis tools to confirm proper alignment between your domain and SES infrastructure. Validate that SPF, DKIM, and DMARC records propagate correctly in DNS and that receiving email systems authenticate messages properly. Test delivery to major email providers including Gmail, Outlook, and corporate Exchange systems to identify any provider-specific filtering issues.
Confirm proper tracking and analytics integration. Send test emails with open and click tracking enabled, then verify that these events capture in Odoo’s marketing statistics. Check that bounce processing updates recipient lists and that complaint handling creates appropriate suppression records. Validate that all tracking links maintain proper session context for Odoo’s website analytics.
Audit security implementation including credential storage, API access logging, and webhook authentication. Verify that IAM policies enforce least privilege access and that sensitive credentials never log in clear text. Test webhook endpoint security by sending forged notifications to ensure only properly signed SNS messages process. Validate that all API communications use TLS encryption and certificate verification.
Production Readiness Verification
Execute a phased rollout that migrates specific email types incrementally. Begin with internal notifications and non-critical communications before progressing to customer-facing messages. Monitor deliverability metrics at each stage, comparing performance against your previous email solution. Establish clear rollback procedures if critical issues emerge during initial production use.
Implement canary testing that sends duplicate messages through both SES and your legacy email system during transition periods. Compare delivery times, inbox placement rates, and engagement metrics between the two systems. Use this comparative data to validate SES performance and identify any configuration optimizations needed before full migration.
Create ongoing monitoring checks that validate integration health. Schedule regular test messages that verify end-to-end delivery and bounce processing. Set up automated alerts for abnormal bounce rates, sending volume changes, or credential expiration. Establish regular review procedures for SES sending statistics and Odoo email analytics to identify emerging issues before they impact business operations.
Security Considerations
Authentication and Access Control
Implement strict IAM role policies that follow the principle of least privilege. Create dedicated IAM users for Odoo integration with permissions limited to specific SES actions and resources. Restrict access by verified domain to prevent accidental or malicious sending from unauthorized domains. Use IAM conditions to constrain API calls to specific source IP addresses when Odoo operates from fixed infrastructure.
Secure AWS credential storage within Odoo’s parameter system with encryption. Never embed credentials in code or configuration files in plaintext. Implement credential rotation procedures that automatically update Odoo when IAM keys approach expiration. For enhanced security, consider using IAM roles with instance profiles when Odoo runs on EC2 infrastructure, eliminating static credential management.
Protect SNS webhook endpoints with signature verification. Amazon SNS signs all notifications with X.509 certificates, and your endpoint must validate these signatures before processing bounce or complaint notifications. Implement proper certificate caching and validation logic to prevent forged notifications that might corrupt your recipient database or tracking statistics.
Data Protection and Compliance
Encrypt all email content in transit using TLS 1.2 or higher for both API communications and SMTP connections. Verify certificate validity for all AWS endpoints to prevent man-in-the-middle attacks. For highly sensitive communications, consider implementing additional message-level encryption that protects content beyond transport security.
Manage personal data in compliance with GDPR, CCPA, and other privacy regulations. Implement proper data retention policies for email logs and tracking information. Provide mechanisms for data subject requests that export or delete personal information from both Odoo records and SES templates. Document data flows between systems for compliance auditing and privacy impact assessments.
Secure Odoo’s email composition interfaces against injection attacks. Validate all user inputs that might affect email content, headers, or recipients. Implement strict anti-spam measures that prevent compromised user accounts from abusing your SES sending capability. Monitor sending patterns for anomalies that might indicate security breaches or credential theft.
Infrastructure Security
Harden the Odoo server environment that hosts the SES integration. Apply security patches regularly, configure firewalls to limit access to necessary ports, and implement intrusion detection monitoring. Isperate the mail processing components from public-facing Odoo web interfaces to reduce attack surface.
Monitor AWS CloudTrail logs for suspicious SES API activity. Set up alerts for unusual sending patterns, configuration changes, or authentication failures that might indicate security incidents. Integrate these alerts with your existing security monitoring infrastructure for coordinated incident response.
Establish security incident response procedures specific to email compromise scenarios. Define escalation paths, communication plans, and technical containment measures for situations where your SES capability becomes abused for spam or phishing. Practice these procedures through tabletop exercises to ensure preparedness for real security events.
Performance Optimization
SES API Efficiency
Implement message batching for high-volume sending scenarios. Instead of individual API calls for each message, group multiple messages into single batch requests where appropriate. Balance batch size against processing overhead and error handling complexity. For truly massive volumes, consider using SES’s sending pipeline features with dedicated IP addresses for predictable performance.
Optimize API call patterns to minimize throttling and latency. Distribute sending load evenly across time rather than in bursts that trigger rate limiting. Implement connection pooling for HTTP requests to avoid TCP handshake overhead for each API call. Cache frequently accessed SES resources like template definitions and configuration sets to reduce redundant API calls.
Use SES’s sending statistics and CloudWatch metrics to identify performance bottlenecks. Monitor send rates, bounce percentages, and complaint rates for early detection of deliverability issues. Set up automated adjustments to sending patterns based on these metrics, reducing volume when engagement metrics indicate potential delivery problems.
Odoo Processing Optimization
Tune Odoo’s mail queue processing for efficient handling of large email volumes. Adjust the mail queue batch size and worker processes based on your server resources and typical email load. Implement priority queuing that processes transactional messages before bulk marketing communications to ensure time-sensitive messages deliver promptly.
Optimize database performance for email-related operations. Add appropriate indexes to mail.message and related tables to speed up message retrieval and status updates. Implement periodic cleanup of old email records that no longer require immediate access, archiving historical data to separate storage for compliance purposes.
Cache recipient validation results to avoid repeated address formatting and validation checks. For mass mailing operations, precompute recipient lists and validate addresses before beginning the sending process. This prevents mid-campaign failures from invalid addresses and improves overall sending throughput.
System-Wide Tuning
Monitor server resources during peak sending periods to identify hardware constraints. Scale Odoo instances horizontally for email-intensive operations, separating web frontends from backend mail processing. Consider dedicated queue processors for email operations when marketing campaigns generate temporary volume spikes.
Implement content delivery optimization for images and tracking links in email campaigns. Use CDN services for hosted images to reduce load on your Odoo servers and improve email rendering performance. Optimize tracking link redirects to minimize latency in click capture and user redirection.
Establish performance baselines and continuous monitoring to detect degradation over time. Track key metrics including messages per second, API latency, and end-to-end delivery time. Set up automated alerts when performance deviates from established baselines, enabling proactive optimization before users experience impact.