Update sign-up settings

PATCH /api/v1/settings/optin Double opt-in and the confirmation email. Admin role required. The organization setting alone controls new sign-ups. Enabled: pending with a confirmation email. Disabled: subscribed without confirmation. The contact API accepts the legacy doubleOptIn boolean but ignores it, whether true or false.

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
`required`	boolean	no	`true`: new sign-ups are `pending` with confirmation; `false`: `subscribed` without confirmation
`subject`	string	no	Subject of the confirmation email
`content`	string	no	Its HTML — rejected without `{{confirmationUrl}}`

json

{"required": true}

Example

bash

curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"required": true}' \
  "https://www.agentsmail.io/api/v1/settings/optin"

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

Response fields

Content identical to the default is stored as empty, so the organization keeps inheriting future improvements to it. That is what customized tells you.

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.required`	boolean	Whether confirmation is now demanded
`data.subject`	string	The subject in force
`data.content`	string	The HTML in force
`data.customized`	boolean	`false` means both are still the product defaults

Example response