Hail

Originate an outbound phone call. Provide ``system_prompt`` (mode A — Hail's bundled fallback LLM uses this prompt) or ``llm`` (mode B — bring your own OpenAI-compatible endpoint as ``{"base_url": ..., "api_key": ..., "model": ...}``), or both. At least one is required. Passing both runs your prompt on your own endpoint: it receives Hail's voice preamble plus your prompt as the leading system message. ``to`` must be E.164 (e.g. ``+14155551234``). ``from_`` is optional and defaults to the first active number on your org. ``first_message`` is spoken verbatim on pickup; omit it to let the agent open the conversation itself — it reacts to how the call was answered, or introduces itself after silence. ``language`` sets the call's spoken language for speech-to-text, text-to-speech, and turn detection, as a lowercase ISO 639-1 code (e.g. ``"da"``); 39 languages are supported (server rejects others with 422); omit for English. STT provider selection is console-BYO-only (no per-call override); configure it on the organization to pin a provider. ``ai_disclosure=False`` skips the spoken "this is an AI assistant" line at the start of the call. Leave enabled unless the user has verified it is not required for this call — US artificial-voice calls (47 CFR 64.1200(b)(1)) and several AI bot-disclosure laws require it, and Hail does not verify this. The agent still identifies itself as an AI if asked. ``metadata`` is free-form JSON attached to the call record. ``tools`` are the agent tools to allow on this call. Omit for all available; pass ``[]`` to disable. ``recipient_consent`` is required: attest that you (the caller triggering this request) have obtained the lawful consent needed to contact this recipient. The API rejects the request (422) if this is not ``true`` — Hail does not verify consent for you, you are responsible for having a lawful basis (TCPA / ePrivacy / GDPR as applicable). Set ``message_type="marketing"`` for promotional calls (this additionally requires a non-empty ``consent_source`` describing how/where consent was obtained) — leave as the default ``"informational"`` for transactional/service calls. ``idempotency_key`` defaults to a fresh UUID per invocation and is returned in the response under ``idempotency_key`` — to retry *this* exact request (rather than dispatch a second call), pass the value back on the retry. A new key is a new call. Example: place_call(to="+14155551234", recipient_consent=True, system_prompt="You are scheduling a haircut.", first_message="Hi, I'm calling on behalf of Alex.") Returns the API's ``CallResponse`` as a dict (id, status, from_e164, to_e164, ...). On failure returns ``{"error": "<message>"}`` instead.

{
  "type": "object",
  "properties": {
    "to": {
      "title": "To",
      "type": "string"
    },
    "recipient_consent": {
      "title": "Recipient Consent",
      "type": "boolean"
    },
    "system_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "System Prompt"
    },
    "llm": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Llm"
    },
    "from_": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From"
    },
    "first_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "First Message"
    },
    "language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Language"
    },
    "ai_disclosure": {
      "default": true,
      "title": "Ai Disclosure",
      "type": "boolean"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metadata"
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tools"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "consent_source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Consent Source"
    },
    "consent_obtained_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Consent Obtained At"
    },
    "message_type": {
      "default": "informational",
      "title": "Message Type",
      "type": "string"
    }
  },
  "required": [
    "to",
    "recipient_consent"
  ],
  "title": "place_call_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "place_call_toolDictOutput"
}

Send an outbound email through your configured SES sender. ``to`` is a non-empty list of RFC-style email addresses. At least one of ``body_text`` / ``body_html`` is required (both is fine — multipart-alternative). Prefer including ``body_html``: open and click tracking only works for emails with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. ``cc``, ``bcc``, and ``reply_to`` are optional and follow the usual mail conventions. Hail sets no ``reply_to`` of its own — to have replies reach the human running this session, call ``whoami`` and pass their ``email``. ``recipient_consent`` is required: attest that you (the caller triggering this request) have obtained the lawful consent needed to email this recipient. The API rejects the request (422) if this is not ``true`` — Hail does not verify consent for you. Set ``message_type="marketing"`` for promotional email (this additionally requires a non-empty ``consent_source`` describing how/where consent was obtained) — leave as the default ``"informational"`` for transactional/service email. ``from_`` is optional only while the workspace has one verified sender identity. With several, omitting it returns 422 listing them — call ``list_email_domains`` and pass one. With none, the server auto-mints a per-org hail-mail address of the form ``<user>+<org>@<base>`` if the operator configured ``HAIL_MAIL_BASE_DOMAIN`` (the ``<org>`` part is derived from your organization id; the ``<user>`` part comes from ``HAIL_MAIL_FROM`` / ``HAIL_MAIL_DEFAULT_USER_PREFIX``, or an explicit row created via ``POST /email-domains``). When supplied, ``from_`` must match a verified row already in ``email_domains`` (register one with the website console or ``POST /email-domains``). ``from_name`` is an optional display name rendered on the From: header ("Acme Billing <[email protected]>"). Control characters are rejected. ``metadata`` is free-form JSON attached to the email record. ``idempotency_key`` defaults to a fresh UUID and is returned in the response under ``idempotency_key`` — pass the same value on a retry to replay rather than re-send. A new key is a new message. ``attachment_ids`` are ids returned by ``upload_email_attachment`` — upload a file first, then pass its id(s) here to attach it. Example: send_email(to=["[email protected]"], subject="Welcome", recipient_consent=True, body_text="Thanks for signing up.") Returns the ``EmailResponse`` dict (id, status, from_address, to_addresses, sent_at, provider_message_id, ...). On failure returns ``{"error": "<message>"}`` instead.

{
  "type": "object",
  "properties": {
    "to": {
      "items": {
        "type": "string"
      },
      "title": "To",
      "type": "array"
    },
    "subject": {
      "title": "Subject",
      "type": "string"
    },
    "recipient_consent": {
      "title": "Recipient Consent",
      "type": "boolean"
    },
    "body_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Body Text"
    },
    "body_html": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Body Html"
    },
    "from_": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From"
    },
    "from_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Name"
    },
    "cc": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cc"
    },
    "bcc": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Bcc"
    },
    "reply_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Reply To"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metadata"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "consent_source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Consent Source"
    },
    "consent_obtained_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Consent Obtained At"
    },
    "message_type": {
      "default": "informational",
      "title": "Message Type",
      "type": "string"
    },
    "attachment_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Attachment Ids"
    }
  },
  "required": [
    "to",
    "subject",
    "recipient_consent"
  ],
  "title": "send_email_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "send_email_toolDictOutput"
}

Upload a file to attach to a future outbound email. ``content_base64`` is the file's raw bytes, base64-encoded. Returns ``{"id": ..., "filename": ..., "content_type": ..., "size_bytes": ...}`` — pass ``id`` in ``send_email``'s ``attachment_ids`` list. The id is reusable across many sends and expires in 24h if never used. Files over 25MB (combined with the message body and any other attachments, per send) are rejected — host large files externally and link to them in the body instead.

{
  "type": "object",
  "properties": {
    "content_base64": {
      "title": "Content Base64",
      "type": "string"
    },
    "filename": {
      "title": "Filename",
      "type": "string"
    },
    "content_type": {
      "title": "Content Type",
      "type": "string"
    }
  },
  "required": [
    "content_base64",
    "filename",
    "content_type"
  ],
  "title": "upload_email_attachment_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "upload_email_attachment_toolDictOutput"
}

Fetch the current state of one call by id. Use this after ``place_call`` (or to check on any prior call) to read the call's latest ``status`` and timing fields. Returns the API's ``CallResponse`` as a dict, or ``{"error": "call not found"}`` for an unknown id.

{
  "type": "object",
  "properties": {
    "call_id": {
      "title": "Call Id",
      "type": "string"
    }
  },
  "required": [
    "call_id"
  ],
  "title": "get_call_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_call_toolDictOutput"
}

List recent calls in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. ``status`` (one of queued, dialing, ringing, in_progress, completed, failed, busy, no_answer, canceled) and ``to`` (E.164) are optional server-side filters. Returns a dict ``{"items": [...], "next_cursor": <str|None>}``.

{
  "type": "object",
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To"
    }
  },
  "title": "list_calls_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "list_calls_toolDictOutput"
}

Send an outbound SMS. ``to`` must be E.164 (e.g. ``+14155551234``). ``body`` is the message text. With no ``from_``: UK (+44) and Germany (+49) destinations use your organization's sender ID (or ``HAIL``, the platform default); Australia (+61) always uses ``HAIL``; every other destination uses your organization's oldest active SMS-capable number and the API returns 422 when there is none. SMS never uses the shared voice-call pool. ``recipient_consent`` is required: attest that you (the caller triggering this request) have obtained the lawful consent needed to text this recipient. The API rejects the request (422) if this is not ``true`` — Hail does not verify consent for you. Set ``message_type="marketing"`` for promotional texts (this additionally requires a non-empty ``consent_source``) — leave as the default ``"informational"`` for transactional/service texts. ``idempotency_key`` defaults to a fresh UUID and is returned in the response under ``idempotency_key`` — pass the same value on a retry to replay rather than re-send. Example: send_sms(to="+14155551234", body="Your order shipped!", recipient_consent=True) Returns the ``SmsResponse`` dict (id, status, from_e164, to_e164, segment_count, ...). On failure returns ``{"error": "<message>"}`` instead.

{
  "type": "object",
  "properties": {
    "to": {
      "title": "To",
      "type": "string"
    },
    "body": {
      "title": "Body",
      "type": "string"
    },
    "recipient_consent": {
      "title": "Recipient Consent",
      "type": "boolean"
    },
    "from_": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metadata"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "consent_source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Consent Source"
    },
    "consent_obtained_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Consent Obtained At"
    },
    "message_type": {
      "default": "informational",
      "title": "Message Type",
      "type": "string"
    }
  },
  "required": [
    "to",
    "body",
    "recipient_consent"
  ],
  "title": "send_sms_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "send_sms_toolDictOutput"
}

Fetch the current state of one SMS by id. Use this after ``send_sms`` to check delivery status. Example: get_sms(sms_id="...")

{
  "type": "object",
  "properties": {
    "sms_id": {
      "title": "Sms Id",
      "type": "string"
    }
  },
  "required": [
    "sms_id"
  ],
  "title": "get_sms_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_sms_toolDictOutput"
}

Page through recent SMS messages for your organization. ``status`` filters to one of: queued, sent, delivered, failed, undelivered, received. ``to`` filters to messages sent to a specific E.164 number. Paginate with the returned ``next_cursor``.

{
  "type": "object",
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To"
    }
  },
  "title": "list_sms_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "list_sms_toolDictOutput"
}

Fetch the full record of one email by id. Returns the complete row — including ``body_text`` / ``body_html`` and (for inbound mail) the ``in_reply_to`` / ``message_id`` headers and ``spam``/``virus``/``spf``/``dkim``/``dmarc`` verdicts. Use this after ``list_emails`` to read a received reply's body. Returns the API's ``EmailResponse`` as a dict, or ``{"error": "resource not found"}`` for an unknown id.

{
  "type": "object",
  "properties": {
    "email_id": {
      "title": "Email Id",
      "type": "string"
    }
  },
  "required": [
    "email_id"
  ],
  "title": "get_email_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_email_toolDictOutput"
}

List emails in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. Two optional server-side filters: * ``direction`` — ``outbound`` or ``inbound``. Pass ``direction="inbound"`` to read replies and other received mail. * ``status`` — one of ``queued``, ``sent``, ``failed``, ``bounced``, ``complained``, ``received``. Items are trimmed summaries (no message body). Call ``get_email`` with an item's ``id`` to read the full body. Example: list_emails(direction="inbound") Returns ``{"items": [...], "next_cursor": <str|None>}`` on success, or ``{"error": "<message>"}`` instead.

{
  "type": "object",
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "direction": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Direction"
    }
  },
  "title": "list_emails_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "list_emails_toolDictOutput"
}

Get a fetchable URL for an email's original MIME source. Returns ``{"url": "<presigned-s3-url>"}`` — a short-lived (~5 minute) link to the full raw RFC822 message. Fetch the URL directly to read the complete original; it needs no auth header. Raw source exists for **inbound** mail only — outbound ids return ``{"error": "resource not found"}``.

{
  "type": "object",
  "properties": {
    "email_id": {
      "title": "Email Id",
      "type": "string"
    }
  },
  "required": [
    "email_id"
  ],
  "title": "get_email_raw_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_email_raw_toolDictOutput"
}

Get a fetchable URL for one inbound email attachment. ``attachment_id`` comes from an item in ``get_email``'s ``attachments`` list. Returns ``{"url": "<presigned-s3-url>"}`` — a short-lived (~5 minute) link to the attachment bytes, fetchable directly with no auth header. Unknown ids return ``{"error": "resource not found"}``.

{
  "type": "object",
  "properties": {
    "email_id": {
      "title": "Email Id",
      "type": "string"
    },
    "attachment_id": {
      "title": "Attachment Id",
      "type": "string"
    }
  },
  "required": [
    "email_id",
    "attachment_id"
  ],
  "title": "get_email_attachment_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_email_attachment_toolDictOutput"
}

Delivery/engagement timeline (sent→delivered→opened…) for one email. Chronological lifecycle events for a single email — use this to see exactly what happened to one message (bounced? opened? clicked?) rather than the account-wide aggregates ``get_email_stats`` returns. Returns ``{"items": [...], "next_cursor": ...}`` where each item has ``kind`` (one of sent, delivered, delivery_delayed, bounced, complained, rejected, opened, clicked), ``payload``, and ``occurred_at``. ``opened`` and ``clicked`` only occur for emails sent with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. Pass ``cursor`` from a previous ``next_cursor`` to page (``limit`` 1..1000, default 100). On failure returns ``{"error": "resource not found"}`` for an unknown id.

{
  "type": "object",
  "properties": {
    "email_id": {
      "title": "Email Id",
      "type": "string"
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Limit"
    }
  },
  "required": [
    "email_id"
  ],
  "title": "get_email_events_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_email_events_toolDictOutput"
}

Account-level email deliverability stats (counts, rates, time series). Aggregates across your whole organization's outbound mail over a window — use this for "how's deliverability doing" rather than one message's history (``get_email_events`` covers that). ``from_`` / ``to`` are ISO 8601 timestamps (defaults: last 7 days ending now). ``bucket`` is ``"day"`` (default) or ``"hour"`` — ``"hour"`` is limited to an 8-day span; any range is capped at 92 days. Returns ``{"from": ..., "to": ..., "bucket": ..., "totals": {...}, "rates": {...}, "series": [...]}`` — ``totals``/each ``series`` bucket carry counts (sent, delivered, bounced, opened, ...) and ``rates`` carries derived ratios (delivery, bounce, open, click), each ``None`` when ``totals.sent`` is 0. Open and click numbers only count HTML emails. Plain-text-only emails are never tracked for opens or clicks, so they lower those rates. On failure returns ``{"error": "<message>"}`` instead.

{
  "type": "object",
  "properties": {
    "from_": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From"
    },
    "to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To"
    },
    "bucket": {
      "default": "day",
      "title": "Bucket",
      "type": "string"
    }
  },
  "title": "get_email_stats_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_email_stats_toolDictOutput"
}

Page through events from across the org or one resource. Pass ``id="<type>:<uuid>"`` to narrow to a single resource — supported types are ``call``, ``email``, and ``sms`` (e.g. ``id="sms:<uuid>"`` after ``send_sms``). When narrowed to a call, the response includes a ``call_status`` field reflecting the call's current state. Without ``id``, returns events from across the whole org. ``kind`` filters server-side by event kind (``state_change``, ``agent_turn``, ``user_turn``, ``tool_call``, ``error``, ...). This is **not** a streaming subscription — the call returns whatever events exist now plus a ``next_cursor`` if more pages remain. To follow a call to completion, loop: pass the previous response's ``next_cursor`` until ``next_cursor`` is null and, when narrowed to a call, ``call_status`` is one of ``completed``, ``failed``, ``busy``, ``no_answer``, ``canceled`` (the terminal set). Example: get_events(id="call:0c2f...-...", limit=200) Returns ``{"items": [...], "next_cursor": <str|None>, "call_status": <str|None>}`` on success, or ``{"error": ...}`` on a malformed ``id`` or upstream failure.

{
  "type": "object",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Kind"
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "default": 100,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "get_events_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_events_toolDictOutput"
}

List the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use ``lookup_contact`` for name searches. ``q`` optionally filters server-side (matches name/email/phone). ``limit`` caps the page (server default 100, max 500). Returns ``{"items": [{"id", "kind", "name", "phone_e164", "email", "role"}, ...]}`` — ``kind`` is ``"member"`` (id ``member:<user_id>``, ``role`` set) or ``"manual"`` (id is the contact's UUID, ``role`` null).

{
  "type": "object",
  "properties": {
    "q": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Q"
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Limit"
    }
  },
  "title": "list_contacts_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "list_contacts_toolDictOutput"
}

Find a contact by name, email, or phone fragment. Resolve a person to their ``phone_e164``/``email`` BEFORE calling ``place_call``, ``send_sms``, or ``send_email`` — do not guess a contact's number. Returns up to 10 matches, same item shape as ``list_contacts``. Example: lookup_contact(query="maya")

{
  "type": "object",
  "properties": {
    "query": {
      "title": "Query",
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "title": "lookup_contact_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "lookup_contact_toolDictOutput"
}

List the addresses this workspace can send email from. Call this BEFORE ``send_email`` when you do not already know the ``from_`` address — do not guess a domain. Returns ``{"items": [...], "next_cursor": ..., "default_from": ...}``. Each item carries ``domain``, ``kind`` (``"custom"`` or ``"hail_mail"``) and ``verification_status``; only ``"verified"`` rows can send. A ``custom`` item's ``domain`` is a bare DNS name that accepts any local-part (``[email protected]``); a ``hail_mail`` item's ``domain`` is already a full address. ``default_from`` is the address a ``send_email`` with no ``from_`` goes out as. It is null when the workspace has several verified identities — then ``send_email`` rejects a missing ``from_`` and you must pass one from ``items``. Example: list_email_domains()

{
  "type": "object",
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Limit"
    }
  },
  "title": "list_email_domains_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "list_email_domains_toolDictOutput"
}

Identify the human whose credentials this session runs under. Use it to sign or route mail as that person: pass their address as ``send_email(reply_to=...)`` so replies reach them rather than the sending domain, which is often an unattended ``noreply@``. Returns ``{"auth_kind", "organization_id", "user_id", "email", "name"}``. ``user_id``/``email``/``name`` are null when the server runs on a shared operator key (``auth_kind="shared"``) — there is no human behind it, so send without a ``reply_to``. Example: whoami()

{
  "type": "object",
  "properties": {},
  "title": "whoami_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "whoami_toolDictOutput"
}

Save a new contact for the workspace. Provide at least one of ``phone_e164`` (E.164, e.g. ``+14155551234``) or ``email`` — the API rejects (422) a contact with neither. A duplicate phone or email on an existing contact returns 409. Example: create_contact(name="Maya Chen", phone_e164="+14155551234") Returns the created contact entry as a dict. On failure returns ``{"error": "<message>"}`` instead.

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "phone_e164": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Phone E164"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Email"
    }
  },
  "required": [
    "name"
  ],
  "title": "create_contact_toolArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "create_contact_toolDictOutput"
}