Añadir una dirección de remitente

POST /api/v1/settings/identities Añade una dirección a la libreta. Requiere el rol Admin. La dirección debe estar en un dominio que esta organización haya verificado y probado: no un dominio que otro verificó, ni uno que todavía se está verificando. Una dirección en un dominio no probado es exactamente el aspecto de un intento de suplantación.

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.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`senderEmail`	string	sí	La dirección que añadir, en un dominio verificado tuyo
`senderName`	string	no	Nombre visible que se muestra delante
`isDefault`	boolean	no	`true` la promueve como la dirección que firma

Ejemplo

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"

Respuesta

201 Created: el recurso creado.
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.
429 Too Many Requests: más de 120 peticiones en un minuto para esta clave.

Campos de la respuesta

201 con la dirección creada.

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data.id`	string	Identificador que pasar como `sendingIdentityId` en una campaña
`data.senderEmail`	string	La dirección
`data.senderName`	string \	null
`data.isDefault`	boolean	Si firma por defecto
`data.createdAt`	string	Fecha de creación ISO

Ejemplo de respuesta

json

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