Skip to content

Runbook: Cartero — operations

Field Value
Service Cartero
Owner Alquemis (DRI) — original author Olger Ávila (IT)
Last verified 2026-07-16 — transcribed from the repo README; not yet independently re-run by Athanor.

Purpose

Day-to-day operation of the Cartero email service: running the microservice, sending a test, rotating the Entra app secret, and diagnosing send failures.

Prerequisites

  • Access to the host running Cartero (office Windows host, C:\Trabajo\cartero) — IT-managed.
  • Python 3 + the project virtualenv (pip install -r requirements.txt).
  • The app secret available either as CARTERO_CLIENT_SECRET (in .env) or via Key Vault access (managed identity on Azure, or a dev / service-principal identity on-prem).
  • For secret rotation: Entra admin on the app registration + write access to the Generales Key Vault (cartero-smtp-client-secret).

Steps

Run the microservice

cd C:\Trabajo\cartero
.\venv\Scripts\Activate.ps1
python mail_service.py          # listens on 0.0.0.0:8182

For production, run it under a process manager / Windows service (NSSM), the same pattern as the other office services.

Send a test email

Library smoke test:

python enviar_prueba.py                  # default recipient
python enviar_prueba.py someone@dom.com  # specific recipient

Or over HTTP:

curl -X POST http://localhost:8182/send -H "Content-Type: application/json" `
  -d '{"to":"someone@dom.com","subject":"Test","body":"hello from cartero"}'

Rotate the client secret

  1. Entra ID → the Cartero app registration → Certificates & secrets → create a new client secret; copy the value.
  2. Update the secret store: set cartero-smtp-client-secret in the Generales Key Vault to the new value (or update CARTERO_CLIENT_SECRET in .env if not using Key Vault).
  3. Restart the service so it picks up the new secret.
  4. Send a test (above) to confirm delivery.
  5. Once the new secret is confirmed working, delete the old one in Entra.

Verification

  • GET http://localhost:8182/health returns {"ok": true, ...} with the expected sender (cartero@alquemis.com) and reply_to.
  • A test send returns {"ok": true} and the mail arrives.
  • Token role check: the diagnostic one-liner in the repo README prints the access token's roles (should include the SMTP send role); empty roles → SMTP.SendAsApp admin consent is missing or still propagating.

Troubleshooting

Symptom Likely cause
Token has no roles / 535 5.7.3 missing SMTP.SendAsApp admin consent (or still propagating)
Auth rechazada (334) service principal lacks FullAccess / SendAs on the mailbox
535 ... SMTP AUTH disabled SmtpClientAuthenticationDisabled on the mailbox or organization
Hangs on connect firewall / proxy blocking smtp.office365.com:587

Rollback

  • Bad deploy: restore the previous code and restart the service.
  • Bad secret rotation: re-point Key Vault / .env to the previous (still-valid) secret and restart. Don't delete the old Entra secret until the new one is confirmed working.

Contacts

Alquemis (DRI). Original author Olger Ávila (IT) — escalate to him for the Entra app registration, SMTP.SendAsApp admin consent, mailbox permissions, and Key Vault access.