mailko 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.
- mailko-0.1.0/.gitignore +13 -0
- mailko-0.1.0/CHANGELOG.md +26 -0
- mailko-0.1.0/LICENSE +21 -0
- mailko-0.1.0/PKG-INFO +285 -0
- mailko-0.1.0/README.md +248 -0
- mailko-0.1.0/pyproject.toml +69 -0
- mailko-0.1.0/src/mailko/__init__.py +68 -0
- mailko-0.1.0/src/mailko/_version.py +1 -0
- mailko-0.1.0/src/mailko/client.py +270 -0
- mailko-0.1.0/src/mailko/constants.py +54 -0
- mailko-0.1.0/src/mailko/contrib/__init__.py +0 -0
- mailko-0.1.0/src/mailko/contrib/django/__init__.py +12 -0
- mailko-0.1.0/src/mailko/contrib/django/backend.py +252 -0
- mailko-0.1.0/src/mailko/contrib/django/conf.py +51 -0
- mailko-0.1.0/src/mailko/contrib/django/signals.py +18 -0
- mailko-0.1.0/src/mailko/contrib/django/urls.py +9 -0
- mailko-0.1.0/src/mailko/contrib/django/views.py +80 -0
- mailko-0.1.0/src/mailko/errors.py +195 -0
- mailko-0.1.0/src/mailko/message.py +222 -0
- mailko-0.1.0/src/mailko/py.typed +0 -0
- mailko-0.1.0/src/mailko/resources.py +332 -0
- mailko-0.1.0/src/mailko/webhooks.py +115 -0
- mailko-0.1.0/tests/__init__.py +0 -0
- mailko-0.1.0/tests/conftest.py +40 -0
- mailko-0.1.0/tests/test_client.py +255 -0
- mailko-0.1.0/tests/test_django_backend.py +205 -0
- mailko-0.1.0/tests/test_django_webhook.py +105 -0
- mailko-0.1.0/tests/test_message.py +95 -0
- mailko-0.1.0/tests/test_webhooks.py +72 -0
- mailko-0.1.0/tests/urls.py +3 -0
mailko-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Todos los cambios de esta librería. Formato [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/),
|
|
4
|
+
versiones [SemVer](https://semver.org/lang/es/).
|
|
5
|
+
|
|
6
|
+
## [Unreleased]
|
|
7
|
+
|
|
8
|
+
## [0.1.0] - 2026-11-17
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Cliente de la API `/v1` (versión `2026-10-01`): correos (`send`, `batch`, `list`, `retrieve`), dominios,
|
|
13
|
+
supresiones, plantillas, uso, webhooks, contactos, listas, segmentos, campañas, importaciones y «Conectar
|
|
14
|
+
Mailko» para apps socias.
|
|
15
|
+
- `Idempotency-Key` en cada escritura, la misma en cada reintento; reintentos solo cuando es seguro (sin
|
|
16
|
+
respuesta, `409 idempotency_key_in_progress`, `429` con `Retry-After`, `5xx`).
|
|
17
|
+
- Un error por estado HTTP (`AuthenticationError`, `PermissionDeniedError`, `RateLimitError`…) con el `code`,
|
|
18
|
+
el `message` en español y el `request_id` de Mailko.
|
|
19
|
+
- `build_email` y `check_email`: el cuerpo de un correo y los límites de Mailko revisados antes de llamar.
|
|
20
|
+
- `verify_signature` y `construct_event` para los webhooks (`Mailko-Signature`), con varios secretos a la vez.
|
|
21
|
+
- Django: `mailko.contrib.django.EmailBackend` (también como mailer de `MAILERS` en Django 6.1), la vista del
|
|
22
|
+
webhook (`mailko.contrib.django.urls`) y las señales `email_event` y `webhook_received`.
|
|
23
|
+
|
|
24
|
+
### Security
|
|
25
|
+
|
|
26
|
+
- La llave solo viaja por https (http únicamente hacia un host de desarrollo) y nunca se siguen redirecciones.
|
mailko-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bithaus SAS
|
|
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.
|
mailko-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: mailko
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Librería oficial de Mailko para Python: la API /v1, la verificación de webhooks y un backend de correo para Django.
|
|
5
|
+
Project-URL: Homepage, https://mailko.co
|
|
6
|
+
Project-URL: Documentation, https://github.com/bithaus-sas/mailko-python#readme
|
|
7
|
+
Project-URL: Source, https://github.com/bithaus-sas/mailko-python
|
|
8
|
+
Project-URL: Changelog, https://github.com/bithaus-sas/mailko-python/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Bithaus SAS
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: django,email,mailko,ses,transactional,webhooks
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Framework :: Django
|
|
15
|
+
Classifier: Framework :: Django :: 4.2
|
|
16
|
+
Classifier: Framework :: Django :: 5.2
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Communications :: Email
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Requires-Dist: requests<3,>=2.31
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
30
|
+
Requires-Dist: django>=4.2; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
32
|
+
Requires-Dist: responses>=0.25; extra == 'dev'
|
|
33
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
34
|
+
Provides-Extra: django
|
|
35
|
+
Requires-Dist: django>=4.2; extra == 'django'
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
|
|
38
|
+
# Mailko para Python
|
|
39
|
+
|
|
40
|
+
La librería oficial de [Mailko](https://mailko.co) para Python: envía correos por la API `/v1`, verifica los
|
|
41
|
+
webhooks y, en Django, reemplaza el backend de correo con una línea.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install mailko # solo el cliente
|
|
45
|
+
pip install "mailko[django]" # con la integración de Django
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Python 3.10 o superior. Django 4.2 o superior para `mailko.contrib.django`.
|
|
49
|
+
|
|
50
|
+
## Antes de empezar
|
|
51
|
+
|
|
52
|
+
En el panel de Mailko, dentro del proyecto desde el que vas a enviar:
|
|
53
|
+
|
|
54
|
+
1. **Verifica tu dominio** (Dominios → Agregar): publica los registros DNS que te muestra.
|
|
55
|
+
2. **Crea una API key** (Configuración → Desarrolladores) con el permiso `send`. Empieza por `mk_live_`; una
|
|
56
|
+
`mk_test_` valida todo y no entrega nada, útil en pruebas.
|
|
57
|
+
3. Si vas a recibir webhooks, **crea el webhook** con la URL de tu servidor y guarda su secreto (`whsec_…`):
|
|
58
|
+
solo se muestra una vez.
|
|
59
|
+
|
|
60
|
+
## Enviar un correo
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
import mailko
|
|
64
|
+
|
|
65
|
+
client = mailko.Mailko("mk_live_…")
|
|
66
|
+
|
|
67
|
+
email = client.emails.send(
|
|
68
|
+
from_="Tienda <pedidos@tienda.co>",
|
|
69
|
+
to="cliente@correo.com",
|
|
70
|
+
subject="Tu pedido #1234",
|
|
71
|
+
html="<p>Gracias por tu compra</p>",
|
|
72
|
+
text="Gracias por tu compra",
|
|
73
|
+
attachments=[mailko.Attachment("factura.pdf", pdf_bytes)],
|
|
74
|
+
tags={"pedido": "1234"},
|
|
75
|
+
idempotency_key="pedido-1234-confirmacion",
|
|
76
|
+
)
|
|
77
|
+
print(email["id"], email["status"]) # msg_… queued
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- `from_` lleva guion bajo porque `from` es palabra reservada de Python.
|
|
81
|
+
- Los adjuntos van como `mailko.Attachment(nombre, bytes)`, una tupla `(nombre, bytes, tipo)` o el `dict` de la
|
|
82
|
+
API con el contenido en base64. El tipo se adivina por el nombre si no lo das.
|
|
83
|
+
- `tags` vuelve en cada webhook de ese correo: úsalo para encontrar tu registro.
|
|
84
|
+
- Hasta 50 destinatarios entre `to`, `cc` y `bcc`, 20 adjuntos y 10 MB por correo. La librería lo revisa antes
|
|
85
|
+
de llamar y lanza `mailko.MessageRejectedError` con la explicación.
|
|
86
|
+
|
|
87
|
+
Varios correos de una vez (hasta 100, todos o ninguno):
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
client.emails.batch([
|
|
91
|
+
mailko.build_email(from_="pedidos@tienda.co", to="ana@correo.com", subject="Hola", text="…"),
|
|
92
|
+
mailko.build_email(from_="pedidos@tienda.co", to="luis@correo.com", subject="Hola", text="…"),
|
|
93
|
+
])
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Con una plantilla del panel:
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
client.emails.send(
|
|
100
|
+
from_="pedidos@tienda.co",
|
|
101
|
+
to="ana@correo.com",
|
|
102
|
+
template={"id": "bienvenida", "variables": {"nombre": "Ana"}},
|
|
103
|
+
)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Reintentos e idempotencia
|
|
107
|
+
|
|
108
|
+
Cada escritura lleva una `Idempotency-Key`: la que pases o una nueva. La librería reintenta (2 veces por
|
|
109
|
+
defecto) **con la misma clave** solo cuando es seguro: Mailko no respondió, la misma clave todavía se procesa
|
|
110
|
+
(`409`), demasiadas peticiones (`429`, esperando lo que diga `Retry-After` hasta `max_retry_after`) o un error
|
|
111
|
+
de Mailko (`5xx`). Así un reintento nunca envía el correo dos veces.
|
|
112
|
+
|
|
113
|
+
Si reintentas por tu cuenta (una tarea de Celery), pasa **siempre la misma** `idempotency_key` para el mismo
|
|
114
|
+
correo, por ejemplo `f"pedido-{pedido.id}-confirmacion"`.
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
client = mailko.Mailko(
|
|
118
|
+
"mk_live_…",
|
|
119
|
+
timeout=(5, 30), # segundos: conectar, leer
|
|
120
|
+
max_retries=2,
|
|
121
|
+
max_retry_after=10, # un Retry-After más largo se lanza como RateLimitError
|
|
122
|
+
)
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Errores
|
|
126
|
+
|
|
127
|
+
Todo error de Mailko trae `message` (una frase en español para quien envió), `code` (estable: es lo que debe
|
|
128
|
+
mirar tu código), `status`, `request_id` (dáselo a soporte) y, en `validation_error`, `fields`.
|
|
129
|
+
|
|
130
|
+
| Clase | Cuándo |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `MessageRejectedError` | La librería lo rechazó antes de llamar (sin destinatario, muy grande…). |
|
|
133
|
+
| `BadRequestError` | 400, 413, 415, 422: la petición está mal; corrígela. |
|
|
134
|
+
| `AuthenticationError` | 401: la llave falta, está mal, se revocó o venció. |
|
|
135
|
+
| `PaymentRequiredError` | 402: el plan o el saldo no alcanza (`insufficient_balance`…). |
|
|
136
|
+
| `PermissionDeniedError` | 403: `missing_scope`, `domain_not_verified`, `workspace_paused`… |
|
|
137
|
+
| `NotFoundError` | 404. |
|
|
138
|
+
| `ConflictError` | 409 (`confirmation_required`, `suppression_not_removable`…). |
|
|
139
|
+
| `IdempotencyError` | La clave sigue en proceso o se usó con otra petición. |
|
|
140
|
+
| `RateLimitError` | 429; `retry_after` dice cuántos segundos esperar. |
|
|
141
|
+
| `ServerError` | 5xx: problema de Mailko; reintenta con la misma clave. |
|
|
142
|
+
| `APIConnectionError` | Mailko no respondió. |
|
|
143
|
+
|
|
144
|
+
Todas heredan de `mailko.MailkoError`.
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
try:
|
|
148
|
+
client.emails.send(...)
|
|
149
|
+
except mailko.PermissionDeniedError as exc:
|
|
150
|
+
if exc.code == "domain_not_verified":
|
|
151
|
+
...
|
|
152
|
+
except mailko.MailkoError as exc:
|
|
153
|
+
logger.warning("Mailko: %s", exc)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Un `202` con `"status": "suppressed"` significa que Mailko tomó la petición y no envió nada: todas las
|
|
157
|
+
direcciones están en la lista de supresión del proyecto (rebotaron o se quejaron antes).
|
|
158
|
+
|
|
159
|
+
## Webhooks
|
|
160
|
+
|
|
161
|
+
Mailko firma cada aviso en la cabecera `Mailko-Signature`. Verifica el **cuerpo crudo**, tal como llegó:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
event = mailko.construct_event(
|
|
165
|
+
request.body, # bytes, sin volver a serializar
|
|
166
|
+
request.headers.get("Mailko-Signature"),
|
|
167
|
+
"whsec_…", # o una lista: varios proyectos o una rotación
|
|
168
|
+
)
|
|
169
|
+
if event["type"] == "email.bounced":
|
|
170
|
+
email = event["data"]["object"]
|
|
171
|
+
...
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`construct_event` lanza `mailko.SignatureVerificationError` si la firma falta, no corresponde o tiene más de
|
|
175
|
+
5 minutos. Un evento puede llegar repetido: deduplica por `event["id"]`.
|
|
176
|
+
|
|
177
|
+
## Django
|
|
178
|
+
|
|
179
|
+
```python
|
|
180
|
+
# settings.py
|
|
181
|
+
EMAIL_BACKEND = "mailko.contrib.django.EmailBackend"
|
|
182
|
+
MAILKO_API_KEY = env("MAILKO_API_KEY")
|
|
183
|
+
MAILKO_WEBHOOK_SECRET = env("MAILKO_WEBHOOK_SECRET") # whsec_…; varios separados por coma
|
|
184
|
+
|
|
185
|
+
# urls.py
|
|
186
|
+
path("mailko/", include("mailko.contrib.django.urls")), # → /mailko/webhook/
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Con `MAILERS` (Django 6.1 en adelante) es igual, y cada mailer puede llevar su propia llave:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
MAILERS = {
|
|
193
|
+
"default": {"BACKEND": "mailko.contrib.django.EmailBackend"}, # usa MAILKO_API_KEY
|
|
194
|
+
"negocios": {"BACKEND": "mailko.contrib.django.EmailBackend", "OPTIONS": {"api_key": env("MAILKO_NEGOCIOS_KEY")}},
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
No necesita `INSTALLED_APPS` ni migraciones. Desde ahí, `send_mail`, `EmailMessage`, `EmailMultiAlternatives` y
|
|
199
|
+
cualquier librería que envíe por Django salen por Mailko: el cuerpo y su alternativa HTML, `cc`, `bcc`,
|
|
200
|
+
`reply_to`, los adjuntos y las cabeceras que Mailko permite (`List-Unsubscribe`, `References`, `In-Reply-To`…;
|
|
201
|
+
las demás se omiten, porque Mailko rechazaría el correo entero).
|
|
202
|
+
|
|
203
|
+
Lo que Django no sabe decir va como atributo del mensaje:
|
|
204
|
+
|
|
205
|
+
```python
|
|
206
|
+
message = EmailMultiAlternatives(subject, text, "pedidos@tienda.co", ["ana@correo.com"])
|
|
207
|
+
message.attach_alternative(html, "text/html")
|
|
208
|
+
message.mailko_tags = {"pedido": "1234"}
|
|
209
|
+
message.mailko_idempotency_key = f"pedido-{pedido.id}-confirmacion" # la misma en cada reintento
|
|
210
|
+
message.mailko_stream = "marketing" # por defecto, transactional
|
|
211
|
+
message.send()
|
|
212
|
+
print(message.mailko_id, message.mailko_status)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
La `mailko_idempotency_key` nombra **un** correo: en cada reintento va con el mismo contenido (Mailko responde
|
|
216
|
+
lo mismo que la primera vez y no lo envía de nuevo). Si la misma clave llega con otro contenido, Mailko lo
|
|
217
|
+
rechaza con `IdempotencyError`, porque podría ser otro correo.
|
|
218
|
+
|
|
219
|
+
Si todas las direcciones de un mensaje están en la lista de supresión, ese mensaje no sale, los demás del lote
|
|
220
|
+
sí, y al final se lanza `mailko.SuppressedError` (salvo con `fail_silently`). Una alternativa que no sea HTML ni
|
|
221
|
+
texto (`text/calendar`, por ejemplo) se omite: la API de Mailko envía solo `html` y `text`.
|
|
222
|
+
|
|
223
|
+
### Qué pasó con cada correo
|
|
224
|
+
|
|
225
|
+
La vista del webhook verifica la firma, ignora los eventos repetidos y emite señales:
|
|
226
|
+
|
|
227
|
+
```python
|
|
228
|
+
from django.dispatch import receiver
|
|
229
|
+
from mailko.contrib.django.signals import email_event
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
@receiver(email_event)
|
|
233
|
+
def on_mailko_email(sender, event, type, email, **kwargs):
|
|
234
|
+
pedido = email.get("tags", {}).get("pedido")
|
|
235
|
+
if type == "email.bounced" and email["event"].get("bounce_type") == "permanent":
|
|
236
|
+
...
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Si tu receptor lanza una excepción, la vista responde 500 y Mailko reenvía el evento más tarde.
|
|
240
|
+
|
|
241
|
+
### Configuración
|
|
242
|
+
|
|
243
|
+
| Variable | Qué es | Por defecto |
|
|
244
|
+
|---|---|---|
|
|
245
|
+
| `MAILKO_API_KEY` | La llave del proyecto. | — |
|
|
246
|
+
| `MAILKO_API_KEYS_BY_DOMAIN` | `{"negocios.tienda.co": "mk_live_…"}`: otro proyecto para lo que sale de ese dominio. | `{}` |
|
|
247
|
+
| `MAILKO_API_URL` | La dirección de la API. | `https://api.mailko.co` |
|
|
248
|
+
| `MAILKO_TIMEOUT` | Segundos, o `(conectar, leer)`. | `(5, 30)` |
|
|
249
|
+
| `MAILKO_MAX_RETRIES` | Reintentos dentro de un envío. | `2` |
|
|
250
|
+
| `MAILKO_MAX_RETRY_AFTER` | El `Retry-After` más largo que se espera dentro de un envío. | `10` |
|
|
251
|
+
| `MAILKO_WEBHOOK_SECRET` | `whsec_…`; una lista o separados por coma para varios proyectos. | — |
|
|
252
|
+
| `MAILKO_WEBHOOK_TOLERANCE` | Segundos que vale una firma. | `300` |
|
|
253
|
+
| `MAILKO_WEBHOOK_DEDUP_SECONDS` | Cuánto se recuerda un evento ya procesado; `0` lo apaga. Usa la caché `default` de Django: con varios procesos necesita una compartida (Redis, Memcached, base de datos), no `LocMemCache`. Aun así, deja tu receptor idempotente: dos entregas simultáneas del mismo evento pueden pasar las dos. | `86400` |
|
|
254
|
+
|
|
255
|
+
## Todo lo demás de la API
|
|
256
|
+
|
|
257
|
+
Cada recurso de `/v1` cuelga del cliente y responde el JSON de Mailko como `dict`. Las listas responden una
|
|
258
|
+
página (`{"data": [...], "pagination": {...}}`) y `list_all()` las recorre todas:
|
|
259
|
+
|
|
260
|
+
```python
|
|
261
|
+
client.me.retrieve()
|
|
262
|
+
client.domains.create("tienda.co") # los registros DNS para publicar
|
|
263
|
+
client.domains.verify(domain_id)
|
|
264
|
+
for email in client.emails.list_all(status="bounced"):
|
|
265
|
+
...
|
|
266
|
+
client.suppressions.create("ana@correo.com", detail="Pidió no recibir más")
|
|
267
|
+
client.webhook_endpoints.create(url="https://tienda.co/mailko/webhook/", topics=["email.bounced"])
|
|
268
|
+
client.campaigns.send(campaign_id, confirm=True)
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
La referencia completa de la API está en [api.mailko.co/docs](https://api.mailko.co/docs/).
|
|
272
|
+
|
|
273
|
+
## Desarrollo
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
|
277
|
+
.venv/bin/ruff check . && .venv/bin/ruff format --check .
|
|
278
|
+
.venv/bin/pytest
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Una versión nueva se publica en PyPI sola al subir su tag (`vX.Y.Z`): ver `.github/workflows/publish.yml`.
|
|
282
|
+
|
|
283
|
+
## Licencia
|
|
284
|
+
|
|
285
|
+
MIT © Bithaus SAS.
|
mailko-0.1.0/README.md
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# Mailko para Python
|
|
2
|
+
|
|
3
|
+
La librería oficial de [Mailko](https://mailko.co) para Python: envía correos por la API `/v1`, verifica los
|
|
4
|
+
webhooks y, en Django, reemplaza el backend de correo con una línea.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
pip install mailko # solo el cliente
|
|
8
|
+
pip install "mailko[django]" # con la integración de Django
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Python 3.10 o superior. Django 4.2 o superior para `mailko.contrib.django`.
|
|
12
|
+
|
|
13
|
+
## Antes de empezar
|
|
14
|
+
|
|
15
|
+
En el panel de Mailko, dentro del proyecto desde el que vas a enviar:
|
|
16
|
+
|
|
17
|
+
1. **Verifica tu dominio** (Dominios → Agregar): publica los registros DNS que te muestra.
|
|
18
|
+
2. **Crea una API key** (Configuración → Desarrolladores) con el permiso `send`. Empieza por `mk_live_`; una
|
|
19
|
+
`mk_test_` valida todo y no entrega nada, útil en pruebas.
|
|
20
|
+
3. Si vas a recibir webhooks, **crea el webhook** con la URL de tu servidor y guarda su secreto (`whsec_…`):
|
|
21
|
+
solo se muestra una vez.
|
|
22
|
+
|
|
23
|
+
## Enviar un correo
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
import mailko
|
|
27
|
+
|
|
28
|
+
client = mailko.Mailko("mk_live_…")
|
|
29
|
+
|
|
30
|
+
email = client.emails.send(
|
|
31
|
+
from_="Tienda <pedidos@tienda.co>",
|
|
32
|
+
to="cliente@correo.com",
|
|
33
|
+
subject="Tu pedido #1234",
|
|
34
|
+
html="<p>Gracias por tu compra</p>",
|
|
35
|
+
text="Gracias por tu compra",
|
|
36
|
+
attachments=[mailko.Attachment("factura.pdf", pdf_bytes)],
|
|
37
|
+
tags={"pedido": "1234"},
|
|
38
|
+
idempotency_key="pedido-1234-confirmacion",
|
|
39
|
+
)
|
|
40
|
+
print(email["id"], email["status"]) # msg_… queued
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- `from_` lleva guion bajo porque `from` es palabra reservada de Python.
|
|
44
|
+
- Los adjuntos van como `mailko.Attachment(nombre, bytes)`, una tupla `(nombre, bytes, tipo)` o el `dict` de la
|
|
45
|
+
API con el contenido en base64. El tipo se adivina por el nombre si no lo das.
|
|
46
|
+
- `tags` vuelve en cada webhook de ese correo: úsalo para encontrar tu registro.
|
|
47
|
+
- Hasta 50 destinatarios entre `to`, `cc` y `bcc`, 20 adjuntos y 10 MB por correo. La librería lo revisa antes
|
|
48
|
+
de llamar y lanza `mailko.MessageRejectedError` con la explicación.
|
|
49
|
+
|
|
50
|
+
Varios correos de una vez (hasta 100, todos o ninguno):
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
client.emails.batch([
|
|
54
|
+
mailko.build_email(from_="pedidos@tienda.co", to="ana@correo.com", subject="Hola", text="…"),
|
|
55
|
+
mailko.build_email(from_="pedidos@tienda.co", to="luis@correo.com", subject="Hola", text="…"),
|
|
56
|
+
])
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Con una plantilla del panel:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
client.emails.send(
|
|
63
|
+
from_="pedidos@tienda.co",
|
|
64
|
+
to="ana@correo.com",
|
|
65
|
+
template={"id": "bienvenida", "variables": {"nombre": "Ana"}},
|
|
66
|
+
)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Reintentos e idempotencia
|
|
70
|
+
|
|
71
|
+
Cada escritura lleva una `Idempotency-Key`: la que pases o una nueva. La librería reintenta (2 veces por
|
|
72
|
+
defecto) **con la misma clave** solo cuando es seguro: Mailko no respondió, la misma clave todavía se procesa
|
|
73
|
+
(`409`), demasiadas peticiones (`429`, esperando lo que diga `Retry-After` hasta `max_retry_after`) o un error
|
|
74
|
+
de Mailko (`5xx`). Así un reintento nunca envía el correo dos veces.
|
|
75
|
+
|
|
76
|
+
Si reintentas por tu cuenta (una tarea de Celery), pasa **siempre la misma** `idempotency_key` para el mismo
|
|
77
|
+
correo, por ejemplo `f"pedido-{pedido.id}-confirmacion"`.
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
client = mailko.Mailko(
|
|
81
|
+
"mk_live_…",
|
|
82
|
+
timeout=(5, 30), # segundos: conectar, leer
|
|
83
|
+
max_retries=2,
|
|
84
|
+
max_retry_after=10, # un Retry-After más largo se lanza como RateLimitError
|
|
85
|
+
)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Errores
|
|
89
|
+
|
|
90
|
+
Todo error de Mailko trae `message` (una frase en español para quien envió), `code` (estable: es lo que debe
|
|
91
|
+
mirar tu código), `status`, `request_id` (dáselo a soporte) y, en `validation_error`, `fields`.
|
|
92
|
+
|
|
93
|
+
| Clase | Cuándo |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `MessageRejectedError` | La librería lo rechazó antes de llamar (sin destinatario, muy grande…). |
|
|
96
|
+
| `BadRequestError` | 400, 413, 415, 422: la petición está mal; corrígela. |
|
|
97
|
+
| `AuthenticationError` | 401: la llave falta, está mal, se revocó o venció. |
|
|
98
|
+
| `PaymentRequiredError` | 402: el plan o el saldo no alcanza (`insufficient_balance`…). |
|
|
99
|
+
| `PermissionDeniedError` | 403: `missing_scope`, `domain_not_verified`, `workspace_paused`… |
|
|
100
|
+
| `NotFoundError` | 404. |
|
|
101
|
+
| `ConflictError` | 409 (`confirmation_required`, `suppression_not_removable`…). |
|
|
102
|
+
| `IdempotencyError` | La clave sigue en proceso o se usó con otra petición. |
|
|
103
|
+
| `RateLimitError` | 429; `retry_after` dice cuántos segundos esperar. |
|
|
104
|
+
| `ServerError` | 5xx: problema de Mailko; reintenta con la misma clave. |
|
|
105
|
+
| `APIConnectionError` | Mailko no respondió. |
|
|
106
|
+
|
|
107
|
+
Todas heredan de `mailko.MailkoError`.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
try:
|
|
111
|
+
client.emails.send(...)
|
|
112
|
+
except mailko.PermissionDeniedError as exc:
|
|
113
|
+
if exc.code == "domain_not_verified":
|
|
114
|
+
...
|
|
115
|
+
except mailko.MailkoError as exc:
|
|
116
|
+
logger.warning("Mailko: %s", exc)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Un `202` con `"status": "suppressed"` significa que Mailko tomó la petición y no envió nada: todas las
|
|
120
|
+
direcciones están en la lista de supresión del proyecto (rebotaron o se quejaron antes).
|
|
121
|
+
|
|
122
|
+
## Webhooks
|
|
123
|
+
|
|
124
|
+
Mailko firma cada aviso en la cabecera `Mailko-Signature`. Verifica el **cuerpo crudo**, tal como llegó:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
event = mailko.construct_event(
|
|
128
|
+
request.body, # bytes, sin volver a serializar
|
|
129
|
+
request.headers.get("Mailko-Signature"),
|
|
130
|
+
"whsec_…", # o una lista: varios proyectos o una rotación
|
|
131
|
+
)
|
|
132
|
+
if event["type"] == "email.bounced":
|
|
133
|
+
email = event["data"]["object"]
|
|
134
|
+
...
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`construct_event` lanza `mailko.SignatureVerificationError` si la firma falta, no corresponde o tiene más de
|
|
138
|
+
5 minutos. Un evento puede llegar repetido: deduplica por `event["id"]`.
|
|
139
|
+
|
|
140
|
+
## Django
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
# settings.py
|
|
144
|
+
EMAIL_BACKEND = "mailko.contrib.django.EmailBackend"
|
|
145
|
+
MAILKO_API_KEY = env("MAILKO_API_KEY")
|
|
146
|
+
MAILKO_WEBHOOK_SECRET = env("MAILKO_WEBHOOK_SECRET") # whsec_…; varios separados por coma
|
|
147
|
+
|
|
148
|
+
# urls.py
|
|
149
|
+
path("mailko/", include("mailko.contrib.django.urls")), # → /mailko/webhook/
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Con `MAILERS` (Django 6.1 en adelante) es igual, y cada mailer puede llevar su propia llave:
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
MAILERS = {
|
|
156
|
+
"default": {"BACKEND": "mailko.contrib.django.EmailBackend"}, # usa MAILKO_API_KEY
|
|
157
|
+
"negocios": {"BACKEND": "mailko.contrib.django.EmailBackend", "OPTIONS": {"api_key": env("MAILKO_NEGOCIOS_KEY")}},
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
No necesita `INSTALLED_APPS` ni migraciones. Desde ahí, `send_mail`, `EmailMessage`, `EmailMultiAlternatives` y
|
|
162
|
+
cualquier librería que envíe por Django salen por Mailko: el cuerpo y su alternativa HTML, `cc`, `bcc`,
|
|
163
|
+
`reply_to`, los adjuntos y las cabeceras que Mailko permite (`List-Unsubscribe`, `References`, `In-Reply-To`…;
|
|
164
|
+
las demás se omiten, porque Mailko rechazaría el correo entero).
|
|
165
|
+
|
|
166
|
+
Lo que Django no sabe decir va como atributo del mensaje:
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
message = EmailMultiAlternatives(subject, text, "pedidos@tienda.co", ["ana@correo.com"])
|
|
170
|
+
message.attach_alternative(html, "text/html")
|
|
171
|
+
message.mailko_tags = {"pedido": "1234"}
|
|
172
|
+
message.mailko_idempotency_key = f"pedido-{pedido.id}-confirmacion" # la misma en cada reintento
|
|
173
|
+
message.mailko_stream = "marketing" # por defecto, transactional
|
|
174
|
+
message.send()
|
|
175
|
+
print(message.mailko_id, message.mailko_status)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
La `mailko_idempotency_key` nombra **un** correo: en cada reintento va con el mismo contenido (Mailko responde
|
|
179
|
+
lo mismo que la primera vez y no lo envía de nuevo). Si la misma clave llega con otro contenido, Mailko lo
|
|
180
|
+
rechaza con `IdempotencyError`, porque podría ser otro correo.
|
|
181
|
+
|
|
182
|
+
Si todas las direcciones de un mensaje están en la lista de supresión, ese mensaje no sale, los demás del lote
|
|
183
|
+
sí, y al final se lanza `mailko.SuppressedError` (salvo con `fail_silently`). Una alternativa que no sea HTML ni
|
|
184
|
+
texto (`text/calendar`, por ejemplo) se omite: la API de Mailko envía solo `html` y `text`.
|
|
185
|
+
|
|
186
|
+
### Qué pasó con cada correo
|
|
187
|
+
|
|
188
|
+
La vista del webhook verifica la firma, ignora los eventos repetidos y emite señales:
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
from django.dispatch import receiver
|
|
192
|
+
from mailko.contrib.django.signals import email_event
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
@receiver(email_event)
|
|
196
|
+
def on_mailko_email(sender, event, type, email, **kwargs):
|
|
197
|
+
pedido = email.get("tags", {}).get("pedido")
|
|
198
|
+
if type == "email.bounced" and email["event"].get("bounce_type") == "permanent":
|
|
199
|
+
...
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Si tu receptor lanza una excepción, la vista responde 500 y Mailko reenvía el evento más tarde.
|
|
203
|
+
|
|
204
|
+
### Configuración
|
|
205
|
+
|
|
206
|
+
| Variable | Qué es | Por defecto |
|
|
207
|
+
|---|---|---|
|
|
208
|
+
| `MAILKO_API_KEY` | La llave del proyecto. | — |
|
|
209
|
+
| `MAILKO_API_KEYS_BY_DOMAIN` | `{"negocios.tienda.co": "mk_live_…"}`: otro proyecto para lo que sale de ese dominio. | `{}` |
|
|
210
|
+
| `MAILKO_API_URL` | La dirección de la API. | `https://api.mailko.co` |
|
|
211
|
+
| `MAILKO_TIMEOUT` | Segundos, o `(conectar, leer)`. | `(5, 30)` |
|
|
212
|
+
| `MAILKO_MAX_RETRIES` | Reintentos dentro de un envío. | `2` |
|
|
213
|
+
| `MAILKO_MAX_RETRY_AFTER` | El `Retry-After` más largo que se espera dentro de un envío. | `10` |
|
|
214
|
+
| `MAILKO_WEBHOOK_SECRET` | `whsec_…`; una lista o separados por coma para varios proyectos. | — |
|
|
215
|
+
| `MAILKO_WEBHOOK_TOLERANCE` | Segundos que vale una firma. | `300` |
|
|
216
|
+
| `MAILKO_WEBHOOK_DEDUP_SECONDS` | Cuánto se recuerda un evento ya procesado; `0` lo apaga. Usa la caché `default` de Django: con varios procesos necesita una compartida (Redis, Memcached, base de datos), no `LocMemCache`. Aun así, deja tu receptor idempotente: dos entregas simultáneas del mismo evento pueden pasar las dos. | `86400` |
|
|
217
|
+
|
|
218
|
+
## Todo lo demás de la API
|
|
219
|
+
|
|
220
|
+
Cada recurso de `/v1` cuelga del cliente y responde el JSON de Mailko como `dict`. Las listas responden una
|
|
221
|
+
página (`{"data": [...], "pagination": {...}}`) y `list_all()` las recorre todas:
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
client.me.retrieve()
|
|
225
|
+
client.domains.create("tienda.co") # los registros DNS para publicar
|
|
226
|
+
client.domains.verify(domain_id)
|
|
227
|
+
for email in client.emails.list_all(status="bounced"):
|
|
228
|
+
...
|
|
229
|
+
client.suppressions.create("ana@correo.com", detail="Pidió no recibir más")
|
|
230
|
+
client.webhook_endpoints.create(url="https://tienda.co/mailko/webhook/", topics=["email.bounced"])
|
|
231
|
+
client.campaigns.send(campaign_id, confirm=True)
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
La referencia completa de la API está en [api.mailko.co/docs](https://api.mailko.co/docs/).
|
|
235
|
+
|
|
236
|
+
## Desarrollo
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
|
240
|
+
.venv/bin/ruff check . && .venv/bin/ruff format --check .
|
|
241
|
+
.venv/bin/pytest
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Una versión nueva se publica en PyPI sola al subir su tag (`vX.Y.Z`): ver `.github/workflows/publish.yml`.
|
|
245
|
+
|
|
246
|
+
## Licencia
|
|
247
|
+
|
|
248
|
+
MIT © Bithaus SAS.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mailko"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Librería oficial de Mailko para Python: la API /v1, la verificación de webhooks y un backend de correo para Django."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Bithaus SAS" }]
|
|
14
|
+
keywords = ["mailko", "email", "transactional", "ses", "django", "webhooks"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Framework :: Django",
|
|
25
|
+
"Framework :: Django :: 4.2",
|
|
26
|
+
"Framework :: Django :: 5.2",
|
|
27
|
+
"Topic :: Communications :: Email",
|
|
28
|
+
"Typing :: Typed",
|
|
29
|
+
]
|
|
30
|
+
dependencies = ["requests>=2.31,<3"]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
django = ["Django>=4.2"]
|
|
34
|
+
dev = ["Django>=4.2", "pytest>=8", "responses>=0.25", "ruff>=0.6", "build>=1.2"]
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://mailko.co"
|
|
38
|
+
Documentation = "https://github.com/bithaus-sas/mailko-python#readme"
|
|
39
|
+
Source = "https://github.com/bithaus-sas/mailko-python"
|
|
40
|
+
Changelog = "https://github.com/bithaus-sas/mailko-python/blob/main/CHANGELOG.md"
|
|
41
|
+
|
|
42
|
+
[tool.hatch.version]
|
|
43
|
+
path = "src/mailko/_version.py"
|
|
44
|
+
|
|
45
|
+
[tool.hatch.build.targets.wheel]
|
|
46
|
+
packages = ["src/mailko"]
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.sdist]
|
|
49
|
+
include = ["src/mailko", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
|
|
50
|
+
|
|
51
|
+
[tool.pytest.ini_options]
|
|
52
|
+
testpaths = ["tests"]
|
|
53
|
+
addopts = "-q"
|
|
54
|
+
|
|
55
|
+
[tool.ruff]
|
|
56
|
+
line-length = 120
|
|
57
|
+
target-version = "py310"
|
|
58
|
+
src = ["src", "tests"]
|
|
59
|
+
extend-exclude = ["*.md"]
|
|
60
|
+
|
|
61
|
+
[tool.ruff.lint]
|
|
62
|
+
select = ["E", "W", "F", "I", "UP", "B", "C4", "SIM", "PIE", "Q", "N"]
|
|
63
|
+
|
|
64
|
+
[tool.ruff.lint.isort]
|
|
65
|
+
known-first-party = ["mailko"]
|
|
66
|
+
|
|
67
|
+
[tool.ruff.format]
|
|
68
|
+
quote-style = "double"
|
|
69
|
+
line-ending = "lf"
|