Subir un medio

POST /api/v1/media Sube una imagen a la biblioteca de medios de la organización. El cuerpo es multipart/form-data, no JSON: es la única familia de la referencia que recibe un archivo en lugar de un documento.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Rechazado — `403`

Una clave lleva el rol que su creador tiene en esta organización, nunca un rol en AgentsMail en sí. Consulta Claves de API.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`file`	file	Sí	La imagen. Tipos aceptados: `image/png`, `image/jpeg`, `image/webp`, `image/gif`
`folder`	string	No	Una subcarpeta de la biblioteca de medios. Solo letras minúsculas, dígitos y guiones
`compression`	string	No	`none` (por defecto), `light`, `balanced` o `strong`; consulta las Notas

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -F "file=@./logo.png" \
  -F "folder=newsletter" \
  -F "compression=balanced" \
  "https://www.agentsmail.io/api/v1/media"

Respuesta

201 Created: el medio.
400 Bad Request: falta el campo file o está vacío, compression no es uno de los cuatro valores aceptados, folder no está formado por letras minúsculas, dígitos y guiones, el tipo del archivo no es compatible, el archivo es demasiado grande, o el plan de la organización alcanzó su límite de almacenamiento de medios.
401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.
403 Forbidden: quien llama es un miembro legítimo, pero su rol es insuficiente.

Campos de la respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data.path`	string	El identificador del medio: pásalo a Eliminar un medio para borrar este archivo
`data.url`	string	URL pública: un cliente de correo nunca está autenticado
`data.name`	string	Nombre del archivo, tras la compresión si esta cambió la extensión
`data.size`	number	Tamaño del archivo en bytes, tras la compresión
`data.type`	string	Tipo MIME, tras la compresión
`data.createdAt`	string	Fecha de creación ISO
`data.folder`	string	Subcarpeta, ausente en la raíz de la biblioteca de medios

Ejemplo de respuesta

json

{
  "success": true,
  "data": {
    "path": "organizations/7c2e…/media/newsletter/logo-1703123456789.jpg",
    "url": "https://…/logo-1703123456789.jpg",
    "name": "logo-1703123456789.jpg",
    "size": 48213,
    "type": "image/jpeg",
    "createdAt": "2026-08-29T10:00:00.000Z",
    "folder": "newsletter"
  }
}

Notas

El límite que detiene las subidas es el plan de la organización, no un límite de peticiones. Cada clave ya está limitada a 120 peticiones por minuto como el resto de la API; además, un plan tiene un número máximo de archivos de medios, y alcanzarlo responde 400, no 403: es un estado que puedes resolver eliminando un medio, no un permiso que te falta.
La compresión se ejecuta en el servidor, con los mismos cuatro niveles que ofrece la pantalla de medios (light, balanced, strong y el valor por defecto none). Apunta a la misma definición y calidad que la pantalla, pero el motor que vuelve a codificar el archivo no es el mismo: espera el mismo orden de magnitud en el tamaño resultante, no un archivo idéntico byte a byte.
Un GIF animado nunca se comprime, sea cual sea el valor de compression: vuelve intacto.
La compresión nunca agranda un archivo: si volver a codificarlo no lo reduce, se guarda el archivo original en su lugar, sin aviso.
Un PNG opaco vuelve como JPEG al comprimirse: es lo que más reduce el tamaño, ya que JPEG no tiene transparencia que preservar. Un PNG con transparencia real conserva su formato y aun así se cuantiza para reducirlo (recodificación con paleta), aunque normalmente no tanto como lo haría JPEG.