Add a sender address

POST /api/v1/settings/identities Adds an address to the book. Admin role required. The address must sit on a domain this organization has verified and proved — not a domain someone else verified, not one still being verified. An address on an unproven domain is exactly what a spoofing attempt looks like.

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.

Request body

Field	Type	Required	Description
`senderEmail`	string	yes	The address to add, on a verified domain of yours
`senderName`	string	no	Display name shown in front of it
`isDefault`	boolean	no	`true` promotes it as the address that signs

Example

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"

Response

201 Created — the created resource.
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.
429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

201 with the created address.

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.id`	string	Identifier to pass as `sendingIdentityId` on a campaign
`data.senderEmail`	string	The address
`data.senderName`	string \	null
`data.isDefault`	boolean	Whether it signs by default
`data.createdAt`	string	ISO creation date

Example response

json

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