Connection check
verified live · 27h ago
hail-mcp
Phone, SMS & email for AI agents — one remote MCP endpoint, OAuth login, zero install.
Tools
20
GitHub stars
—
Installs / wk
—
Licence
—
Transport
streamable-http
Last checked
27h ago
Tools & capabilities
20 toolsRead from the running server on 27h ago.
create_contact
name*emailphone_e164
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 neit… 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.
get_call
call_id*
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.… 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.
get_email
email_id*
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… 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.
get_email_attachment
email_id*attachment_id*
Get a fetchable URL for one inbound email attachment. ``attachment_id`` comes from an item in ``get_email``'s ``attachments`` list. Returns ``{"url": "<presigned-s… 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"}``.
get_email_events
limitcursoremail_id*
Delivery/engagement timeline (sent→delivered→opened…) for one email. Chronological lifecycle events for a single email — use this to see exactly what happened to o… 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.
get_email_raw
email_id*
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.… 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"}``.
get_email_stats
tofrom_bucket
Account-level email deliverability stats (counts, rates, time series). Aggregates across your whole organization's outbound mail over a window — use this for "how'… 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.
get_events
idkindlimitcursor
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… 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.
get_sms
sms_id*
Fetch the current state of one SMS by id. Use this after ``send_sms`` to check delivery status. Example: get_sms(sms_id="...") Fetch the current state of one SMS by id. Use this after ``send_sms`` to check delivery status. Example: get_sms(sms_id="...")
list_calls
tolimitcursorstatus
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 que… 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>}``.
list_contacts
qlimit
List the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use ``lookup_contact`` for name searches. ``q`` optionally filter… 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).
list_email_domains
limitcursor
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.… 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()
list_emails
limitcursorstatusdirection
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 fil… 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.
list_sms
tolimitcursorstatus
Page through recent SMS messages for your organization. ``status`` filters to one of: queued, sent, delivered, failed, undelivered, received. ``to`` filters to mes… 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``.
lookup_contact
query*
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``… 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")
place_call
to*llmfrom_toolslanguagemetadata
+8
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 Ope… 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.
send_email
ccto*bccfrom_subject*metadata
+10
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`` i… 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.
send_sms
to*body*from_metadatamessage_typeconsent_source
+3
Send an outbound SMS from your organization's dedicated number. ``to`` must be E.164 (e.g. ``+14155551234``). ``body`` is the message text. SMS requires a dedicate… Send an outbound SMS from your organization's dedicated number. ``to`` must be E.164 (e.g. ``+14155551234``). ``body`` is the message text. SMS requires a dedicated phone number on your organization — it does not use 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.
upload_email_attachment
filename*content_type*content_base64*
Upload a file to attach to a future outbound email. ``content_base64`` is the file's raw bytes, base64-encoded. Returns ``{"id": ..., "filename": ..., "content_typ… 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.
whoami