Mail Gateway

Agregar un dominio de envío

POST /v1/mail-gateway/domains · scope mailgateway:write · reversible · idempotente

Devuelve los registros DNS que hay que publicar en la zona del dominio. Eso es lo importante de esta llamada: hasta que estén publicados y SES los vea, el dominio no verifica y no se puede enviar desde él. Cada registro trae purpose, type, host, value y status; purpose es la clave estable con la que automatizar la publicación.

La verificación es asíncrona y del lado de SES: esta llamada no espera. Consultá el estado con POST /v1/mail-gateway/domains/{domain}/verify.

Es idempotente: repetirla sobre un dominio ya dado de alta reusa el mismo par de llaves DKIM y devuelve los mismos registros, así que un reintento no invalida lo ya publicado.

curl https://api.truo.cloud/v1/mail-gateway/domains \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"ejemplo.com"}'

truo mail-gateway domain add <domain>

await truo.mailgateway.domains.create({"domain":"ejemplo.com"});

truo_mailgateway({
  "action": "domain_add"
})

operationId: mailgateway.domains.create

Quitar un dominio de envío

DELETE /v1/mail-gateway/domains/{domain} · scope mailgateway:write · destructiva — no tiene vuelta atras · idempotente

Corta el envío desde ese dominio: sale de la política del SMTP y de las keys. Los registros DNS quedan publicados en tu zona; borrarlos es cosa tuya. Volver a agregarlo genera llaves DKIM nuevas, así que el TXT viejo deja de servir.

curl https://api.truo.cloud/v1/mail-gateway/domains/ejemplo.com \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway domain remove ejemplo.com

await truo.mailgateway.domains.delete("ejemplo.com");

truo_mailgateway({
  "action": "domain_remove",
  "domain": "ejemplo.com"
})

operationId: mailgateway.domains.delete

Listar los dominios de envío

GET /v1/mail-gateway/domains · scope mailgateway:read

Cada dominio viene con los registros DNS que le corresponden y el estado de cada uno. Solo se puede enviar desde un dominio verified.

curl https://api.truo.cloud/v1/mail-gateway/domains \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway domain list

await truo.mailgateway.domains.list();

truo_mailgateway({
  "action": "domain_list"
})

operationId: mailgateway.domains.list

Consultar la verificación de un dominio

POST /v1/mail-gateway/domains/{domain}/verify · scope mailgateway:write

Consulta, no fuerza. SES revisa el DNS público por su cuenta y a su ritmo; esto lee ese resultado y actualiza el estado del dominio y el de cada registro. Que vuelva pending no es un error: significa que SES todavía no vio los registros, sea porque no propagaron o porque falta publicarlos.

Los registros dkim y mail_from_mx son los que SES verifica. spf, mail_from_spf y dmarc quedan siempre en info: mejoran la entrega, pero no hay quien los chequee.

verified_at viene en null en esta respuesta aunque el estado sea verified; el dato está en GET /v1/mail-gateway/domains.

curl https://api.truo.cloud/v1/mail-gateway/domains/ejemplo.com/verify \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway domain verify ejemplo.com

await truo.mailgateway.domains.verify("ejemplo.com");

truo_mailgateway({
  "action": "domain_verify",
  "domain": "ejemplo.com"
})

operationId: mailgateway.domains.verify

Crear una API key de envío

POST /v1/mail-gateway/keys · scope mailgateway:send · reversible · idempotente

Devuelve la key completa en secret, una sola vez: guardamos su hash, así que no hay forma de volver a mostrarla. Si se pierde, se crea otra y se revoca esta.

Esta key no sirve contra esta API: se usa en el plano de envío, POST {api_endpoint}/emails (hoy https://mg.truo.cloud/v1/emails), con Authorization: Bearer mg_live_…. El envío no pasa por api.truo.cloud a propósito: un salto de más en el camino del correo es un modo de falla de más.

Pide mailgateway:send y no mailgateway:write porque emitir esta credencial es poder enviar en nombre de la cuenta, y eso sobrevive a que revoquen la key de esta API.

curl https://api.truo.cloud/v1/mail-gateway/keys \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway key create

await truo.mailgateway.keys.create();

truo_mailgateway({
  "action": "key_create"
})

operationId: mailgateway.keys.create

Revocar una API key de envío

DELETE /v1/mail-gateway/keys/{key_id} · scope mailgateway:write · destructiva — no tiene vuelta atras · idempotente

Efecto casi inmediato: la key sale del índice del gateway. Lo que ya se aceptó, se entrega. Revocar es write y no send a propósito: quitarle capacidad de envío a la cuenta no debería exigir el scope que otorga capacidad de envío.

curl https://api.truo.cloud/v1/mail-gateway/keys/mgk3f9a2b1c4d5 \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway key revoke mgk3f9a2b1c4d5

await truo.mailgateway.keys.delete("mgk3f9a2b1c4d5");

truo_mailgateway({
  "action": "key_revoke",
  "keyId": "mgk3f9a2b1c4d5"
})

operationId: mailgateway.keys.delete

Listar las API keys de envío

GET /v1/mail-gateway/keys · scope mailgateway:read

Incluye las revocadas, para que se pueda auditar qué hubo. secret siempre es null: de la key guardamos su hash y no hay forma de recuperarla.

curl https://api.truo.cloud/v1/mail-gateway/keys \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway key list

await truo.mailgateway.keys.list();

truo_mailgateway({
  "action": "key_list"
})

operationId: mailgateway.keys.list

Listar los mensajes enviados

GET /v1/mail-gateway/messages · scope mailgateway:read

Un elemento por mensaje, del más reciente al más viejo, con el estado agregado del evento de mayor severidad que se vio (bounced gana a delivered). Se retienen 90 días.

Sin total: el backend no sabe cuántos mensajes matchean sin recorrer la historia entera, y ninguna colección de /v1 publica totales. Paginá con next_cursor.

curl https://api.truo.cloud/v1/mail-gateway/messages \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway message list

await truo.mailgateway.messages.list();

truo_mailgateway({
  "action": "message_list"
})

operationId: mailgateway.messages.list

Métricas de entrega y reputación

GET /v1/mail-gateway/metrics · scope mailgateway:read

Tasas de entrega, apertura, rebote y queja del rango, con la serie diaria, la latencia envío→entrega y el desglose por dominio. Las tasas son fracciones (0–1), no porcentajes. bounce_rate_limit y complaint_rate_limit son los umbrales de SES: cruzarlos suspende el envío para proteger la reputación compartida.

curl https://api.truo.cloud/v1/mail-gateway/metrics \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway metrics

await truo.mailgateway.metrics.get();

truo_mailgateway({
  "action": "metrics"
})

operationId: mailgateway.metrics.get

Ver la configuración SMTP

GET /v1/mail-gateway/smtp · scope mailgateway:read

Host, puerto, usuario y estado, sin la password. Es lo que hace falta para configurar o revisar un cliente de correo sin manipular el secreto. Para la password, POST /v1/mail-gateway/smtp.

curl https://api.truo.cloud/v1/mail-gateway/smtp \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway smtp get

await truo.mailgateway.smtp.get();

truo_mailgateway({
  "action": "smtp_get"
})

operationId: mailgateway.smtp.get

Revelar la password SMTP

POST /v1/mail-gateway/smtp · scope mailgateway:send

Devuelve la password SMTP en claro. Es un POST a propósito, aunque no cambie nada. El backend la expone en un GET, y un GET que devuelve un secreto queda en el historial del navegador, en la caché de cualquier proxy y en el curl de ayer. Un POST obliga a una acción deliberada, no es cacheable, y entra al audit log como mutación — que es exactamente cómo hay que poder auditar “quién sacó la clave de envío y cuándo”.

La password es recuperable (se guarda cifrada, no hasheada) porque un servidor de correo la necesita entera en cada conexión. Si la comprometieron, no alcanza con dejar de mirarla: rotala con POST /v1/mail-gateway/smtp/rotate.

curl https://api.truo.cloud/v1/mail-gateway/smtp \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway smtp reveal

await truo.mailgateway.smtp.reveal();

truo_mailgateway({
  "action": "smtp_reveal"
})

operationId: mailgateway.smtp.reveal

Rotar la credencial SMTP

POST /v1/mail-gateway/smtp/rotate · scope mailgateway:send · destructiva — no tiene vuelta atras · idempotente

Emite usuario y password nuevos y devuelve los dos. La credencial anterior queda desactivada, no borrada, para que una aplicación que todavía la tenga en memoria no se caiga en el instante de la rotación — pero dejará de funcionar, así que actualizá tus sistemas. No hay vuelta atrás: la vieja no se puede reactivar desde acá.

curl https://api.truo.cloud/v1/mail-gateway/smtp/rotate \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway smtp rotate

await truo.mailgateway.smtp.rotate();

truo_mailgateway({
  "action": "smtp_rotate"
})

operationId: mailgateway.smtp.rotate

Obtener el Mail Gateway de la cuenta

GET /v1/mail-gateway · scope mailgateway:read

No lleva id: hay un solo Mail Gateway por cuenta. Trae el estado, el uso del mes y cuántos dominios y keys hay; el detalle de cada uno tiene su propio endpoint. Si la cuenta no tiene el servicio, devuelve 404.

curl https://api.truo.cloud/v1/mail-gateway \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway get

await truo.mailgateway.tenant.get();

truo_mailgateway({
  "action": "get"
})

operationId: mailgateway.tenant.get

Uso del mes en curso

GET /v1/mail-gateway/usage · scope mailgateway:read

Envíos aceptados y rechazados del mes calendario UTC en curso. Es el número que factura. Los rechazados no se cobran: son los que el gateway frenó antes de SES.

curl https://api.truo.cloud/v1/mail-gateway/usage \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo mail-gateway usage

await truo.mailgateway.usage.get();

truo_mailgateway({
  "action": "usage"
})

operationId: mailgateway.usage.get