Email for every product you ship — receive email as a webhook, send over a verified domain, give an AI agent its own inbox.
The official MailKite library for Python.
Docs · Library guide · mailkite.dev · AI agents
Read-only mirror. This repo is a generated, release-time mirror of the MailKite monorepo (the private source of truth) — development doesn't happen here. Install from PyPI and open issues against the MailKite docs.
pip install mailkite-devPublished as
mailkite-devwhile themailkitename is reclaimed — the import isfrom mailkite import MailKite.
importosfrommailkiteimportMailKitemk=MailKite(os.environ["MAILKITE_API_KEY"])
res=mk.send({
"from": "hello@myapp.ai",
"to": "ada@example.com",
"subject": "Your invoice #1042",
"html": "<p>Thanks! Receipt attached.</p>",
})Runnable examples live in examples/ — send mail, verify webhooks, build an AI email agent, and log users in:
| Example | What it shows |
|---|---|
examples/01_send_email.py | Send an email over a verified domain — the 10-second "it works". |
examples/02_receive_webhook.py | Receive inbound email as a webhook — and VERIFY the HMAC signature before trusting it. |
examples/03_agent_email_reply.py | An AI email agent: inbound email → Claude drafts a reply → MailKite sends it, threaded. |
examples/04_give_your_agent_an_inbox.py | Give your agent its own email address — MailKite's built-in inbox agent answers mail for… |
examples/05_server_login.py | Server-side login + register. |
Every method is documented on its own page under docs/. The full surface:
| Method | What it does |
|---|---|
send | Send a message over a verified domain. Pass templateId (+ optional templateData) to… |
sendBatch | Send one personalized message per recipient (up to 50) in a single call. Shared fields… |
uploadAttachment | Upload a file to MailKite storage and get back a secure, time-limited URL. Reference the… |
listTemplates | List your saved email templates (light metadata only — no body). Use getTemplate for the… |
listBaseTemplates | List the premade base templates (light metadata). Clone one with createTemplate({ baseId… |
getTemplate | Get one template (full: subject, html, text, theme). Works for your templates (tpl_…) and… |
createTemplate | Create a template. Pass baseId to clone a base template into your own, or provide… |
listDomains | List your domains, each with its webhook URL. |
createDomain | Add a domain. Returns the domain + DNS records. Paid plans may pass email_provider_id… |
getDomain | Get one domain with DNS records + webhook. |
deleteDomain | Remove a domain. |
verifyDomain | Check DNS and update status. |
setWebhook | Set or replace the domain's catch-all webhook. |
setTrackingWebhook | Set or replace the domain's dedicated tracking-event webhook: an HTTPS endpoint that… |
deleteTrackingWebhook | Remove the domain's tracking-event webhook (engagement events stop). |
setWebhookEvents | Opt the domain's inbound webhook into engagement events — one webhook, all events. Pass… |
deleteWebhookEvents | Opt the domain's inbound webhook back out of engagement events (inbound email.received… |
deleteWebhook | Remove the domain's webhook. |
getWebhookSecret | Get this domain's webhook signing secret (whsec_…) — the per-route secret used to verify… |
testWebhook | Send a signed test event to the domain's webhook. |
checkDomainAvailability | Check whether a domain is available to register, and at what price. Read-only — no charge. |
registerDomain | Register (buy) a domain on the customer's behalf; provisions mail DNS and adds it to the… |
listRoutes | List inbound routing rules. |
createRoute | Create a route (match, action, destination). |
deleteRoute | Delete an inbound routing rule by id. Pair with createRoute to register and tear down a… |
agent | Send a message to one of your inbox agents and get its reply. Defaults to the account's… |
route | Route a message to one of your registered routes (by routeId or address), running… |
listMessages | List stored messages, newest first. Optionally filter with search (matches sender… |
getMessage | Get a message with deliveries + attachments. |
retryDelivery | Re-deliver a stored message to its webhook. |
listLists | List your contact lists (static, curated broadcast audiences), each with its member count. |
createList | Create a contact list. Returns the list with its id (lst_…); add contacts with… |
getList | Get one contact list with its member count. |
updateList | Rename a contact list. |
deleteList | Delete a contact list. The list is removed; the contacts themselves are kept. |
listListContacts | List the contacts that are members of a list, newest first. Optionally page with before… |
addListContacts | Add contacts (by id, ctr_…) to a list. Returns how many were newly added; contacts… |
removeListContact | Remove one contact from a list (the contact itself is kept). |
listBroadcasts | List your broadcasts (one-to-many sends) with status and send stats. |
createBroadcast | Create a broadcast draft. from is required; set audience to { type: "all" } or {… |
getBroadcast | Get one broadcast with its status and recipient summary. |
updateBroadcast | Edit a draft broadcast (any of from/subject/audience/html/… ). Drafts only. |
deleteBroadcast | Delete a broadcast draft. |
sendBroadcast | Send a broadcast now, or pass an ISO 8601 scheduledAt to schedule it. A one-click… |
verifyWebhook | Verify the x-mailkite-signature header on an inbound webhook delivery. Runs entirely… |
replyOk | The acknowledgement body a webhook consumer returns to confirm it processed the event —… |
replySpam | Control-mode reply a webhook consumer returns to tell MailKite to mark the message as… |
replyDrop | Control-mode reply a webhook consumer returns to tell MailKite to drop (discard) the… |
replyBlockSender | Control-mode reply a webhook consumer returns to tell MailKite to block the sender — the… |
encrypt | Encrypt a UTF-8 string to a domain's RSA public key (SPKI/PEM), returning the at-rest… |
decrypt | Decrypt a MailKite at-rest envelope JSON with your RSA private key (PKCS8/PEM), returning… |
semanticSearch | Semantic search over the MailKite documentation — returns the most relevant doc sections… |
getApiKey | Get the account's unrestricted API key (mk_live_…). Read-or-create: the first call mints… |
rotateApiKey | Rotate the account API key: the old key stops working immediately and a fresh one is… |
listScopedKeys | List the account's domain-scoped API keys. A scoped key can send and manage only its one… |
createScopedKey | Create a key scoped to one domain. Ideal for per-site installs (e.g. a WordPress plugin)… |
deleteScopedKey | Revoke a domain-scoped key. Takes effect immediately. |
getUsage | Current billing-period usage: emails used vs the plan's included bucket (null =… |
listSuppressions | List suppressed addresses (unsubscribes, hard bounces, spam complaints, manual). Sends to… |
addSuppression | Suppress an address so this account never sends to it again (reason defaults to manual). |
removeSuppression | Remove an address from the suppression list (URL-encode the email in the path). Removing… |
register | Create a MailKite account from just an email — no password. Returns the new account's API… |
me | The account behind this credential: email, whether it is verified (sending is blocked… |
MailKite speaks the Model Context Protocol: every API method is a tool your AI assistant (Claude, Cursor, …) can call — send mail, manage domains, search the docs, and give an agent its own inbox. Full guide: https://mailkite.dev/docs/ai-agents.
Hosted (recommended) — one-click OAuth, no key to copy:
claude mcp add --transport http mailkite https://mcp.mailkite.dev/mcpIn Claude Code you can also install the plugin:
/plugin marketplace add mailkite/claude-code
/plugin install mailkite@mailkite
Any chat/UI agent: "Add the MCP server at https://mcp.mailkite.dev/mcp and authenticate in the browser when prompted."
Local (static key, offline / CI):
{ "mcpServers": { "mailkite": { "command": "npx", "args": ["-y", "@mailkite/mcp"], "env": { "MAILKITE_API_KEY": "mk_live_…" } } } }Give an agent its own inbox. Route inbound mail to a built-in inbox agent (the agent route action) and it answers, files, or escalates on its own — see https://mailkite.dev/docs/ai-agents.
Same contract, every language — pick the one for your stack (full list: https://mailkite.dev/docs/libraries):
| Library | Repo | Distribution |
|---|---|---|
| MailKite for Node.js | mailkite-node | npm |
| MailKite for Python (this repo) | mailkite-python | PyPI |
| MailKite for Ruby | mailkite-ruby | RubyGems |
| MailKite for Java | mailkite-java | Maven Central |
| MailKite for PHP | mailkite-php | Packagist |
| MailKite for Go | mailkite-go | Go modules |
| @mailkite/cli | mailkite-cli | npm |
| @mailkite/mcp | mailkite-mcp | npm |
| @mailkite/client | mailkite-js | npm |
| @mailkite/expo | mailkite-expo | npm |
| MailKiteClient | mailkite-swift | Swift Package Manager |
| dev.mailkite:mailkite-client | mailkite-kotlin | Maven Central |
| mailkite_client | mailkite-flutter | pub.dev |
- 📚 Documentation:https://mailkite.dev/docs
- 📦 This library's guide:https://mailkite.dev/docs/libraries
- 🤖 AI agents (MCP + inbox agents):https://mailkite.dev/docs/ai-agents
- 🌐 Website:https://mailkite.dev
- 🧭 All libraries:https://mailkite.dev/docs/libraries
Generated from the shared MailKite API contract. © MailKite.