Edit or promote an address

PATCH /api/v1/settings/identities/{identityId} Changes an address or its display name, or promotes it as the organization default. Admin role required.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Path parameters

Parameter	Type	Description
`identityId`	string	Required. The address to change

Request body

Field	Type	Required	Description
`senderEmail`	string	no	New address — same domain rule as when adding one
`senderName`	string	no	New display name
`isDefault`	boolean	no	`true` promotes it. `false` is refused: promote another address instead

Example

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"

Response

200 OK — the call succeeded.
400 Bad Request — validation failed; details carries the field-level issues.
401 Unauthorized — missing or invalid key, or its owner left the organization.
403 Forbidden — the key's owner is a member of the organization, not an admin.
404 Not Found — no such resource, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.
429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

The address after the change, same shape as the address book.

There is exactly one default. Promoting an address demotes the previous one in the same operation — you never have to clear it first.

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.id`	string	Unchanged
`data.senderEmail`	string	The address
`data.senderName`	string \	null
`data.isDefault`	boolean	`true` if this call promoted it
`data.createdAt`	string	ISO creation date

Example response

json

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