Modifier ou promouvoir une adresse

PATCH /api/v1/settings/identities/{identityId} Change une adresse ou son nom affiché, ou la promeut comme adresse par défaut de l'organisation. Rôle admin requis.

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.

Paramètres de chemin

Paramètre	Type	Description
`identityId`	string	Obligatoire. L'adresse à modifier

Corps de la requête

Champ	Type	Obligatoire	Description
`senderEmail`	string	non	Nouvelle adresse — même règle de domaine qu'à l'ajout
`senderName`	string	non	Nouveau nom affiché
`isDefault`	boolean	non	`true` la promeut. `false` est refusé : promouvez plutôt une autre adresse

Exemple

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"

Réponse

200 OK — l'appel a réussi.
400 Bad Request — la validation a échoué ; details porte les erreurs champ par champ.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
404 Not Found — aucune ressource de ce type, ou elle appartient à une autre organisation. L'API ne confirme jamais qu'un identifiant existe à un appelant qui n'y a pas droit.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

L'adresse après la modification, même forme que dans le carnet d'adresses.

Il y a exactement une adresse par défaut. Promouvoir une adresse rétrograde la précédente dans la même opération — vous n'avez jamais à la retirer d'abord.

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.id`	string	Inchangé
`data.senderEmail`	string	L'adresse
`data.senderName`	string \	null
`data.isDefault`	boolean	`true` si cet appel l'a promue
`data.createdAt`	string	Date de création ISO

Exemple de réponse

json

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