# Email URL: https://docs.hanzo.ai/docs/openapi/email > Email — 10 operations on https://api.hanzo.ai. Also for this capability: **API** · [CLI](https://docs.hanzo.ai/docs/cli/email) · [MCP](https://docs.hanzo.ai/docs/mcp-tools/email) · [SDKs](https://docs.hanzo.ai/docs/sdks) The REST reference for **Email** — 10 operations, generated from the OpenAPI document. > [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | -------------- | -------------------------------------- | | **Base URL** | `https://api.hanzo.ai` | | **Operations** | 10 | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | ## Specification Specification pending — no HIP in [hanzoai/hips](https://github.com/hanzoai/hips) declares `capability: email` yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139. ## Four surfaces | Surface | Reaches this capability as | Coverage | | -------- | --------------------------------------------- | ------------------------------------------------------------------------- | | **REST** | `email` at its own prefix | 10 operations | | **CLI** | `hanzo email …` | 10 of 10 | | **SDK** | `EmailApi` in every published client | 8 of 10 — the clients are generated at their own release | | **MCP** | tool `email` on `https://api.hanzo.ai/v1/mcp` | 8 operations, 3 under the document's own id — ask `describe` for the rest | ## Quickstart ```bash export HANZO_API_KEY=sk-... # console.hanzo.ai → API keys ``` Then the first call — a read that needs nothing but the key. `GET /v1/email`, operation `get_email`: **CLI** ```bash hanzo email list ``` **SDK** **.ts** ```ts import { Configuration, EmailApi } from 'hanzoai'; const api = new EmailApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getEmail(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import EmailApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = EmailApi(client).get_email() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.EmailAPI.GetEmail(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, email_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = email_api::get_email(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.EmailApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new EmailApi(client).getEmail(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/email \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** MCP reaches **email** through the `email` tool, which names its 8 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_emails" } } }' ``` Answers `200` with `object` — ok. ## Endpoints | Endpoint | What it does | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`GET /v1/email/{id}`](https://docs.hanzo.ai/docs/openapi/email/get-email-by-id) | Reads one message of the org's ledger, sent through this API or told of by its provider, with what became of it. | | [`PUT /v1/email/provider`](https://docs.hanzo.ai/docs/openapi/email/put-email-provider) | Sets the provider the org's mail leaves by when a send pins none: ses or sendgrid. | | [`GET /v1/email/sendgrid/status`](https://docs.hanzo.ai/docs/openapi/email/get-email-sendgrid-status) | Reports the org's SendGrid configuration: whether it holds the credentials a send needs, the account's credits as SendGrid answers them, what the org's ledger counted sent by SendGrid in the last 24 hours, and the DNS records of the sending domain. | | [`GET /v1/email/ses/status`](https://docs.hanzo.ai/docs/openapi/email/get-email-ses-status) | Reports the org's Amazon SES configuration: whether it holds the credentials a send needs, the account's limits as SES answers them (sandbox, sending enabled, 24-hour quota, rate, sent in the last 24 hours), what the org's ledger counted sent by SES in the last 24 hours, and the DNS records of the sending domain. | | [`GET /v1/email/stats`](https://docs.hanzo.ai/docs/openapi/email/get-email-stats) | Counts the org's mail over a range: sent, delivered, opened, clicked, bounced, complained and unsubscribed, each a count of messages, in all, by provider, by campaign and by day or hour (UTC). | | [`POST /v1/email/verify`](https://docs.hanzo.ai/docs/openapi/email/post-email-verify) | Evaluates an email address using explicitly selected, composable checks. | | [`POST /v1/email/webhooks/sendgrid`](https://docs.hanzo.ai/docs/openapi/email/post-email-webhooks-sendgrid) | Receives SendGrid's Signed Event Webhook: the delivery is an array of events, signed (ECDSA P-256, SHA-256) over its timestamp header followed by the body, under the public key the organization holds (the webhook-public-key credential). | | [`POST /v1/email/webhooks/ses`](https://docs.hanzo.ai/docs/openapi/email/post-email-webhooks-ses) | Receives Amazon SES events as an SNS HTTPS subscription delivers them. | | [`GET /v1/email`](https://docs.hanzo.ai/docs/openapi/email/get-email) | Reads a page of the org's ledger, newest first: every message sent through POST /v1/email, and every message SES or SendGrid told of by its events, sent from anywhere on the org's account. | | [`POST /v1/email`](https://docs.hanzo.ai/docs/openapi/email/post-email) | Sends commercial email from the org through SES or SendGrid: one message per recipient, each carrying its own signed unsubscribe link in the footer and in List-Unsubscribe and List-Unsubscribe-Post (RFC 8058), and every http(s) link tagged with utm\_source=email, utm\_medium=\, utm\_campaign=\, utm\_content=link\ and from=\, each only where the link does not carry it already. | --- [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)