# 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`:

```json
{
  "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:**

```bash
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:**

```bash
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:**

```bash
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:

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

If the sender ID is not found:

```json
{
  "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:**

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

**To confirm the change, read back the updated sender:**

```bash
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](https://developers.envoke.com).*