PATCH/sending/identities/{identityId}

PATCH /sending/identities/{identityId}

Update a sender identity. label and fromEmail are replaced; an omitted fromName or replyToEmail keeps its current value.

View as Markdown

Request

curl -X PATCH 'https://api.sendheron.com/api/v1/sending/identities/{identityId}' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

sending:write

Path parameters

Name	Type	Required	Description
identityId	uuid	Yes	Sender identity UUID.

Body parameters

Name	Type	Required	Description
label	string	Yes	Human label shown when picking a sender, e.g. `Acme Billing`.
fromEmail	string	Yes	The From address. Its domain must already be added to this workspace, or verified in another workspace of your organization. It does not have to be verified yet, and the identity is reported as unsendable until the domain is authenticated here.
fromName	string	No	Display name recipients see beside the address.
replyToEmail	string	No	Where replies go, when that differs from the From address. Its domain does not have to be authenticated.

Responses

Returns 200 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The error code is stable and safe to branch on; description is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The error code is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.
400: emailConfig.domainNotInWorkspace: the address is on a domain this workspace has not added, and your organization has not verified it anywhere else. Add the domain first; it does not have to be verified yet.
400: emailConfig.impersonation: until your account has been reviewed, a fromName that names a well-known brand is refused. It stops applying once the account is approved.

Rate limits

100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute.