# Hail

Give your AI agent a voice, a real phone number, and an inbox — place AI phone calls with ElevenLabs voices, run an AI call center, send SMS and agent mail, all from one API, CLI, and MCP server.

## Guides

- [Hail documentation](https://hail.so/docs.md): Hail gives your AI agent a voice, a real phone number, and an inbox — place AI phone calls with ElevenLabs voices, run an AI call center, send SMS and agent mail, all behind one MCP endpoint, one API key, one invoice. Most people use Hail Cloud; Hail's services are also self-hostable under AGPLv3, with LiveKit Cloud and channel providers remaining external.
- [Architecture](https://hail.so/docs/architecture.md): Hail v1 is three Python services plus a Go CLI, built around LiveKit Cloud.
- [Bring your own LLM](https://hail.so/docs/byo-llm.md): Point a Hail voice call at your own OpenAI-compatible endpoint. Your agent becomes the brain of the call: Hail handles telephony, speech-to-text, text-to-speech, turn detection, and tools, and asks your endpoint what to say on every turn.
- [CLI reference](https://hail.so/docs/cli.md): hail is the Go CLI. It codegens its client from openapi/openapi.yaml — that spec is the canonical contract. This page is a brief summary of each command group. Run hail <cmd> --help for the full, authoritative flag list.
- [Contributing](https://hail.so/docs/contributing.md): For the full operational runbook (releases, deployment, DB switching, all the known problems), refer to Operations. This page covers the contribution flow only.
- [MCP clients](https://hail.so/docs/mcp.md): Hail exposes MCP as a remote server. Hail Cloud uses OAuth. Paste the URL into your client. Click Allow in the browser. Your agent then gets the call/sms/mail tools. There are no keys to manage and no installation.
- [Self-hosting](https://hail.so/docs/self-host.md): Run Hail's API, voicebot, MCP server, Postgres, and object storage with Docker Compose. LiveKit Cloud and the providers for the channels you enable remain external. The code is AGPLv3.
- [AWS SES (email)](https://hail.so/docs/self-host/aws-ses.md): Outbound and inbound email go through Amazon SES (SESv2 API). You need an AWS account and the SES service enabled in one region. You also need IAM-role credentials (recommended for EC2/ECS/EKS deployments) or a long-lived access key.
- [LiveKit Cloud](https://hail.so/docs/self-host/livekit-cloud.md): LiveKit Cloud supplies the media (SIP bridge + WebRTC) in v1. A self-hosted SFU is a later milestone.
- [Operations runbook](https://hail.so/docs/self-host/operations.md): This document is the single source of truth for how to develop, deploy, migrate, and release Hail. If you are an AI agent that starts work on this codebase, read this document first together with CLAUDE.md.
- [SMTP inbound — not yet implemented](https://hail.so/docs/self-host/smtp-inbound.md): The SmtpInboundProvider interface exists in core/hailhq/core/providers/email/inbound/smtp.py but is not implemented. It is the cloud-agnostic / OSS-only path. We defer it to a follow-up milestone.
- [Twilio](https://hail.so/docs/self-host/twilio.md): You need a Twilio account, a phone number, and a SIP trunk that bridges to LiveKit Cloud.
- [VM deployment](https://hail.so/docs/self-host/vm-deploy.md): Self-host Hail on one Ubuntu VM behind HTTPS. GitHub Actions deploys every commit on main. The database is managed (Neon, Supabase, RDS, or your choice). The VM runs only the stateless services.
- [API versioning](https://hail.so/docs/versioning.md): /v1/<resource> is the canonical, documented form of every customer-facing Hail API route. It appears in the OpenAPI spec (openapi/openapi.yaml) and is what the CLI and generated clients target.
- [Webhooks](https://hail.so/docs/webhooks.md): When a subscribed event occurs — inbound mail or SMS, a delivery report, a call outcome — Hail POSTs a signed JSON event to your URL. Verify the X-Hail-Signature header against the once-shown secret. Return any 2xx, and you are done. Hail retries a non-2xx response (or a timeout) on a fixed ladder.

## API reference

Full list: https://hail.so/docs/api.md

- [Acquire Number](https://hail.so/docs/api/acquire_number_v1_numbers_post.md)
- [Activate Provider](https://hail.so/docs/api/activate_provider.md)
- [Check Domain](https://hail.so/docs/api/check_domain_v1_email_domains_check_domain_get.md)
- [Create Call](https://hail.so/docs/api/create_call_v1_calls_post.md)
- [Create Contact](https://hail.so/docs/api/create_contact_v1_contacts_post.md)
- [Create Email Domain](https://hail.so/docs/api/create_email_domain_v1_email_domains_post.md)
- [Create Email](https://hail.so/docs/api/create_email_v1_emails_post.md)
- [Create Sms](https://hail.so/docs/api/create_sms_v1_sms_post.md)
- [Create Subscription](https://hail.so/docs/api/create_subscription_v1_webhooks_post.md)
- [Delete Contact](https://hail.so/docs/api/delete_contact_v1_contacts__contact_id__delete.md)
- [Delete Email Domain](https://hail.so/docs/api/delete_email_domain_v1_email_domains__domain_id__delete.md)
- [Delete Member Phone](https://hail.so/docs/api/delete_member_phone_v1_members__user_id__phone_delete.md)
- [Delete Provider](https://hail.so/docs/api/delete_provider.md)
- [Delete Sms Suppression](https://hail.so/docs/api/delete_sms_suppression_v1_sms_suppressions__number__delete.md)
- [Delete Subscription](https://hail.so/docs/api/delete_subscription_v1_webhooks__sub_id__delete.md)
- [Enable Sms](https://hail.so/docs/api/enable_sms_v1_numbers__number_id__enable_sms_post.md)
- [Get Call](https://hail.so/docs/api/get_call_v1_calls__call_id__get.md)
- [Get Email Attachment](https://hail.so/docs/api/get_email_attachment_v1_emails__email_id__attachments__attachment_id__get.md)
- [Get Email Domain](https://hail.so/docs/api/get_email_domain_v1_email_domains__domain_id__get.md)
- [Get Email Raw](https://hail.so/docs/api/get_email_raw_v1_emails__email_id__raw_get.md)
- [Get Email Stats](https://hail.so/docs/api/get_email_stats_v1_emails_stats_get.md)
- [Get Email](https://hail.so/docs/api/get_email_v1_emails__email_id__get.md)
- [Get Number](https://hail.so/docs/api/get_number_v1_numbers__number_id__get.md)
- [Get Sender Id](https://hail.so/docs/api/get_sender_id_v1_sms_sender_id_get.md)
- [Get Sms](https://hail.so/docs/api/get_sms_v1_sms__sms_id__get.md)
- [Get Subscription](https://hail.so/docs/api/get_subscription_v1_webhooks__sub_id__get.md)
- [Get Whoami](https://hail.so/docs/api/get_whoami_v1_whoami_get.md)
- [Healthz](https://hail.so/docs/api/healthz_healthz_get.md)
- [List Calls](https://hail.so/docs/api/list_calls_v1_calls_get.md)
- [List Contacts](https://hail.so/docs/api/list_contacts_v1_contacts_get.md)
- [List Deliveries](https://hail.so/docs/api/list_deliveries_v1_webhooks__sub_id__deliveries_get.md)
- [List Email Domains](https://hail.so/docs/api/list_email_domains_v1_email_domains_get.md)
- [List Email Events](https://hail.so/docs/api/list_email_events_v1_emails__email_id__events_get.md)
- [List Emails](https://hail.so/docs/api/list_emails_v1_emails_get.md)
- [List Events](https://hail.so/docs/api/list_events_v1_events_get.md)
- [List Numbers](https://hail.so/docs/api/list_numbers_v1_numbers_get.md)
- [List Providers](https://hail.so/docs/api/list_providers.md)
- [List Sms Suppressions](https://hail.so/docs/api/list_sms_suppressions_v1_sms_suppressions_get.md)
- [List Sms](https://hail.so/docs/api/list_sms_v1_sms_get.md)
- [List Subscriptions](https://hail.so/docs/api/list_subscriptions_v1_webhooks_get.md)
- [Patch Contact](https://hail.so/docs/api/patch_contact_v1_contacts__contact_id__patch.md)
- [Patch Email Domain](https://hail.so/docs/api/patch_email_domain_v1_email_domains__domain_id__patch.md)
- [Patch Sender Id](https://hail.so/docs/api/patch_sender_id_v1_sms_sender_id_patch.md)
- [Patch Subscription](https://hail.so/docs/api/patch_subscription_v1_webhooks__sub_id__patch.md)
- [Put Member Phone](https://hail.so/docs/api/put_member_phone_v1_members__user_id__phone_put.md)
- [Redeliver](https://hail.so/docs/api/redeliver_v1_webhooks__sub_id__deliveries__delivery_id__redeliver_post.md)
- [Release Number](https://hail.so/docs/api/release_number_v1_numbers__number_id__delete.md)
- [Rotate Secret](https://hail.so/docs/api/rotate_secret_v1_webhooks__sub_id__rotate_secret_post.md)
- [Unsubscribe](https://hail.so/docs/api/unsubscribe_v1_unsubscribe_get.md)
- [Create Email Attachment](https://hail.so/docs/api/upload_email_attachment.md)
- [Upsert Provider](https://hail.so/docs/api/upsert_provider.md)
- [Validate Provider](https://hail.so/docs/api/validate_provider.md)
- [Verify Email Domain](https://hail.so/docs/api/verify_email_domain_v1_email_domains__domain_id__verify_post.md)