---
title: "Ask for effects on a task"
method: POST
path: "/api/assistant/tasks/{id}/effects"
tags: ["Mailzero Assistant"]
---

# Ask for effects on a task

`POST /api/assistant/tasks/{id}/effects`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/assistant/tasks/{id}/effects`
- Auth: HTTP bearer

The assignee asks for one or more effects (reply, forward, label, snooze, resolve, note, request). The delegation's level decides the kinds allowed and the grants cap them: inside the grants at guarded_send or operate (and the inward kinds at triage) the effects run at once with their receipts; at draft they wait for the owner's approval; a failed grant escalates to the owner; a kind the level does not allow is refused. The owner's own request runs at once. The same idempotency key answers the first plan again. Requires `assistant:write`.

## Path parameters

- `id` string, required

## Request body

- object
  - `effects` AssistantEffect[], required
    - `kind` 'reply' | 'forward' | 'label' | 'snooze' | 'resolve' | 'note' | 'request', required
    - `mailbox_id` string: reply, forward, label: the mailbox of the message
    - `reply_to_message_id` string: reply: the message answered
    - `message_id` string: forward: the message forwarded
    - `message_ids` string[]: label: the messages; the matter's source message by default
    - `to` string[]: reply, forward: the recipients
    - `cc` string[]
    - `body` string: reply: the text
    - `expected_reply` object, nullable: reply: what the matter then waits for
      - `description` string
      - `due_at` string, date-time, nullable
    - `note` string, nullable: forward: a line above the forwarded mail
    - `add` string[]: label: labels added
    - `remove` string[]: label: labels removed
    - `set` string[]: label: the whole new set
    - `until` string, date-time: snooze: until when
    - `reason` string, nullable: resolve: why
    - `text` string: note: the line added to the matter's story
    - `url` string: request: the endpoint called with the matter's envelope
    - `payload` object: request: what travels with the envelope
  - `idempotency_key` string, required
  - `note` string: What the assignee wants the owner to know about this request

## Response `200`

The plan, and what ran

- object
  - `task_id` string, required
  - `replayed` boolean, required
  - `plan` AssistantPlan, required: An action plan: the effects asked for, who asked at which level, what the grant check said, and where it stands
    - `id` string, required
    - `status` 'proposed' | 'approved' | 'executing' | 'executed' | 'failed' | 'escalated' | 'rejected' | 'stale' | 'expired', required
    - `requires_approval` boolean, required
    - `requested_by` string, required: assistant, user:<id>, agent:<slug> or member:<id>
    - `level` 'observe' | 'triage' | 'draft' | 'guarded_send' | 'operate', required
    - `rule_id` string, nullable
    - `grant_check` AssistantGrantCheck: The verdict of the validation order for one request: the level, the recipients, the volume, the schedule, the spend, the risk classes of the matter, the required approver
      - `outcome` 'allowed' | 'escalate' | 'approval' | 'rejected', required
      - `effects` object[], required
        - `kind` string, required
        - `check` object, required
          - `outcome` 'allowed' | 'escalate' | 'approval' | 'rejected', required
          - `checks` object[], required
            - `name` 'level' | 'recipients' | 'volume' | 'schedule' | 'spend' | 'risk' | 'approver', required
            - `passed` boolean, required
            - `why` string, required
          - `risk_classes` string[], required
      - `usage` object, required
        - `effects_today` integer, required
        - `spend_today_usd` number, required
    - `effects` AssistantEffect[], required
      - `kind` 'reply' | 'forward' | 'label' | 'snooze' | 'resolve' | 'note' | 'request', required
      - `mailbox_id` string: reply, forward, label: the mailbox of the message
      - `reply_to_message_id` string: reply: the message answered
      - `message_id` string: forward: the message forwarded
      - `message_ids` string[]: label: the messages; the matter's source message by default
      - `to` string[]: reply, forward: the recipients
      - `cc` string[]
      - `body` string: reply: the text
      - `expected_reply` object, nullable: reply: what the matter then waits for
        - `description` string
        - `due_at` string, date-time, nullable
      - `note` string, nullable: forward: a line above the forwarded mail
      - `add` string[]: label: labels added
      - `remove` string[]: label: labels removed
      - `set` string[]: label: the whole new set
      - `until` string, date-time: snooze: until when
      - `reason` string, nullable: resolve: why
      - `text` string: note: the line added to the matter's story
      - `url` string: request: the endpoint called with the matter's envelope
      - `payload` object: request: what travels with the envelope
    - `hash` string
    - `source_revision` integer
    - `receipt_id` string, nullable
    - `expires_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `execution` object, nullable
    - `status` string
    - `executed` integer
    - `skipped` integer
    - `receipt_ids` string[]
    - `reason` string, nullable
  - `lease` AssistantTaskLease
    - `holder` string, required: agent:<slug>, member:<id> or user:<id>
    - `expires_at` string, date-time, required
  - `hint` string, required

## Other responses

- `400`: Invalid effects
- `401`: Missing or invalid API key
- `403`: The matter is not handed to the caller
- `404`: No such task in the caller's scope
- `409`: Another assignee holds the lease
- `429`: Rate limit exceeded - wait and retry

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)