Delete a media

DELETE /api/v1/media Removes a media from the library. A media has no id of its own — its identity is the path returned by Upload a media and List media, which is why it travels as a query parameter here instead of a path segment.

Authorization

Role in the organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERRefused — 403
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Query parameters

ParameterTypeDescription
pathstringRequired. The path of the media, as returned by upload or listing

Example

bash
curl -X DELETE -H "x-api-key: $AGENTMAIL_API_KEY" \
  --data-urlencode "path=organizations/7c2e…/media/newsletter/logo-1703123456789.jpg" \
  -G "https://www.agentsmail.io/api/v1/media"

Response

  • 200 OK — the call succeeded.
  • 400 Bad Request — the path query parameter is missing.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 403 Forbidden — the caller is a legitimate member, but their role is too low.
  • 404 Not Found — the path does not belong to the organization of the key. The API never confirms that a path exists to a caller who has no right to it.

Response fields

FieldTypeDescription
successbooleanIndicates if the operation was successful
data.deletedbooleantrue when the media is gone

Example response

json
{"success": true, "data": {"deleted": true}}

Notes

  • Deleting is definitive — there is no trash or recovery.
  • A media still referenced by a template or campaign's HTML is deleted anyway: the reference is not checked, and the <img> tag will simply break for future opens.

Related