Sender Identity API - Fields Reference

This article describes all fields available through the Sender Identity API. Use this as a reference when reading, creating, or updating sender identities.

---

Overview

The Sender Identity API lets you manage the sender identities in your Envoke account programmatically. Sender identities are the From name and email address combinations that appear in your contacts’ inboxes. Each account must have at least one sender identity, and exactly one identity is always designated as the default.

All endpoints require HTTP Basic Auth using your API ID and API Key.

---

Fields

Field	Type	Read-only	Required on Create	Description
id	string	Yes	—	Unique identifier assigned on creation.
name	string	No	Yes	The sender display name shown in the From field.
email	string	No	Yes	The sender email address.
is_default	boolean	Yes	—	Whether this is the account’s default sender.
dkim_status	object	—	—	DKIM verification status. Returned on create and update only.

---

Field Details

id

• Type: String
• Read-only: Yes — assigned automatically on creation.
• Example: "42"

Used to identify the sender in update, delete, and set-default requests.

---

name

• Type: String
• Read-only: No — updatable via PATCH.
• Required on create: Yes
• Constraints: Double quotes (") are not allowed.
• Example: "City of Harborview"

The display name shown in the From field of outbound emails. Choose a name your contacts will immediately recognise.

---

email

• Type: String
• Read-only: No — updatable via PATCH.
• Required on create: Yes
• Constraints: Must be a valid email address using a domain your organisation controls. Free and personal email providers are not accepted.
• Example: "communications@harborview.gov"

The email address shown in the From field. Use a domain your organisation owns for best deliverability results. Addresses from free or personal email providers will be rejected.

---

is_default

• Type: Boolean
• Read-only: Yes — managed via POST /v1/senders/{id}/default.
• Values: true or false
• Example: true

Indicates whether this sender identity is the account’s current default. Exactly one identity is always the default. Use the set default endpoint to change which identity is the default.

The very first identity you create is automatically set as the default.

---

dkim_status

• Type: Object
• Read-only: N/A — informational only.
• Returned by: Create (POST /v1/senders) and update (PATCH /v1/senders/{id}) responses. Not included in list or single-GET responses.
• Shape: { "verified": boolean, "domain": string }

Key	Type	Description
exists	boolean	true if a DKIM private key has been generated or uploaded for this domain.
verified	boolean	true if DKIM is configured and the DNS records have been verified. false if setup is incomplete.
domain	string	The domain extracted from the sender’s email address.

Example:

{
  "exists": true,
  "verified": true,
  "domain": "harborview.gov"
}

When verified is false, DKIM has not been configured for this domain. Configuring DKIM DNS records for your domain improves email deliverability and reduces the likelihood of messages being flagged as spam. Contact Envoke support if you need assistance setting up DKIM.

---

Error Responses

Validation errors (missing required fields, invalid values, etc.):

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

Not-found behaviour varies by method:

• GET /senders/{id} — when the ID is not found, returns an empty array ([]).
• PATCH /senders/{id} and DELETE /senders/{id} — when the ID is not found, returns a validation error:

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

---

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