Send a message over a verified domain. Pass templateId (+ optional templateData) to send from a saved or base template. Requires an API key (mk_live_…).

Send one personalized message per recipient (up to 50) in a single call. Shared fields form the base message; each recipients[] entry gets its own message to exactly one address, with per-recipient templateData and headers merged over the shared ones. Every message passes the same gates as send() and gets its own id; the response reports each recipient's outcome in order, so a batch can partially succeed. Pass scheduledAt to park the whole batch for later (one cancelable ssnd_… per recipient). Requires an API key (mk_live_…).

Record one application-level fact about a user — user.created, trial.expiring, payment.failed. THE primary way a sequence starts on a developer platform: your application already knows when a payment failed, so it says so, and every enabled trigger listening for that name enrolls the contact with the payload as its input. Identify the subject with email or contactId (never both). Pass a dedupeKey to make retries idempotent: a repeat returns the original event with duplicate: true rather than enrolling anyone twice. Requires an API key (mk_live_…).

List recorded events, newest first — the surface for confirming a POST landed and for debugging a sequence that did not trigger. Filter by name and/or email. Requires an API key (mk_live_…).

List the distinct event names this account works with, so an editor can offer them instead of asking you to remember one. Returns both events actually posted (with a count and when one last arrived) and events your sequences already trigger on or wait for but that may never have been sent — sequences are routinely written before the application emits the event, so a list of only-what-you-have-sent would be a trap. Requires an API key (mk_live_…).

List your sequences, newest first, each with live enrollment counts. Archived sequences are omitted. Requires an API key (mk_live_…).

Create a sequence: a declared input shape, the steps a contact walks over time, and zero or more triggers. A sequence is a function — input is its signature, and every door must satisfy it, so a step's {{input.field}} means the same thing however it was started. Created as a draft unless you pass status "active". The whole definition is validated up front and every problem is reported at once, so you fix a program in one pass rather than one 400 at a time. Requires an API key (mk_live_…).

Get one sequence with its definition and live enrollment counts. Requires an API key (mk_live_…).

Edit a sequence. Changing the STEPS bumps its version and contacts already in flight keep walking the version they started on, so an edit can never make someone skip or repeat a step. Nothing else re-pins anybody — a rename, a pause, the input signature, and the trigger set are all editable while people are mid-flight. Archiving retires everyone in flight; pausing deliberately does not, so unpausing resumes rather than restarts. Requires an API key (mk_live_…).

Delete a sequence and retire every contact still walking it. The response reports how many were canceled. Requires an API key (mk_live_…).

List the triggers attached to a sequence — the doors into it. Requires an API key (mk_live_…).

Attach a trigger: when this event arrives, enroll the contact it is about. Attaching never bumps the sequence's version and never touches anyone already in flight — a trigger is a fact about the outside world, a sequence is a program, and they change on different rhythms. The sequence needs a from address first, since an event-triggered enrollment has no message to inherit a sender from. Requires an API key (mk_live_…).

Edit a trigger, or toggle enabled to switch the door off without deleting it. Either way, everyone already walking the sequence carries on. Requires an API key (mk_live_…).

Detach a trigger. Stops future enrollments through that door and nothing else. Requires an API key (mk_live_…).

Start a sequence for one contact, directly — when your code already knows WHICH sequence it wants. Takes a sequence NAME or id, so "start the dunning sequence" needs no lookup. Returns the enrollment it created: the run you then inspect, follow, or cancel. Refused with 409 when the address is suppressed, is already running on a reentry: "once" sequence, or is missing a required input — and the response says which. Reach for sendEvent instead when your code only knows what HAPPENED and policy should decide what reacts. Requires an API key (mk_live_…).

Stop whatever is chasing someone. Pass the cancelKey you set when starting — so you cancel with your own invoice or order id and never store ours — or pass sequence and email together when you did not set one. Always answers 200 with a count, so it is safe to fire blindly from a webhook. Requires an API key (mk_live_…).

List who is in a sequence and where each of them is. Filter with status. Requires an API key (mk_live_…).

Get one enrollment — which sequence, which step, and what happens next. Requires an API key (mk_live_…).

Every step this enrollment has executed, with the outcome and the reason for it. This is the "why didn't step 3 fire" view. Requires an API key (mk_live_…).

Cancel one specific run by its enrollment id — the per-row action when you are looking at the enrollments table. To stop whatever is chasing a contact without knowing which run, use stopSequence. Requires an API key (mk_live_…).

Upload a file to MailKite storage and get back a secure, time-limited URL. Reference the returned url as an attachment in send() ({ filename, url }) or link it inline in your HTML — instead of base64-inlining large files on every send. Give the file ONE of four ways: a local path (read and streamed as raw bytes by the CLI/SDK/local MCP), a remote url (MailKite fetches and re-hosts it), base64 content, or — over raw HTTP — the file bytes as the POST body with ?filename=. retentionDays (7/30/90/365, default 7) sets how long the file and URL live. Requires an API key (mk_live_…).

List your saved email templates (light metadata only — no body). Use getTemplate for the full template. Requires a management session token.

List the premade base templates (light metadata). Clone one with createTemplate({ baseId }) or send from it directly via send({ templateId }). Requires a management session token.

Get one template (full: subject, html, text, theme). Works for your templates (tpl_…) and base templates (base_…). Requires a management session token.

Create a template. Pass baseId to clone a base template into your own, or provide name/subject/html/text/theme directly. Requires a management session token.

List your domains, each with its webhook URL. Requires a management session token.

Add a domain. Returns the domain + DNS records. Paid plans may pass email_provider_id to choose a provider (list available providers with listEmailProviders); free plans are always pinned to the platform default (SES US East 2 production). Requires a management session token.

Suggest a free, currently-unclaimed subdomain label to prefill the input with, plus the base zone it would live on. Read-only — suggesting does not reserve the name. Always take the zone from base rather than hard-coding it: which zones are on offer changes over time. Requires a management session token.

Check whether a free subdomain label can be claimed. Read-only and cheap — call it as the user types. reason explains a rejection and is safe to show verbatim. Requires a management session token.

Claim a free MailKite subdomain — a <label>.<base> host on a zone we run (call suggestSubdomain for the current base; the pool changes over time and more than one may be offered). The fastest path to a sending identity: we host the zone, so it comes back already verified with an empty dns array — nothing for the customer to publish. Use it when you want onboarding to work without asking anyone to touch DNS; bring your own domain with createDomain when you want mail to come from your own name. Requires a management session token.

Get one domain with DNS records + webhook. Requires a management session token.

Remove a domain. Requires a management session token.

Check DNS and update status. Requires a management session token.

Set or replace the domain's catch-all webhook. Requires a management session token.

Set or replace the domain's dedicated tracking-event webhook: an HTTPS endpoint that receives signed email.* engagement events (email.sent / email.bounced / email.complained / email.opened / email.clicked, shaped per the tracking-event schema) SEPARATELY from inbound mail. This is the split-endpoint override for consumers that keep engagement events away from their inbound webhook (e.g. django-anymail's paired views); most consumers should prefer setWebhookEvents, which delivers everything to the one inbound webhook. When both are configured, this URL wins for engagement events. Returns the signing secret (the same account secret as inbound deliveries). Requires a management session token.

Remove the domain's tracking-event webhook (engagement events stop). Requires a management session token.

Opt the domain's inbound webhook into engagement events — one webhook, all events. Pass "all" or a list of email.* tracking types (email.sent / email.bounced / email.complained / email.opened / email.clicked) and MailKite delivers them to the same webhook route that receives the domain's inbound mail; consumers switch on the payload's type (inbound mail is type email.received, engagement events follow the tracking-event schema). Off by default, so existing inbound consumers never see event types they didn't opt into. Events at the inbound webhook are signed with that route's secret (account secret fallback) — the same key inbound deliveries already use. If a dedicated tracking webhook URL is set (setTrackingWebhook), engagement events go there instead. Requires a management session token.

Opt the domain's inbound webhook back out of engagement events (inbound email.received only — the default). Requires a management session token.

Remove the domain's webhook. Requires a management session token.

Send a signed test event to the domain's webhook. Requires a management session token.

Check whether a domain is available to register, and at what price. Read-only — no charge. Requires a management session token.

Register (buy) a domain on the customer's behalf; provisions mail DNS and adds it to the account in one call. Charges the registrar. Requires a management session token. Does NOT register automatically — returns a dashboard link for the user to review the price and confirm. An assistant can never purchase a domain on its own.

List inbound routing rules. Requires a management session token.

Create a route (match, action, destination). Requires a management session token.

Delete an inbound routing rule by id. Pair with createRoute to register and tear down a webhook destination — e.g. an automation platform subscribing on enable and cleaning up on disable. Requires a management session token.

Send a message to one of your inbox agents and get its reply. Defaults to the account's default agent; pass routeId or address to target a specific agent, or model to override the model. This is separate from inbound routing — it does not match or override routes. Requires an API key (mk_live_…).

Route a message to one of your registered routes (by routeId or address), running that route's action — agent, webhook, or forward. The route must already exist on your account; arbitrary destinations are not allowed. Requires an API key (mk_live_…).

List stored messages, newest first. Optionally filter with search (matches sender, recipient, or subject) and page with before (a received_at cursor) and limit; omit all for the default newest 100. Response is a bare array — paginate by passing the last row's received_at as the next before. Requires a management session token.

Get a message with deliveries + attachments. Requires a management session token.

Re-deliver a stored message to its webhook. Requires a management session token.

Replay a whole selection of webhook deliveries in one call — the bulk form of retryDelivery. Pass deliveryIds (replay those exact deliveries), messageIds (replay each message's most recent delivery per route), and/or threadIds (expanded server-side to every message in the conversation); they combine. At most 50 ids per request, so send larger selections as sequential batches. Always answers 200 with a per-id results array — one unreachable endpoint never hides the outcomes of the rest — so branch on ok and results, not the HTTP status. An id you don't own is reported as skipped with reason not_found, exactly as the single-delivery endpoint 404s. Requires a management session token.

Every captured attempt for one delivery, newest first: the request headers and payload we POSTed, and the status, headers, and body that came back. This is the per-attempt record behind a webhook post-mortem, fetched without pulling the whole message. Captures are retained for 45 days. Requires a management session token.

POST stored messages to one webhook route — including messages that arrived BEFORE the route existed, which no retry can reach (a retry replays an existing delivery row, and a new route has none). Use listRouteCandidates to find what a route could be sent. Webhook routes only: a forward would re-send real mail to a third party and an agent would re-spend model tokens, so both answer 400 route_action. At most 50 ids per request; same per-id results contract as retryDeliveries. Requires a management session token.

Stored inbound messages this route could be asked to deliver, newest first — the preview for replaying mail to a route defined after that mail arrived. Each row carries delivered_here, so you can send a route only what it has never seen. Page with before (the response's nextBefore); because matching happens after a bounded scan, a page can come back shorter than limit while more still remain — keep going until nextBefore is null. Requires a management session token.

Mint a short-lived, single-use token that authorises one Realtime API connection. For browsers: EventSource cannot set headers, so this is what a page passes as ?token= instead of putting an API key in a URL. Inherits the calling credential's scope, expires in five minutes, and burns on first use. The stream itself is GET /v1/realtime — a subscription, not a request/response call, so it is contracted in sdks/spec/realtime.json rather than here. Requires an API key (mk_live_…).

List your contact lists (static, curated broadcast audiences), each with its member count. Requires a management session token.

Create a contact list. Returns the list with its id (lst_…); add contacts with addListContacts. Requires a management session token.

Get one contact list with its member count. Requires a management session token.

Rename a contact list. Requires a management session token.

Delete a contact list. The list is removed; the contacts themselves are kept. Requires a management session token.

List the contacts that are members of a list, newest first. Optionally page with before (a last_seen_at/created_at cursor) and limit. Response is a bare array — paginate by passing the last row's last_seen_at (or created_at) as the next before. Requires a management session token.

Add contacts (by id, ctr_…) to a list. Returns how many were newly added; contacts already on the list are ignored. Requires a management session token.

Remove one contact from a list (the contact itself is kept). Requires a management session token.

List your broadcasts (one-to-many sends) with status and send stats. Requires a management session token.

Create a broadcast draft. from is required; set audience to { type: "all" } or { type: "list", id: "lst_…" }. Returns the broadcast with its id (bct_…). Send it with sendBroadcast. Requires a management session token.

Get one broadcast with its status and recipient summary. Requires a management session token.

Edit a draft broadcast (any of from/subject/audience/html/… ). Drafts only. Requires a management session token.

Delete a broadcast draft. Requires a management session token.

Send a broadcast now, or pass an ISO 8601 scheduledAt to schedule it. A one-click unsubscribe is always added. Returns the status and resolved audience count. Requires a management session token. Does NOT register automatically — returns a dashboard link for the user to review the price and confirm. An assistant can never purchase a domain on its own.

Verify the x-mailkite-signature header on an inbound webhook delivery. Runs entirely locally (HMAC-SHA256 over ${t}.${payload}) — no network call. Returns true only when the signature matches and the event is within the freshness window. Runs locally (no API call) — no credentials needed.

Semantic search over the MailKite documentation — returns the most relevant doc sections for a natural-language query (hybrid vector + keyword search over https://mailkite.dev/docs). Public; no authentication required. Requires an API key (mk_live_…).

Register an OAuth client for this installation (RFC 7591 dynamic client registration) — step 1 of linking an existing MailKite account to your app. No pre-shared secret and no manual app review: you get a client_id back immediately and prove yourself with PKCE. Register once per install and keep the client_id. Requires a management session token.

Exchange an authorization code for an access token (or rotate a refresh token) — step 3 of linking. Between steps you send the user's browser to /oauth/authorize with your client_id, redirect_uri, state, and an S256 code_challenge; they sign in with whatever method they already use and approve, and the code comes back to your redirect_uri. Then call getApiKey with the access token and store the key. Requires a management session token.

Get the account's unrestricted API key (mk_live_…). Read-or-create: the first call mints it. Requires a management session token.

Rotate the account API key: the old key stops working immediately and a fresh one is returned. The plaintext is only shown here. Requires a management session token.

List the account's domain-scoped API keys. A scoped key can send and manage only its one domain — hand one to each site or CI job so a leak burns only that surface. Requires a management session token.

Create a key scoped to one domain. Ideal for per-site installs (e.g. a WordPress plugin) — the site never holds the account master key. Requires a management session token.

Revoke a domain-scoped key. Takes effect immediately. Requires a management session token.

List the account's app passwords. Each one opens a mailbox over IMAP and/or the mailbox API, scoped to a domain and an address pattern within it. Requires a management session token.

Create an app password for one domain and address pattern. Hand it to a mail client or an agent — the secret is returned once and never again. Requires a management session token.

Change what an app password covers — its label, address pattern, or protocols. The domain is fixed for the life of the password: repointing a live credential would hand its holder mail they were never granted, so create a new password instead. Requires a management session token.

Replace an app password's secret, keeping its scope. The old secret stops authenticating immediately; the new one is returned once. Use after a leak, when revoking would mean reconfiguring every client. Requires a management session token.

Revoke an app password. Takes effect immediately — any IMAP session or API call using it stops authenticating. Requires a management session token.

List a mailbox's messages, newest first. Authenticated with an app password granting api — this is how an agent reads its own inbox without an IMAP client. Requires a management session token.

Fetch one message's raw RFC822 bytes from a mailbox. Same app password auth as the list. Requires a management session token.

Replace a message's IMAP flags (e.g. mark it Seen). Flags set here are the same ones an IMAP client sees. Requires a management session token.

Current billing-period usage: emails used vs the plan's included bucket (null = unlimited), AI actions, and the overage state that gates sending. Powers quota meters in dashboards and integrations. Requires a management session token.

List suppressed addresses (unsubscribes, hard bounces, spam complaints, manual). Sends to a suppressed address are dropped before delivery. Requires a management session token.

Suppress an address so this account never sends to it again (reason defaults to manual). Requires a management session token.

Remove an address from the suppression list (URL-encode the email in the path). Removing an unsuppressed address is a no-op success. Requires a management session token.

Create a MailKite account from just an email — no password. Returns the new account's API key immediately; a verification link is emailed, and SENDING stays blocked until the address is verified (poll me()). An existing email returns 409 account_exists with no credentials. Powers plugin/CLI onboarding. Requires a management session token.

The account behind this credential: email, whether it is verified (sending is blocked until it is), and plan. Use to poll verification state after register(). Requires an API key (mk_live_…).