Schedule task email - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

This endpoint may send immediately. A future send_at queues a scheduled outbox delivery; an omitted time sends now for a standalone task, or uses the sequence working window for a sequence task. The response is an outbox receipt, not just a task status. Sending requires an active enrollment where applicable, a usable recipient email, an authorized connected mailbox, resolved template variables, and provider readiness.

Path parameters

task_idrequired
string
Task ID.

Name	Type	Description
task_idrequired	string	Task ID.

Query parameters

actorUserId · optional
string
Optional actor override.

Name	Type	Description
actorUserId	string	Optional actor override.

Body parameters

send_at · optional
string (ISO datetime)
Optional send time. Omitted means send now for a standalone task; sequence tasks use the sequence schedule window.
provider · optional
string
Optional gmail or microsoft provider override.
provider_account_email · optional
string
Optional authorized sender mailbox address.
subject · optional
string
Optional subject override.
body_text · optional
string
Optional plain-text body override.
body_html · optional
string
Optional HTML body override.
body_format · optional
string
auto, text, html, or both (both is Gmail-only); defaults to auto.
thread_ref · optional
object
Optional thread reference.
context_tags · optional
array<object>
Optional send context tags.
attachments · optional
array<object>
Optional attachment descriptors.

Name	Type	Description
send_at	string (ISO datetime)	Optional send time. Omitted means send now for a standalone task; sequence tasks use the sequence schedule window.
provider	string	Optional gmail or microsoft provider override.
provider_account_email	string	Optional authorized sender mailbox address.
subject	string	Optional subject override.
body_text	string	Optional plain-text body override.
body_html	string	Optional HTML body override.
body_format	string	auto, text, html, or both (both is Gmail-only); defaults to auto.
thread_ref	object	Optional thread reference.
context_tags	array<object>	Optional send context tags.
attachments	array<object>	Optional attachment descriptors.

Errors

Status	Meaning
400	Invalid payload or actor.
401	Invalid API key or missing auth.
403	Missing tasks:write scope.
404	Task or lead not found.
409	Task requires an action, sender unavailable, sequence enrollment inactive, or template variables unresolved.

Example

bash

curl -X POST "https://app.autotouch.ai/api/task-queue/67c4d064b4dd8f2d4999f611/email/schedule?actorUserId=<USER_ID>" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{"send_at":"2030-03-04T15:30:00Z"}'

Request body

json

{
    "send_at": "2030-03-04T15:30:00Z",
    "body_text": "Hi Ada, following up.",
    "body_format": "text"
  }

Response example

json

{
    "success": true,
    "task_id": "67c4d064b4dd8f2d4999f611",
    "outbox_id": "67c4d064b4dd8f2d4999f612",
    "outbox_status": "scheduled",
    "queued_for_send": true,
    "send_at": "2030-03-04T15:30:00Z",
    "outbox": { "outbox_id": "67c4d064b4dd8f2d4999f612", "status": "scheduled", "send_at": "2030-03-04T15:30:00Z" },
    "task_completion": null,
    "task_state": null
  }