Cuentas de envío

Una cuenta define credenciales, remitente y restricciones para entregar correo. Todos los endpoints requieren un access token OpenID Connect.

Endpoints

Método	Ruta	Éxito
GET	/api/v1/smtp-accounts	200 OK
POST	/api/v1/smtp-accounts	201 Created
GET	/api/v1/smtp-accounts/{id}	200 OK
PUT	/api/v1/smtp-accounts/{id}	200 OK
DELETE	/api/v1/smtp-accounts/{id}	204 No Content
POST	/api/v1/smtp-accounts/{id}/test	200 OK

Campos de escritura

Campo	Tipo	Requerido	Proveedor	Descripción
label	string	Sí	Ambos	Nombre interno de la cuenta.
provider	string	No	Ambos	smtp por defecto o http_api.
from_address	string	Sí	Ambos	Dirección remitente.
from_name	string	No	Ambos	Nombre predeterminado del remitente.
is_default	boolean	No	Ambos	Selecciona la cuenta cuando una notificación omite su ID.
trusted_domains	string[]	No	Ambos	Dominios permitidos de destinatarios. Vacío = sin restricción.
api_allowed_domains	string[]	No	Ambos	Hosts permitidos en Origin/Referer. Vacío = sin restricción.
host	string	Sí	SMTP	Host del servidor.
port	integer	Sí	SMTP	Entre 1 y 65535.
username	string	No	SMTP	Usuario SMTP.
password	string	Al crear	SMTP	Se cifra y nunca se devuelve. Vacío en PUT conserva el existente.
encryption	string	Sí	SMTP	none, starttls o tls.
endpoint	string	Sí	HTTP	URL que empieza por http:// o https://.
auth_header_name	string	No	HTTP	Header que transporta la credencial.
auth_value_template	string	No	HTTP	Predeterminado al enviar: {{.APIKey}}.
body_template	string	Sí	HTTP	Go template que debe producir el JSON del proveedor.
api_key	string	Al crear	HTTP	Se cifra y nunca se devuelve. Vacío en PUT conserva la existente.

Proveedor HTTP no habilitado

Los campos marcados como HTTP se documentan como referencia del contrato, pero la integración http_api no está habilitada actualmente. Usa provider: "smtp".

Los dominios se recortan, convierten a minúsculas y deduplican. Deben ser nombres desnudos como example.com: no admiten esquema, @, rutas, espacios ni dominios de una sola etiqueta.

Crear una cuenta SMTP

curl -X POST https://notify.summitexplorerjd.ec/api/v1/smtp-accounts \
  -H "Authorization: Bearer $OIDC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Cuenta principal",
    "provider": "smtp",
    "host": "smtp.example.com",
    "port": 587,
    "username": "notificaciones@example.com",
    "password": "YOUR_SMTP_PASSWORD",
    "encryption": "starttls",
    "from_address": "notificaciones@example.com",
    "from_name": "Mi Empresa",
    "is_default": true,
    "trusted_domains": ["example.com"],
    "api_allowed_domains": ["app.example.com"]
  }'

La primera cuenta creada se convierte automáticamente en predeterminada, aunque is_default sea false. Marcar otra cuenta como predeterminada desmarca la anterior.

Proveedor HTTP (no habilitado)

El siguiente payload es únicamente una referencia técnica. No intentes utilizarlo mientras la integración permanezca no habilitada.

curl -X POST https://notify.summitexplorerjd.ec/api/v1/smtp-accounts \
  -H "Authorization: Bearer $OIDC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "SMTP2GO",
    "provider": "http_api",
    "endpoint": "https://api.smtp2go.com/v3/email/send",
    "auth_header_name": "X-Smtp2go-Api-Key",
    "auth_value_template": "{{.APIKey}}",
    "api_key": "YOUR_PROVIDER_API_KEY",
    "body_template": "{\"sender\": {{.From | json}}, \"to\": [{{.To | json}}], \"subject\": {{.Subject | json}}, \"text_body\": {{.Body | json}}}",
    "from_address": "notificaciones@example.com",
    "from_name": "Mi Empresa"
  }'

body_template y auth_value_template se analizan al guardar. El resultado del body se envía como application/json; el cliente HTTP tiene un timeout de 15 segundos y solo considera exitosos los estados 2xx.

Datos de template HTTP

Variable	Tipo	Contenido
{{.To}}	string	Destinatario principal.
{{.CC}}	string[]	Destinatarios CC.
{{.BCC}}	string[]	Destinatarios CCO.
{{.Subject}}	string	Asunto final.
{{.Body}}	string	Cuerpo final.
{{.BodyType}}	string	text o html.
{{.From}}	string	from_address.
{{.FromName}}	string	Nombre efectivo de la notificación/cuenta.
{{.APIKey}}	string	API key descifrada durante el envío.

El helper json serializa cadenas y listas: {{.Subject | json}}, {{.CC | json}}. Las cuentas existentes no envían CC/CCO por HTTP a menos que su template use esas variables en los campos apropiados del proveedor.

Esquema de respuesta

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "label": "Cuenta principal",
  "provider": "smtp",
  "host": "smtp.example.com",
  "port": 587,
  "username": "notificaciones@example.com",
  "encryption": "starttls",
  "from_address": "notificaciones@example.com",
  "from_name": "Mi Empresa",
  "is_default": true,
  "trusted_domains": ["example.com"],
  "api_allowed_domains": ["app.example.com"],
  "created_at": "2026-08-03T14:00:00Z",
  "updated_at": "2026-08-03T14:00:00Z"
}

Los campos del proveedor no utilizado se omiten. password y api_key nunca aparecen. GET de colección devuelve un arreglo con este esquema.

Obtener, actualizar y eliminar

GET /{id} devuelve la cuenta o 404. Un ID no UUID devuelve 400.

PUT /{id} valida el objeto completo, no aplica un patch parcial. Debes reenviar todos los campos necesarios del proveedor. Únicamente el secreto puede quedar vacío para conservar el valor almacenado.

DELETE /{id} responde 204 sin cuerpo. Las notificaciones que referencian una cuenta eliminada conservan su historial, pero los envíos pendientes ya no podrán resolver sus credenciales.

Probar una cuenta

curl -X POST https://notify.summitexplorerjd.ec/api/v1/smtp-accounts/ACCOUNT_ID/test \
  -H "Authorization: Bearer $OIDC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"destinatario@example.com"}'

El body es opcional. Sin recipient, envía a from_address. Esta operación no entra en la cola: intenta entregar inmediatamente con un timeout global de 20 segundos.

Éxito:

{"status":"sent"}

Un fallo del proveedor devuelve 502 con failed to send test email y el detalle disponible.

Errores principales

Estado	Causa
400	JSON/ID inválido, campo desconocido o validación de campos/templates.
404	Cuenta inexistente o perteneciente a otro usuario.
500	Fallo de persistencia/cifrado.
502	Fallo del envío de prueba.