# Sender Identity API - Insert

Use this endpoint to create a new sender identity in your account.

---

## Endpoint

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

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Sender display name shown in the From field. Double quotes (`"`) are not allowed. |
| `email` | string | Yes | Sender email address. Must use a domain your organisation controls. |

Free and personal email providers are not accepted as sender email addresses. Use a domain your organisation owns.

---

## Response

On success, the API returns the newly created sender identity:

```json
{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "1",
    "name": "City of Harborview",
    "email": "communications@harborview.gov",
    "is_default": true,
    "dkim_status": {
      "exists": true,
      "verified": true,
      "domain": "harborview.gov"
    }
  }
}
```

`result_data.id` is the Envoke sender ID. Store this to use in update, delete, and set-default requests.

`result_data.is_default` will be `true` if this is the first sender identity in your account — the first identity created is automatically set as the default.

`result_data.dkim_status.verified` indicates whether DKIM is configured for this domain. If `false`, configure DKIM DNS records for your domain to improve email deliverability.

---

## Validation Errors

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "The field 'name' is required"
    ]
  }
}
```

Common validation errors:

| Error | Cause |
|---|---|
| `Request body may not be empty` | No JSON body was provided. |
| `The field 'name' is required` | `name` was missing or blank. |
| `Email is required` | `email` was missing or blank. |
| `Email address is not valid` | The value in `email` is not a valid email address 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 email provider. |
| `A sender with this name and email already exists` | A sender with the same name and email combination already exists in your account. |

---

## Examples

### Create the primary sender identity

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "City of Harborview", "email": "communications@harborview.gov"}' \
  "$BASE/v1/senders"
```

### Create a department sender

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Parks & Recreation", "email": "parks@harborview.gov"}' \
  "$BASE/v1/senders"
```

### Create a second department sender

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Planning Department", "email": "planning@harborview.gov"}' \
  "$BASE/v1/senders"
```

---

*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).*