Skip to main content
POST
/
v1
/
api
/
email
/
endpoints
Create email endpoint
curl --request POST \
  --url https://api.hq.zone/v1/api/email/endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "<string>",
  "localpart": "<string>",
  "allow_escalation": true,
  "allow_patterns": [
    "<string>"
  ],
  "category_policy": "<unknown>",
  "default_reply_lang": "<string>",
  "deliver_to": "<unknown>",
  "enabled": true,
  "instructions": "<string>",
  "max_turns_per_day": 123,
  "max_turns_per_sender_day": 123,
  "plane": "<string>",
  "reply_policy": "<string>",
  "sender_policy": "<string>",
  "spam_score_max": 123,
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "allow_escalation": true,
  "allow_patterns": [
    "<string>"
  ],
  "awaiting_review": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "enabled": true,
  "escalated": 123,
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "is_system": true,
  "kind": "<string>",
  "localpart": "<string>",
  "message_count": 123,
  "needs_attention": 123,
  "plane": "<string>",
  "received": 123,
  "replied": 123,
  "reply_languages": "<unknown>",
  "reply_policy": "<string>",
  "sender_policy": "<string>",
  "unrouted": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "category_policy": "<unknown>",
  "default_reply_lang": "<string>",
  "deliver_to": "<unknown>",
  "instructions": "<string>",
  "last_occurred_at": "2023-11-07T05:31:56Z",
  "max_turns_per_day": 123,
  "max_turns_per_sender_day": 123,
  "spam_score_max": 123
}

Authorizations

​
Authorization
string
header
required

Personal Access Token. Send as Authorization: Bearer hq_pat_....

Body

application/json

The editable behavior fields. All optional on PATCH (a full-form replace); on create, missing values fall back to the DB column defaults.

​
kind
string
required
​
localpart
string
required
​
allow_escalation
boolean | null
​
allow_patterns
string[] | null

Replaces the allowlist set wholesale when present.

​
category_policy
any
​
default_reply_lang
string | null
​
deliver_to
any
​
enabled
boolean | null
​
instructions
string | null
​
max_turns_per_day
integer<int32> | null
​
max_turns_per_sender_day
integer<int32> | null
​
plane
string | null
​
reply_policy
string | null
​
sender_policy
string | null
​
spam_score_max
number<float> | null
​
agent_id
string<uuid> | null

Response

Endpoint created

​
allow_escalation
boolean
required
​
allow_patterns
string[]
required
​
awaiting_review
integer<int64>
required
​
created_at
string<date-time>
required
​
enabled
boolean
required
​
escalated
integer<int64>
required
​
id
string<uuid>
required
​
is_system
boolean
required

True for the workspace outbound mailbox (HQ-managed): not deletable, not a normal custom inbox - the UI renders it as the workspace mailbox.

​
kind
string
required
​
localpart
string
required
​
message_count
integer<int64>
required

Total mail (in + out) attributed to this endpoint.

​
needs_attention
integer<int64>
required

Items needing a human (handling_state <> 'handled').

​
plane
string
required
​
received
integer<int64>
required

Disposition counters (E7.2): inbound received, outbound replies sent, per-state queues, and threads escalated light -> agent.

​
replied
integer<int64>
required
​
reply_languages
any
required

Reply-language distribution: { "English": 12, "Swedish": 3 }.

​
reply_policy
string
required
​
sender_policy
string
required
​
unrouted
integer<int64>
required
​
updated_at
string<date-time>
required
​
agent_id
string<uuid> | null
​
category_policy
any
​
default_reply_lang
string | null
​
deliver_to
any
​
instructions
string | null
​
last_occurred_at
string<date-time> | null
​
max_turns_per_day
integer<int32> | null
​
max_turns_per_sender_day
integer<int32> | null
​
spam_score_max
number<float> | null