Téléverser un média

POST /api/v1/media Téléverse une image dans la médiathèque de l'organisation. Le corps est en multipart/form-data, pas en JSON — c'est la seule famille de la référence qui reçoit un fichier plutôt qu'un document.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Refusé — `403`

Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Corps de la requête

Champ	Type	Obligatoire	Description
`file`	file	Oui	L'image. Types acceptés : `image/png`, `image/jpeg`, `image/webp`, `image/gif`
`folder`	string	Non	Un sous-dossier de la médiathèque. Lettres minuscules, chiffres et tirets uniquement
`compression`	string	Non	`none` (par défaut), `light`, `balanced` ou `strong` — voir les remarques

Exemple

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"

Réponse

201 Created — le média.
400 Bad Request — le champ file est absent ou vide, compression ne fait pas partie des quatre valeurs acceptées, folder ne se compose pas de lettres minuscules, de chiffres et de tirets, le type du fichier n'est pas pris en charge, le fichier est trop volumineux, ou l'offre de l'organisation a atteint sa limite de stockage de médias.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
403 Forbidden — l'appelant est bien membre, mais son rôle est insuffisant.

Champs de la réponse

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.path`	string	L'identifiant du média — passez-le à Supprimer un média pour retirer ce fichier
`data.url`	string	URL publique — un client de messagerie n'est jamais authentifié
`data.name`	string	Nom du fichier, après compression si celle-ci en a changé l'extension
`data.size`	number	Taille du fichier en octets, après compression
`data.type`	string	Type MIME, après compression
`data.createdAt`	string	Date de création ISO
`data.folder`	string	Sous-dossier, absent à la racine de la médiathèque

Exemple de réponse

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"
  }
}

Remarques

La limite qui bloque les téléversements est l'offre de l'organisation, pas une limite de débit. Chaque clé est déjà plafonnée à 120 requêtes par minute comme le reste de l'API ; en plus de cela, une offre a un nombre maximal de fichiers médias, et l'atteindre répond 400, pas 403 — c'est un état que vous pouvez résoudre en supprimant un média, pas une permission qui vous manque.
La compression s'exécute sur le serveur, avec les quatre mêmes niveaux que ceux de l'écran Médias (light, balanced, strong, et none par défaut). Elle vise la même définition et la même qualité que l'écran, mais le moteur qui réencode le fichier n'est pas le même — attendez-vous au même ordre de grandeur pour la taille obtenue, pas à un fichier identique à l'octet près.
Un GIF animé n'est jamais compressé, quelle que soit la valeur de compression — il revient intact.
La compression n'agrandit jamais un fichier : si le réencodage ne le réduit pas, c'est le fichier d'origine qui est stocké, sans avertissement.
Un PNG opaque revient en JPEG une fois compressé — c'est ce qui réduit le plus la taille, puisque le JPEG n'a aucune transparence à préserver. Un PNG réellement transparent garde son format et est tout de même quantifié pour le réduire (réencodage par palette), en général moins fortement que ne le ferait le JPEG.