Editar o promover una dirección

PATCH /api/v1/settings/identities/{identityId} Cambia una dirección o su nombre visible, o la promueve como predeterminada de la organización. Requiere el rol Admin.

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.

Parámetros de ruta

Parámetro	Tipo	Descripción
`identityId`	string	Obligatorio. La dirección que se modifica

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`senderEmail`	string	no	Dirección nueva: la misma regla de dominio que al añadir una
`senderName`	string	no	Nombre visible nuevo
`isDefault`	boolean	no	`true` la promueve. `false` se rechaza: promueve otra dirección en su lugar

Ejemplo

bash

curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isDefault": true}' \
  "https://www.agentsmail.io/api/v1/settings/identities/$IDENTITY_ID"

Respuesta

200 OK: la llamada tuvo éxito.
400 Bad Request: la validación falló; details lleva los problemas campo por campo.
401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.
403 Forbidden: el propietario de la clave es member de la organización, no admin.
404 Not Found: no existe ese recurso, o pertenece a otra organización. La API nunca confirma que un id existe a quien no tiene derecho sobre él.
429 Too Many Requests: más de 120 peticiones en un minuto para esta clave.

Campos de la respuesta

La dirección tras el cambio, con la misma forma que la libreta de direcciones.

Hay exactamente una dirección predeterminada. Promover una dirección degrada a la anterior en la misma operación: nunca tienes que quitarla primero.

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data.id`	string	Sin cambios
`data.senderEmail`	string	La dirección
`data.senderName`	string \	null
`data.isDefault`	boolean	`true` si esta llamada la promovió
`data.createdAt`	string	Fecha de creación ISO

Ejemplo de respuesta

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "senderEmail": "hello@mail.example.com",
    "senderName": "Example",
    "isDefault": true,
    "createdAt": "2026-08-23T10:22:05.000Z"
  }
}