# Sender Identity API - Read

Use the read endpoints to retrieve sender identities for your account. You can list all identities with filtering and pagination, or retrieve a single identity by ID.

---

## Endpoints

| Method | URL | Description |
|---|---|---|
| GET | `https://e1.envoke.com/v1/senders` | Return a list of sender identities. |
| GET | `https://e1.envoke.com/v1/senders/{ID}` | Return a single sender identity. |

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

---

## List Sender Identities

```
GET https://e1.envoke.com/v1/senders
```

Returns a JSON array of sender identities for your account, sorted alphabetically by name by default. Supports filtering, sorting, pagination, and field selection.

### Query Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | integer | `10` | Maximum number of results to return. Hard cap is `100` unless `?fields=` or `?result_type=kvp` is also set (see note below). |
| `skip` | integer | `0` | Number of records to skip. Use with `limit` to paginate. |
| `fields` | string | *(all)* | Comma-separated list of fields to include in each result. See limit note below. |
| `result_type` | string | *(array)* | Set to `kvp` to receive results as a key-value object (`{ "id": "name" }`). See limit note below. |
| `filter[id]` | string | — | Filter by sender ID. |
| `filter[name]` | string | — | Filter by sender display name. |
| `filter[email]` | string | — | Filter by sender email address. |
| `filter[is_default]` | string | — | Filter by default status. Use `1` for the default sender, `0` for non-default senders. |
| `sort[name]` | string | — | Sort by sender display name. Value: `asc` or `desc`. |
| `sort[email]` | string | — | Sort by sender email address. Value: `asc` or `desc`. |

**Note — limit behaviour with `?fields=` and `?result_type=kvp`:** When either of these parameters is present, the default limit increases to 10,000 (returning all records if no explicit limit is specified) and a `?limit=` value above 100 is honoured as-is. This allows full exports and dropdown population without pagination.

### Filter Operators

All `filter[field]` parameters support the following operators:

| Operator | Example | Description |
|---|---|---|
| *(none)* | `?filter[name]=City+of+Harborview` | Exact match |
| `(ne)` | `?filter[name][(ne)]=City+of+Harborview` | Not equal |

*Note: URL-encode brackets in production requests (e.g. `%5B` for `[`).*

### Response

A JSON array of sender identity objects. Returns an empty array (`[]`) if no identities match.

```json
[
  {
    "id": "1",
    "name": "City of Harborview",
    "email": "communications@harborview.gov",
    "is_default": true
  },
  {
    "id": "2",
    "name": "Parks & Recreation",
    "email": "parks@harborview.gov",
    "is_default": false
  }
]
```

Note: `dkim_status` is not included in list responses. It is only returned on create and update.

---

## Get a Single Sender Identity

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

Returns a single sender identity object. Replace `{ID}` with the Envoke sender ID.

If the ID is not found, the API returns an empty array (`[]`).

### Response

```json
{
  "id": "1",
  "name": "City of Harborview",
  "email": "communications@harborview.gov",
  "is_default": true
}
```

---

## Examples

### Return all sender identities (default pagination)

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

### Get a single sender by ID

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/senders/1"
```

### Filter to find the default sender

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?filter%5Bis_default%5D=1"
```

### Filter by email address

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?filter%5Bemail%5D=communications%40harborview.gov"
```

### Filter by name (exact match)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?filter%5Bname%5D=Parks+%26+Recreation"
```

### Sort by name descending

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?sort%5Bname%5D=desc"
```

### Sort by email ascending

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?sort%5Bemail%5D=asc"
```

### Return only specific fields

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?fields=id,name,email"
```

### Return as a key-value map (for dropdowns)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?result_type=kvp"
```

Response:

```json
{ "1": "City of Harborview", "2": "Parks & Recreation" }
```

### Paginate through results

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/senders?limit=5&skip=5"
```

---

*Note: The curl examples above are formatted for readability. URL-encode brackets in production requests (e.g. `%5B` for `[`, `%5D` for `]`).*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*