mailing2fast-fastapi 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. mailing2fast_fastapi-0.1.0/LICENSE +21 -0
  2. mailing2fast_fastapi-0.1.0/MANIFEST.in +8 -0
  3. mailing2fast_fastapi-0.1.0/PKG-INFO +371 -0
  4. mailing2fast_fastapi-0.1.0/README.md +310 -0
  5. mailing2fast_fastapi-0.1.0/docs/env.example +79 -0
  6. mailing2fast_fastapi-0.1.0/examples/async_queue.py +115 -0
  7. mailing2fast_fastapi-0.1.0/examples/basic_usage.py +121 -0
  8. mailing2fast_fastapi-0.1.0/examples/fastapi_integration.py +222 -0
  9. mailing2fast_fastapi-0.1.0/pyproject.toml +73 -0
  10. mailing2fast_fastapi-0.1.0/setup.cfg +4 -0
  11. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/__init__.py +79 -0
  12. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/__version__.py +5 -0
  13. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/dependencies.py +109 -0
  14. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/models.py +154 -0
  15. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/queue.py +265 -0
  16. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/sender.py +344 -0
  17. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/settings.py +241 -0
  18. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi/worker.py +233 -0
  19. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi.egg-info/PKG-INFO +371 -0
  20. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi.egg-info/SOURCES.txt +22 -0
  21. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi.egg-info/dependency_links.txt +1 -0
  22. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi.egg-info/requires.txt +15 -0
  23. mailing2fast_fastapi-0.1.0/src/mailing2fast_fastapi.egg-info/top_level.txt +1 -0
  24. mailing2fast_fastapi-0.1.0/tests/test_sender.py +38 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Angel Daniel Sanchez Castillo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,8 @@
1
+ include README.md
2
+ include LICENSE
3
+ recursive-include docs *.md *.example
4
+ recursive-include examples *.py
5
+ recursive-include src/mailing2fast_fastapi *.py *.html *.txt
6
+ global-exclude __pycache__
7
+ global-exclude *.py[co]
8
+ global-exclude .DS_Store
@@ -0,0 +1,371 @@
1
+ Metadata-Version: 2.4
2
+ Name: mailing2fast-fastapi
3
+ Version: 0.1.0
4
+ Summary: Simple and fast mailing module for FastAPI with async support and Redis queue management
5
+ Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Angel Daniel Sanchez Castillo
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Homepage, https://github.com/AngelDanielSanchezCastillo/mailing2fast-fastapi
29
+ Project-URL: Documentation, https://github.com/AngelDanielSanchezCastillo/mailing2fast-fastapi/tree/main/docs
30
+ Project-URL: Repository, https://github.com/AngelDanielSanchezCastillo/mailing2fast-fastapi
31
+ Project-URL: Issues, https://github.com/AngelDanielSanchezCastillo/mailing2fast-fastapi/issues
32
+ Keywords: fastapi,email,smtp,async,redis,queue,mailing
33
+ Classifier: Development Status :: 3 - Alpha
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: License :: OSI Approved :: MIT License
36
+ Classifier: Programming Language :: Python :: 3
37
+ Classifier: Programming Language :: Python :: 3.10
38
+ Classifier: Programming Language :: Python :: 3.11
39
+ Classifier: Programming Language :: Python :: 3.12
40
+ Classifier: Framework :: FastAPI
41
+ Classifier: Topic :: Communications :: Email
42
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
43
+ Requires-Python: >=3.10
44
+ Description-Content-Type: text/markdown
45
+ License-File: LICENSE
46
+ Requires-Dist: fastapi>=0.100.0
47
+ Requires-Dist: pydantic>=2.0.0
48
+ Requires-Dist: pydantic-settings>=2.0.0
49
+ Requires-Dist: redis>=5.0.0
50
+ Requires-Dist: aiosmtplib>=3.0.0
51
+ Requires-Dist: email-validator>=2.0.0
52
+ Requires-Dist: jinja2>=3.0.0
53
+ Provides-Extra: dev
54
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
55
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
56
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
57
+ Requires-Dist: httpx>=0.24.0; extra == "dev"
58
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
59
+ Requires-Dist: aiosmtpd>=1.4.0; extra == "dev"
60
+ Dynamic: license-file
61
+
62
+ # mailing2fast-fastapi
63
+
64
+ 🚀 Simple and fast mailing module for FastAPI with async support and Redis queue management
65
+
66
+ > [!WARNING]
67
+ > **Internal Use Notice**
68
+ >
69
+ > This package is designed and maintained by the **Solautyc Team** for internal use. While it is publicly available, it may not work as expected in all environments or use cases outside of our specific infrastructure. We do not provide support or guarantees for external usage, and we are not responsible for any issues that may arise from using this package in other contexts.
70
+ >
71
+ > Use at your own risk. Contributions and feedback are welcome, but compatibility with external environments is not guaranteed.
72
+
73
+ ## Features
74
+
75
+ - 📧 **Multiple SMTP Accounts**: Configure multiple named email accounts (e.g., "support", "transactions", "notifications")
76
+ - ⚡ **Async Email Sending**: Full async/await support with aiosmtplib
77
+ - 🔄 **Redis Queue Management**: FIFO queue with automatic retry and dead letter queue
78
+ - 🎯 **Two Sending Modes**:
79
+ - **Synchronous**: Send and wait for success/failure response
80
+ - **Async Queue**: Fire-and-forget with background worker processing
81
+ - 🚦 **Rate Limiting**: Configurable rate limits (default: 100 emails/hour)
82
+ - 📝 **Jinja2 Templates**: Built-in template support for HTML emails
83
+ - 📎 **Attachments**: Easy attachment handling
84
+ - 🔁 **Automatic Retry**: Exponential backoff for failed emails
85
+ - ⚙️ **Pydantic Settings**: Type-safe configuration with environment variables
86
+ - 🎨 **FastAPI Integration**: Ready-to-use dependencies and lifecycle hooks
87
+
88
+ ## Installation
89
+
90
+ ### From PyPI (Recommended)
91
+
92
+ ```bash
93
+ pip install mailing2fast-fastapi
94
+ ```
95
+
96
+ ### From Source
97
+
98
+ ```bash
99
+ # Clone the repository
100
+ git clone https://github.com/AngelDanielSanchezCastillo/mailing2fast-fastapi.git
101
+ cd mailing2fast-fastapi
102
+
103
+ # Install in development mode
104
+ pip install -e .
105
+
106
+ # Or install with dev dependencies
107
+ pip install -e ".[dev]"
108
+ ```
109
+
110
+ ## Quick Start
111
+
112
+ ### 1. Configure Environment Variables
113
+
114
+ Create a `.env` file:
115
+
116
+ ```bash
117
+ # Default SMTP Account
118
+ MAIL_SMTP_ACCOUNTS__DEFAULT__HOST=smtp.gmail.com
119
+ MAIL_SMTP_ACCOUNTS__DEFAULT__PORT=587
120
+ MAIL_SMTP_ACCOUNTS__DEFAULT__USERNAME=your-email@gmail.com
121
+ MAIL_SMTP_ACCOUNTS__DEFAULT__PASSWORD=your-app-password
122
+ MAIL_SMTP_ACCOUNTS__DEFAULT__FROM_EMAIL=your-email@gmail.com
123
+ MAIL_SMTP_ACCOUNTS__DEFAULT__FROM_NAME=Your Name
124
+
125
+ # Support Account (optional)
126
+ MAIL_SMTP_ACCOUNTS__SUPPORT__HOST=smtp.gmail.com
127
+ MAIL_SMTP_ACCOUNTS__SUPPORT__PORT=587
128
+ MAIL_SMTP_ACCOUNTS__SUPPORT__USERNAME=support@yourcompany.com
129
+ MAIL_SMTP_ACCOUNTS__SUPPORT__PASSWORD=support-password
130
+ MAIL_SMTP_ACCOUNTS__SUPPORT__FROM_EMAIL=support@yourcompany.com
131
+ MAIL_SMTP_ACCOUNTS__SUPPORT__FROM_NAME=Support Team
132
+
133
+ # Redis Configuration
134
+ MAIL_REDIS__HOST=localhost
135
+ MAIL_REDIS__PORT=6379
136
+ MAIL_REDIS__DB=0
137
+
138
+ # Rate Limiting (optional)
139
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_HOUR=100
140
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_MINUTE=10
141
+ ```
142
+
143
+ ### 2. Basic Usage - Synchronous Sending
144
+
145
+ ```python
146
+ import asyncio
147
+ from mailing2fast_fastapi import EmailSender, EmailMessage
148
+
149
+ async def main():
150
+ sender = EmailSender()
151
+
152
+ email = EmailMessage(
153
+ to=["recipient@example.com"],
154
+ subject="Hello from mailing2fast!",
155
+ body="This is a plain text email",
156
+ html="<h1>This is an HTML email</h1>",
157
+ )
158
+
159
+ result = await sender.send_email(email)
160
+
161
+ if result.is_success():
162
+ print(f"Email sent! Message ID: {result.message_id}")
163
+ else:
164
+ print(f"Failed to send: {result.error}")
165
+
166
+ asyncio.run(main())
167
+ ```
168
+
169
+ ### 3. Async Queue Mode
170
+
171
+ ```python
172
+ import asyncio
173
+ from mailing2fast_fastapi import EmailQueue, EmailMessage, EmailWorker
174
+
175
+ async def main():
176
+ # Start background worker
177
+ worker = EmailWorker()
178
+ await worker.start()
179
+
180
+ # Queue emails (fire-and-forget)
181
+ queue = EmailQueue()
182
+ await queue.connect()
183
+
184
+ email = EmailMessage(
185
+ to=["recipient@example.com"],
186
+ subject="Queued Email",
187
+ body="This email will be sent by the background worker",
188
+ )
189
+
190
+ await queue.enqueue(email)
191
+ print("Email queued successfully!")
192
+
193
+ # Worker will process it in the background
194
+ # Keep worker running...
195
+ await asyncio.sleep(60)
196
+
197
+ await worker.stop()
198
+ await queue.disconnect()
199
+
200
+ asyncio.run(main())
201
+ ```
202
+
203
+ ### 4. FastAPI Integration
204
+
205
+ ```python
206
+ from fastapi import FastAPI, Depends
207
+ from mailing2fast_fastapi import (
208
+ EmailMessage,
209
+ EmailSender,
210
+ EmailQueue,
211
+ get_email_sender,
212
+ get_email_queue,
213
+ startup_email_worker,
214
+ shutdown_email_worker,
215
+ )
216
+
217
+ app = FastAPI()
218
+
219
+ # Start/stop worker with app lifecycle
220
+ @app.on_event("startup")
221
+ async def startup():
222
+ await startup_email_worker()
223
+
224
+ @app.on_event("shutdown")
225
+ async def shutdown():
226
+ await shutdown_email_worker()
227
+
228
+ # Synchronous sending endpoint
229
+ @app.post("/send-email")
230
+ async def send_email(sender: EmailSender = Depends(get_email_sender)):
231
+ email = EmailMessage(
232
+ to=["user@example.com"],
233
+ subject="Welcome!",
234
+ html="<h1>Welcome to our service!</h1>",
235
+ )
236
+
237
+ result = await sender.send_email(email)
238
+ return {"status": result.status, "message_id": result.message_id}
239
+
240
+ # Async queue endpoint
241
+ @app.post("/queue-email")
242
+ async def queue_email(queue: EmailQueue = Depends(get_email_queue)):
243
+ email = EmailMessage(
244
+ to=["user@example.com"],
245
+ subject="Newsletter",
246
+ html="<h1>Monthly Newsletter</h1>",
247
+ smtp_account="support", # Use specific account
248
+ )
249
+
250
+ await queue.enqueue(email)
251
+ return {"status": "queued"}
252
+ ```
253
+
254
+ ## Multiple SMTP Accounts
255
+
256
+ Configure different accounts for different purposes:
257
+
258
+ ```python
259
+ email = EmailMessage(
260
+ to=["customer@example.com"],
261
+ subject="Payment Confirmation",
262
+ html="<h1>Payment received!</h1>",
263
+ smtp_account="transactions", # Use transactions account
264
+ )
265
+ ```
266
+
267
+ ## Templates
268
+
269
+ Create Jinja2 templates in `templates/emails/`:
270
+
271
+ **templates/emails/welcome.html:**
272
+ ```html
273
+ <h1>Welcome, {{ name }}!</h1>
274
+ <p>Thank you for joining {{ company_name }}.</p>
275
+ ```
276
+
277
+ **Usage:**
278
+ ```python
279
+ email = EmailMessage(
280
+ to=["user@example.com"],
281
+ subject="Welcome!",
282
+ template_name="welcome.html",
283
+ template_data={
284
+ "name": "John Doe",
285
+ "company_name": "Acme Corp"
286
+ },
287
+ )
288
+ ```
289
+
290
+ ## Rate Limiting
291
+
292
+ Rate limiting is enabled by default (100 emails/hour). Configure via environment variables:
293
+
294
+ ```bash
295
+ MAIL_RATE_LIMIT__ENABLED=true
296
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_HOUR=100
297
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_MINUTE=10
298
+ ```
299
+
300
+ ## Queue Management
301
+
302
+ Monitor queue status:
303
+
304
+ ```python
305
+ queue = EmailQueue()
306
+ await queue.connect()
307
+
308
+ stats = {
309
+ "pending": await queue.get_queue_size(),
310
+ "retry": await queue.get_retry_queue_size(),
311
+ "failed": await queue.get_dlq_size(),
312
+ }
313
+ print(stats)
314
+ ```
315
+
316
+ ## 📚 Documentation
317
+
318
+ - **[Usage Guide](docs/usage.md)** - Comprehensive usage guide
319
+ - **[Configuration](docs/env.example)** - All configuration options
320
+
321
+ ## Module Structure
322
+
323
+ ```
324
+ mailing2fast-fastapi/
325
+ ├── pyproject.toml
326
+ ├── MANIFEST.in
327
+ ├── README.md
328
+ ├── LICENSE
329
+ ├── src/
330
+ │ └── mailing2fast_fastapi/
331
+ │ ├── __init__.py
332
+ │ ├── __version__.py
333
+ │ ├── settings.py # Pydantic settings
334
+ │ ├── models.py # Email schemas
335
+ │ ├── sender.py # Email sender
336
+ │ ├── queue.py # Redis queue
337
+ │ ├── worker.py # Background worker
338
+ │ └── dependencies.py # FastAPI deps
339
+ ├── docs/
340
+ │ ├── env.example
341
+ │ ├── usage.md
342
+ │ └── publishing.md
343
+ ├── examples/
344
+ │ ├── basic_usage.py
345
+ │ ├── async_queue.py
346
+ │ └── fastapi_integration.py
347
+ └── tests/
348
+ ├── test_sender.py
349
+ ├── test_queue.py
350
+ └── test_integration.py
351
+ ```
352
+
353
+ ## Acknowledgments
354
+
355
+ This project uses the following open-source packages:
356
+
357
+ - [FastAPI](https://github.com/tiangolo/fastapi) - Modern web framework (MIT License)
358
+ - [Pydantic](https://github.com/pydantic/pydantic) - Data validation (MIT License)
359
+ - [Redis](https://github.com/redis/redis-py) - Redis client (MIT License)
360
+ - [aiosmtplib](https://github.com/cole/aiosmtplib) - Async SMTP client (MIT License)
361
+ - [Jinja2](https://github.com/pallets/jinja) - Template engine (BSD License)
362
+
363
+ We are grateful to the maintainers and contributors of these projects.
364
+
365
+ ## License
366
+
367
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
368
+
369
+ Copyright (c) 2026 Angel Daniel Sanchez Castillo
370
+
371
+ **Note**: This package is designed and maintained by the Solautyc Team for internal use. While publicly available under MIT license, use at your own risk.
@@ -0,0 +1,310 @@
1
+ # mailing2fast-fastapi
2
+
3
+ 🚀 Simple and fast mailing module for FastAPI with async support and Redis queue management
4
+
5
+ > [!WARNING]
6
+ > **Internal Use Notice**
7
+ >
8
+ > This package is designed and maintained by the **Solautyc Team** for internal use. While it is publicly available, it may not work as expected in all environments or use cases outside of our specific infrastructure. We do not provide support or guarantees for external usage, and we are not responsible for any issues that may arise from using this package in other contexts.
9
+ >
10
+ > Use at your own risk. Contributions and feedback are welcome, but compatibility with external environments is not guaranteed.
11
+
12
+ ## Features
13
+
14
+ - 📧 **Multiple SMTP Accounts**: Configure multiple named email accounts (e.g., "support", "transactions", "notifications")
15
+ - ⚡ **Async Email Sending**: Full async/await support with aiosmtplib
16
+ - 🔄 **Redis Queue Management**: FIFO queue with automatic retry and dead letter queue
17
+ - 🎯 **Two Sending Modes**:
18
+ - **Synchronous**: Send and wait for success/failure response
19
+ - **Async Queue**: Fire-and-forget with background worker processing
20
+ - 🚦 **Rate Limiting**: Configurable rate limits (default: 100 emails/hour)
21
+ - 📝 **Jinja2 Templates**: Built-in template support for HTML emails
22
+ - 📎 **Attachments**: Easy attachment handling
23
+ - 🔁 **Automatic Retry**: Exponential backoff for failed emails
24
+ - ⚙️ **Pydantic Settings**: Type-safe configuration with environment variables
25
+ - 🎨 **FastAPI Integration**: Ready-to-use dependencies and lifecycle hooks
26
+
27
+ ## Installation
28
+
29
+ ### From PyPI (Recommended)
30
+
31
+ ```bash
32
+ pip install mailing2fast-fastapi
33
+ ```
34
+
35
+ ### From Source
36
+
37
+ ```bash
38
+ # Clone the repository
39
+ git clone https://github.com/AngelDanielSanchezCastillo/mailing2fast-fastapi.git
40
+ cd mailing2fast-fastapi
41
+
42
+ # Install in development mode
43
+ pip install -e .
44
+
45
+ # Or install with dev dependencies
46
+ pip install -e ".[dev]"
47
+ ```
48
+
49
+ ## Quick Start
50
+
51
+ ### 1. Configure Environment Variables
52
+
53
+ Create a `.env` file:
54
+
55
+ ```bash
56
+ # Default SMTP Account
57
+ MAIL_SMTP_ACCOUNTS__DEFAULT__HOST=smtp.gmail.com
58
+ MAIL_SMTP_ACCOUNTS__DEFAULT__PORT=587
59
+ MAIL_SMTP_ACCOUNTS__DEFAULT__USERNAME=your-email@gmail.com
60
+ MAIL_SMTP_ACCOUNTS__DEFAULT__PASSWORD=your-app-password
61
+ MAIL_SMTP_ACCOUNTS__DEFAULT__FROM_EMAIL=your-email@gmail.com
62
+ MAIL_SMTP_ACCOUNTS__DEFAULT__FROM_NAME=Your Name
63
+
64
+ # Support Account (optional)
65
+ MAIL_SMTP_ACCOUNTS__SUPPORT__HOST=smtp.gmail.com
66
+ MAIL_SMTP_ACCOUNTS__SUPPORT__PORT=587
67
+ MAIL_SMTP_ACCOUNTS__SUPPORT__USERNAME=support@yourcompany.com
68
+ MAIL_SMTP_ACCOUNTS__SUPPORT__PASSWORD=support-password
69
+ MAIL_SMTP_ACCOUNTS__SUPPORT__FROM_EMAIL=support@yourcompany.com
70
+ MAIL_SMTP_ACCOUNTS__SUPPORT__FROM_NAME=Support Team
71
+
72
+ # Redis Configuration
73
+ MAIL_REDIS__HOST=localhost
74
+ MAIL_REDIS__PORT=6379
75
+ MAIL_REDIS__DB=0
76
+
77
+ # Rate Limiting (optional)
78
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_HOUR=100
79
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_MINUTE=10
80
+ ```
81
+
82
+ ### 2. Basic Usage - Synchronous Sending
83
+
84
+ ```python
85
+ import asyncio
86
+ from mailing2fast_fastapi import EmailSender, EmailMessage
87
+
88
+ async def main():
89
+ sender = EmailSender()
90
+
91
+ email = EmailMessage(
92
+ to=["recipient@example.com"],
93
+ subject="Hello from mailing2fast!",
94
+ body="This is a plain text email",
95
+ html="<h1>This is an HTML email</h1>",
96
+ )
97
+
98
+ result = await sender.send_email(email)
99
+
100
+ if result.is_success():
101
+ print(f"Email sent! Message ID: {result.message_id}")
102
+ else:
103
+ print(f"Failed to send: {result.error}")
104
+
105
+ asyncio.run(main())
106
+ ```
107
+
108
+ ### 3. Async Queue Mode
109
+
110
+ ```python
111
+ import asyncio
112
+ from mailing2fast_fastapi import EmailQueue, EmailMessage, EmailWorker
113
+
114
+ async def main():
115
+ # Start background worker
116
+ worker = EmailWorker()
117
+ await worker.start()
118
+
119
+ # Queue emails (fire-and-forget)
120
+ queue = EmailQueue()
121
+ await queue.connect()
122
+
123
+ email = EmailMessage(
124
+ to=["recipient@example.com"],
125
+ subject="Queued Email",
126
+ body="This email will be sent by the background worker",
127
+ )
128
+
129
+ await queue.enqueue(email)
130
+ print("Email queued successfully!")
131
+
132
+ # Worker will process it in the background
133
+ # Keep worker running...
134
+ await asyncio.sleep(60)
135
+
136
+ await worker.stop()
137
+ await queue.disconnect()
138
+
139
+ asyncio.run(main())
140
+ ```
141
+
142
+ ### 4. FastAPI Integration
143
+
144
+ ```python
145
+ from fastapi import FastAPI, Depends
146
+ from mailing2fast_fastapi import (
147
+ EmailMessage,
148
+ EmailSender,
149
+ EmailQueue,
150
+ get_email_sender,
151
+ get_email_queue,
152
+ startup_email_worker,
153
+ shutdown_email_worker,
154
+ )
155
+
156
+ app = FastAPI()
157
+
158
+ # Start/stop worker with app lifecycle
159
+ @app.on_event("startup")
160
+ async def startup():
161
+ await startup_email_worker()
162
+
163
+ @app.on_event("shutdown")
164
+ async def shutdown():
165
+ await shutdown_email_worker()
166
+
167
+ # Synchronous sending endpoint
168
+ @app.post("/send-email")
169
+ async def send_email(sender: EmailSender = Depends(get_email_sender)):
170
+ email = EmailMessage(
171
+ to=["user@example.com"],
172
+ subject="Welcome!",
173
+ html="<h1>Welcome to our service!</h1>",
174
+ )
175
+
176
+ result = await sender.send_email(email)
177
+ return {"status": result.status, "message_id": result.message_id}
178
+
179
+ # Async queue endpoint
180
+ @app.post("/queue-email")
181
+ async def queue_email(queue: EmailQueue = Depends(get_email_queue)):
182
+ email = EmailMessage(
183
+ to=["user@example.com"],
184
+ subject="Newsletter",
185
+ html="<h1>Monthly Newsletter</h1>",
186
+ smtp_account="support", # Use specific account
187
+ )
188
+
189
+ await queue.enqueue(email)
190
+ return {"status": "queued"}
191
+ ```
192
+
193
+ ## Multiple SMTP Accounts
194
+
195
+ Configure different accounts for different purposes:
196
+
197
+ ```python
198
+ email = EmailMessage(
199
+ to=["customer@example.com"],
200
+ subject="Payment Confirmation",
201
+ html="<h1>Payment received!</h1>",
202
+ smtp_account="transactions", # Use transactions account
203
+ )
204
+ ```
205
+
206
+ ## Templates
207
+
208
+ Create Jinja2 templates in `templates/emails/`:
209
+
210
+ **templates/emails/welcome.html:**
211
+ ```html
212
+ <h1>Welcome, {{ name }}!</h1>
213
+ <p>Thank you for joining {{ company_name }}.</p>
214
+ ```
215
+
216
+ **Usage:**
217
+ ```python
218
+ email = EmailMessage(
219
+ to=["user@example.com"],
220
+ subject="Welcome!",
221
+ template_name="welcome.html",
222
+ template_data={
223
+ "name": "John Doe",
224
+ "company_name": "Acme Corp"
225
+ },
226
+ )
227
+ ```
228
+
229
+ ## Rate Limiting
230
+
231
+ Rate limiting is enabled by default (100 emails/hour). Configure via environment variables:
232
+
233
+ ```bash
234
+ MAIL_RATE_LIMIT__ENABLED=true
235
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_HOUR=100
236
+ MAIL_RATE_LIMIT__MAX_EMAILS_PER_MINUTE=10
237
+ ```
238
+
239
+ ## Queue Management
240
+
241
+ Monitor queue status:
242
+
243
+ ```python
244
+ queue = EmailQueue()
245
+ await queue.connect()
246
+
247
+ stats = {
248
+ "pending": await queue.get_queue_size(),
249
+ "retry": await queue.get_retry_queue_size(),
250
+ "failed": await queue.get_dlq_size(),
251
+ }
252
+ print(stats)
253
+ ```
254
+
255
+ ## 📚 Documentation
256
+
257
+ - **[Usage Guide](docs/usage.md)** - Comprehensive usage guide
258
+ - **[Configuration](docs/env.example)** - All configuration options
259
+
260
+ ## Module Structure
261
+
262
+ ```
263
+ mailing2fast-fastapi/
264
+ ├── pyproject.toml
265
+ ├── MANIFEST.in
266
+ ├── README.md
267
+ ├── LICENSE
268
+ ├── src/
269
+ │ └── mailing2fast_fastapi/
270
+ │ ├── __init__.py
271
+ │ ├── __version__.py
272
+ │ ├── settings.py # Pydantic settings
273
+ │ ├── models.py # Email schemas
274
+ │ ├── sender.py # Email sender
275
+ │ ├── queue.py # Redis queue
276
+ │ ├── worker.py # Background worker
277
+ │ └── dependencies.py # FastAPI deps
278
+ ├── docs/
279
+ │ ├── env.example
280
+ │ ├── usage.md
281
+ │ └── publishing.md
282
+ ├── examples/
283
+ │ ├── basic_usage.py
284
+ │ ├── async_queue.py
285
+ │ └── fastapi_integration.py
286
+ └── tests/
287
+ ├── test_sender.py
288
+ ├── test_queue.py
289
+ └── test_integration.py
290
+ ```
291
+
292
+ ## Acknowledgments
293
+
294
+ This project uses the following open-source packages:
295
+
296
+ - [FastAPI](https://github.com/tiangolo/fastapi) - Modern web framework (MIT License)
297
+ - [Pydantic](https://github.com/pydantic/pydantic) - Data validation (MIT License)
298
+ - [Redis](https://github.com/redis/redis-py) - Redis client (MIT License)
299
+ - [aiosmtplib](https://github.com/cole/aiosmtplib) - Async SMTP client (MIT License)
300
+ - [Jinja2](https://github.com/pallets/jinja) - Template engine (BSD License)
301
+
302
+ We are grateful to the maintainers and contributors of these projects.
303
+
304
+ ## License
305
+
306
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
307
+
308
+ Copyright (c) 2026 Angel Daniel Sanchez Castillo
309
+
310
+ **Note**: This package is designed and maintained by the Solautyc Team for internal use. While publicly available under MIT license, use at your own risk.