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:

{
  "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

{
  "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

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

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

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.