---
title: "Archive an agent"
method: DELETE
path: "/v1/agents/{id}"
tags: ["Agents"]
---

# Archive an agent

`DELETE /v1/agents/{id}`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/agents/{id}`
- Auth: HTTP bearer

**Requires scope:** `manage`. Soft-deletes the agent (sets status to `archived`). The address is retained and cannot be reused, and archiving cannot be undone. The agent sends nothing more; mail that reaches it is still received, stored and sent to your webhooks as before, so none is lost. A pause by our abuse-prevention system or for the agent's bounce or complaint rate stays as its `pause_reason`; one for the workspace's bounce or complaint rate stays until the hourly check finds that rate recovered, and then reads `archived_via_api`. A test key cannot archive an agent that has a live key tied to it, live mail (sent, scheduled or received) or a draft a live key made (403 `live_mode_required`).

## Path parameters

- `id` string, required

## Response `200`

The archived agent.

- object
  - `id` string, required: Id of the archived agent (`agt_…`), also when the path named it by name.
  - `status` 'archived', required: Always `archived`. The agent's address stays taken and cannot be given to a new agent.
  - `archived_at` string, date-time, required: The time of this call. It is not kept on the agent, so archiving an archived agent again returns a new time.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `409`: Conflict — duplicate resource, an in-progress idempotent request, a draft or scheduled message that started sending while it was being changed, or a thread deleted for good while one of its messages is being sent (`duplicate_resource`); or an agent name more than one agent has (`agent_name_conflict`: use the agent's id); or a status change on an archived agent, since archiving cannot be undone (`agent_archived`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)