Ajouter une adresse d'expéditeur

POST /api/v1/settings/identities Ajoute une adresse au carnet. Rôle admin requis. L'adresse doit se trouver sur un domaine que cette organisation a vérifié et prouvé — pas un domaine vérifié par quelqu'un d'autre, pas un domaine encore en cours de vérification. Une adresse sur un domaine non prouvé, c'est exactement à cela que ressemble une tentative d'usurpation.

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.

Corps de la requête

Champ	Type	Obligatoire	Description
`senderEmail`	string	oui	L'adresse à ajouter, sur l'un de vos domaines vérifiés
`senderName`	string	non	Nom affiché devant elle
`isDefault`	boolean	non	`true` la promeut comme adresse qui signe

Exemple

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"senderEmail": "news@mail.example.com", "senderName": "Example News"}' \
  "https://www.agentsmail.io/api/v1/settings/identities"

Réponse

201 Created — la ressource créée.
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.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

201 avec l'adresse créée.

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.id`	string	Identifiant à passer comme `sendingIdentityId` sur une campagne
`data.senderEmail`	string	L'adresse
`data.senderName`	string \	null
`data.isDefault`	boolean	Si elle signe par défaut
`data.createdAt`	string	Date de création ISO

Exemple de réponse

json

{
  "success": true,
  "data": {"id": "2ad9…", "senderEmail": "news@mail.example.com", "senderName": "Example News", "isDefault": false, "createdAt": "2026-08-23T10:22:05.000Z"}
}