Sender Identity API - Update

Use these endpoints to update an existing sender identity or change the account’s default sender.

Endpoints

Method	URL	Description
PATCH	`https://e1.envoke.com/v1/senders/{ID}`	Update the name and/or email of a sender identity.
POST	`https://e1.envoke.com/v1/senders/{ID}/default`	Set a sender identity as the account’s default.

Authentication is via HTTP Basic Auth using your API ID and API Key.

Update a Sender Identity

PATCH https://e1.envoke.com/v1/senders/{ID}

Replace {ID} with the Envoke sender ID you want to update. The request body must be JSON.

Request Body

At least one field must be provided.

Field	Type	Description
`name`	string	Updated sender display name. Double quotes (`"`) are not allowed.
`email`	string	Updated sender email address. Must use a domain your organisation controls.

id and is_default are read-only and cannot be updated via PATCH. To change the default sender, use POST /v1/senders/{ID}/default (see below).

If id is included in the request body, it must match the {ID} in the URL. If they differ, a validation error is returned: "Provided 'id': {url_id} does not match 'id' in request body ({body_id})".

Response

On success, the API returns the updated sender identity including dkim_status:

{
  "success": true,
  "result_text": "Updated",
  "result_data": {
    "id": "2",
    "name": "Parks & Recreation",
    "email": "parks@harborview.gov",
    "is_default": false,
    "dkim_status": {
      "verified": true,
      "domain": "harborview.gov"
    }
  }
}

dkim_status.verified reflects the DKIM state for the sender’s domain after the update. If you changed the email field to use a different domain, this indicates whether the new domain has DKIM configured.

Validation Errors

Common errors:

Error	Cause
`Request body may not be empty`	No JSON body was provided.
`Item with id '42' not found`	The `{ID}` in the URL does not match any sender in your account.
`Provided 'id': {url_id} does not match 'id' in request body ({body_id})`	`id` in the request body differs from `{ID}` in the URL.
`The field 'name' is required`	`name` was provided but is blank or whitespace only.
`Email is required`	`email` was provided but is blank.
`Email address is not valid`	The value in `email` is not a valid email format.
`Double quotes are not allowed in the from name field`	The `name` value contains a `"` character.
`Double quotes are not allowed in the email field`	The `email` value contains a `"` character.
`Third party email providers such as gmail.com, yahoo.com, etc. cannot be used as senders`	The email address uses a free or personal provider.
`A sender with this name and email already exists`	Another sender in your account already has this name and email combination.

Examples

Update the name only:

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Office of Communications"}' \
  "$BASE/v1/senders/1"

Update the email only:

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "info@harborview.gov"}' \
  "$BASE/v1/senders/1"

Update both name and email:

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Office of Communications", "email": "info@harborview.gov"}' \
  "$BASE/v1/senders/1"

Set the Default Sender

POST https://e1.envoke.com/v1/senders/{ID}/default

Promotes the specified sender identity to be the account’s default. Replace {ID} with the sender ID to promote.

The default sender is used automatically when no sender is explicitly specified in a campaign. Exactly one identity is always the default — when you promote a new identity, the previous default is automatically demoted.

This endpoint requires no request body.

Response

On success:

{
  "success": true,
  "result_text": "Updated",
  "result_data": []
}

If the sender ID is not found:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Item with id '42' not found"]
  }
}

Example

Set a department sender as the default:

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders/2/default"

To confirm the change, read back the updated sender:

curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/senders/2"

Expected: is_default is true.

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.