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.
@@ -0,0 +1,13 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ build/
6
+ dist/
7
+ *.egg-info/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .coverage
11
+ htmlcov/
12
+ .DS_Store
13
+ .env
@@ -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"