Proveedores de email

Generado desde DialerDigital/core commit 0fc18008b3c8 — especificación openapi/dialer-v1.yaml v0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.

English version

Traducción en curso

Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.

Registro de proveedores de email por tenant/región (SMTP / log).

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/email/providers`	Registro de proveedores de email
`POST`	`/v1/email/providers`	Registrar un proveedor de email
`GET`	`/v1/email/providers/{id}`	Obtener un proveedor de email
`PATCH`	`/v1/email/providers/{id}`	Actualizar un proveedor de email (alcance inmutable)
`POST`	`/v1/email/providers/{id}/retire`	Retirar un proveedor de email (las filas nunca se borran)

Registro de proveedores de email

http

GET /v1/email/providers

Respuestas

`200`

Filas propias + filas heredadas de toda la empresa.

Campo	Tipo	Obligatorio	Descripción
`email_providers`	arreglo de EmailProvider	sí
`email_providers[].id`	string (uuid)	no
`email_providers[].account_id`	string (uuid)	no
`email_providers[].tenant_id`	string (uuid) \| null	no	`null` = proveedor de toda la empresa, heredado por cada sede.
`email_providers[].scope`	`empresa` · `sede`	no	Derivado de `tenant_id`.
`email_providers[].adapter`	`smtp` · `log`	no
`email_providers[].region`	`us` · `mx` · `eu`	no
`email_providers[].name`	string	no
`email_providers[].from_address`	string	no
`email_providers[].host`	string	no
`email_providers[].port`	integer	no
`email_providers[].username`	string	no
`email_providers[].has_secret`	boolean	no	El secreto SMTP NUNCA viaja por el cable: esta es la única señal de que hay una credencial almacenada.
`email_providers[].has_webhook_secret`	boolean	no	La clave de firma de eventos NUNCA viaja por el cable: esta es la única señal de que hay una almacenada.
`email_providers[].status`	`active` · `disabled` · `retired`	no
`email_providers[].created_at`	string (date-time)	no
`email_providers[].updated_at`	string (date-time)	no

`401` — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`429` — ApiKeyRateLimited

Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Registrar un proveedor de email

http

POST /v1/email/providers

Mismas convenciones que /v1/sms/providers: scope: "empresa" crea una fila de toda la cuenta y necesita un account_admin (un member o una clave de máquina recibe 403); account_id/tenant_id se inyectan desde la sesión. smtp necesita host (un nombre DNS o un literal IPv4 que pase la protección SSRF, que se vuelve a comprobar en cada envío), port 465 o 587, username y secret. secret es SOLO DE ESCRITURA: las respuestas llevan has_secret/has_webhook_secret, nunca los secretos. El adaptador log se rechaza salvo que el despliegue lo permita. No hay proveedor de respaldo: un tenant sin ninguna fila activa no envía. Solo se retira: no existe ruta DELETE.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`adapter`	`smtp` · `log`	sí
`region`	`us` · `mx` · `eu`	sí
`name`	string	sí
`from_address`	string (email)	sí
`host`	string	no
`port`	`465` · `587`	no
`username`	string	no
`secret`	string	no	Solo de escritura. Contraseña SMTP.
`webhook_secret`	string	no	Solo de escritura. Clave HMAC de los eventos firmados del proveedor; las respuestas llevan `has_webhook_secret`.
`status`	`active` · `disabled` · `retired`	no
`scope`	`sede` · `empresa`	no	Campo solo de petición; las respuestas lo derivan de `tenant_id`.

json

{
  "adapter": "smtp",
  "region": "us",
  "name": "example-email-provider",
  "from_address": "[email protected]",
  "host": "smtp.example.com",
  "port": 587,
  "username": "example-user",
  "secret": "example-smtp-password-not-a-real-one"
}

Respuestas

`201`

Proveedor registrado (has_secret, nunca el secreto).

Campo	Tipo	Obligatorio	Descripción
`email_provider`	object (EmailProvider)	sí
`email_provider.id`	string (uuid)	no
`email_provider.account_id`	string (uuid)	no
`email_provider.tenant_id`	string (uuid) \| null	no	`null` = proveedor de toda la empresa, heredado por cada sede.
`email_provider.scope`	`empresa` · `sede`	no	Derivado de `tenant_id`.
`email_provider.adapter`	`smtp` · `log`	no
`email_provider.region`	`us` · `mx` · `eu`	no
`email_provider.name`	string	no
`email_provider.from_address`	string	no
`email_provider.host`	string	no
`email_provider.port`	integer	no
`email_provider.username`	string	no
`email_provider.has_secret`	boolean	no	El secreto SMTP NUNCA viaja por el cable: esta es la única señal de que hay una credencial almacenada.
`email_provider.has_webhook_secret`	boolean	no	La clave de firma de eventos NUNCA viaja por el cable: esta es la única señal de que hay una almacenada.
`email_provider.status`	`active` · `disabled` · `retired`	no
`email_provider.created_at`	string (date-time)	no
`email_provider.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Obtener un proveedor de email

http

GET /v1/email/providers/{id}

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

El proveedor.

Campo	Tipo	Obligatorio	Descripción
`email_provider`	object (EmailProvider)	sí
`email_provider.id`	string (uuid)	no
`email_provider.account_id`	string (uuid)	no
`email_provider.tenant_id`	string (uuid) \| null	no	`null` = proveedor de toda la empresa, heredado por cada sede.
`email_provider.scope`	`empresa` · `sede`	no	Derivado de `tenant_id`.
`email_provider.adapter`	`smtp` · `log`	no
`email_provider.region`	`us` · `mx` · `eu`	no
`email_provider.name`	string	no
`email_provider.from_address`	string	no
`email_provider.host`	string	no
`email_provider.port`	integer	no
`email_provider.username`	string	no
`email_provider.has_secret`	boolean	no	El secreto SMTP NUNCA viaja por el cable: esta es la única señal de que hay una credencial almacenada.
`email_provider.has_webhook_secret`	boolean	no	La clave de firma de eventos NUNCA viaja por el cable: esta es la única señal de que hay una almacenada.
`email_provider.status`	`active` · `disabled` · `retired`	no
`email_provider.created_at`	string (date-time)	no
`email_provider.updated_at`	string (date-time)	no

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Actualizar un proveedor de email (alcance inmutable)

http

PATCH /v1/email/providers/{id}

Editar una fila de toda la empresa requiere una sesión account_admin, igual que crearla. Una fila retirada es terminal. scope no se acepta aquí: da 400.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`adapter`	`smtp` · `log`	no
`region`	`us` · `mx` · `eu`	no
`name`	string	no
`from_address`	string (email)	no
`host`	string	no
`port`	`465` · `587`	no
`username`	string	no
`secret`	string	no	Solo de escritura.
`webhook_secret`	string,null	no	Solo de escritura. Un valor nuevo rota la clave; `null` o una cadena vacía la borra, de modo que la fila deja de aceptar eventos.
`status`	`active` · `disabled` · `retired`	no

json

{
  "name": "postman-email-renamed",
  "status": "disabled"
}

Respuestas

`200`

Proveedor actualizado.

Campo	Tipo	Obligatorio	Descripción
`email_provider`	object (EmailProvider)	sí
`email_provider.id`	string (uuid)	no
`email_provider.account_id`	string (uuid)	no
`email_provider.tenant_id`	string (uuid) \| null	no	`null` = proveedor de toda la empresa, heredado por cada sede.
`email_provider.scope`	`empresa` · `sede`	no	Derivado de `tenant_id`.
`email_provider.adapter`	`smtp` · `log`	no
`email_provider.region`	`us` · `mx` · `eu`	no
`email_provider.name`	string	no
`email_provider.from_address`	string	no
`email_provider.host`	string	no
`email_provider.port`	integer	no
`email_provider.username`	string	no
`email_provider.has_secret`	boolean	no	El secreto SMTP NUNCA viaja por el cable: esta es la única señal de que hay una credencial almacenada.
`email_provider.has_webhook_secret`	boolean	no	La clave de firma de eventos NUNCA viaja por el cable: esta es la única señal de que hay una almacenada.
`email_provider.status`	`active` · `disabled` · `retired`	no
`email_provider.created_at`	string (date-time)	no
`email_provider.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Retirar un proveedor de email (las filas nunca se borran)

http

POST /v1/email/providers/{id}/retire

Retirar una fila de toda la empresa requiere una sesión account_admin.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

El proveedor retirado.

Campo	Tipo	Obligatorio	Descripción
`email_provider`	object (EmailProvider)	sí
`email_provider.id`	string (uuid)	no
`email_provider.account_id`	string (uuid)	no
`email_provider.tenant_id`	string (uuid) \| null	no	`null` = proveedor de toda la empresa, heredado por cada sede.
`email_provider.scope`	`empresa` · `sede`	no	Derivado de `tenant_id`.
`email_provider.adapter`	`smtp` · `log`	no
`email_provider.region`	`us` · `mx` · `eu`	no
`email_provider.name`	string	no
`email_provider.from_address`	string	no
`email_provider.host`	string	no
`email_provider.port`	integer	no
`email_provider.username`	string	no
`email_provider.has_secret`	boolean	no	El secreto SMTP NUNCA viaja por el cable: esta es la única señal de que hay una credencial almacenada.
`email_provider.has_webhook_secret`	boolean	no	La clave de firma de eventos NUNCA viaja por el cable: esta es la única señal de que hay una almacenada.
`email_provider.status`	`active` · `disabled` · `retired`	no
`email_provider.created_at`	string (date-time)	no
`email_provider.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Proveedores de email ​

Endpoints ​

Registro de proveedores de email ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Registrar un proveedor de email ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Obtener un proveedor de email ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Actualizar un proveedor de email (alcance inmutable) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Retirar un proveedor de email (las filas nunca se borran) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Proveedores de email

Endpoints

Registro de proveedores de email

`200`

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Registrar un proveedor de email

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Obtener un proveedor de email

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Actualizar un proveedor de email (alcance inmutable)

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

Retirar un proveedor de email (las filas nunca se borran)

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited