Generate a new PostStack API key. The full key is returned ONCE in this response and cannot be retrieved again. When to use: agent needs to provision credentials for a new integration. Pick "sending_access" for send-only keys (recommended for app servers) or "full_access" for management. Returns: shaped key including the secret string — display it once and tell the user to store it securely. Example: { name: "Backend prod", permission: "sending_access" }

List API keys (only the prefix is returned, never the full secret). When to use: audit which keys exist, find a key id to revoke. Returns: { keys: [{ id, name, keyPrefix, permission, mode, ... }] }. Example: { per_page: 50 }

Get an API key's metadata (the secret is never returned after creation). When to use: confirm a key's permission, mode or last-used timestamp before revoking. Returns: shaped key without secret. Example: { id: 17 }

Permanently revoke an API key — all subsequent requests using it will fail. When to use: a key has leaked or is no longer needed. Confirm with the user — irreversible. Returns: { success: boolean }. Example: { id: 17 }

Create a draft broadcast targeted at a segment. When to use: agent has assembled a campaign body + segment id and wants to stage it for review or scheduled send. Created in "draft" status — call send_broadcast to dispatch. Returns: shaped broadcast (id, subject, status=draft, recipient counts will populate on send). Example: { segment_id: "seg_abc", from: "Acme hi@acme.io", subject: "April update", html }

List broadcasts. When to use: find recent campaigns, audit which broadcasts were sent, or pick one to inspect with get_broadcast. Returns: { items[], meta } — paginated shaped broadcasts with status and counts. Example: { per_page: 20 }

Get a broadcast's details and aggregate delivery stats. When to use: report on send results (delivered/opened/clicked/bounced) for a specific broadcast. Returns: shaped broadcast (subject, status, recipient counts). Example: { id: "br_abc" }

Edit a draft broadcast in place. Only draft broadcasts can be updated. When to use: tweak subject/body/segment before sending or before the scheduled time. Returns: shaped broadcast reflecting the new state. Example: { id: "br_abc", subject: "April update (revised)" }

Dispatch a draft broadcast to its segment immediately. When to use: after the user has reviewed the staged broadcast and approved sending. The broadcast must be in "draft" status. Returns: { success: boolean }. Example: { id: "br_abc" }

Cancel a queued or sending broadcast. When to use: stop a broadcast mid-flight. Already-delivered messages cannot be recalled. Returns: { success: boolean }. Example: { id: "br_abc" }

Get broadcast performance — either for one broadcast (variant breakdown if A/B) or for a leaderboard ranked by a chosen metric. When to use: agent wants to find the best-performing broadcast in a date range, or drill into one broadcast's stats. Pass broadcast_id for single mode, or { since, best_metric } for leaderboard mode. Returns: single mode → { broadcast: { id, subject, status, sent_at, total_recipients, delivered, opened, clicked, bounced, open_rate, click_rate }, variants: [...]|null }. Leaderboard → { metric, since, broadcasts: [...] } sorted by metric desc. Example: { broadcast_id: "br_abc" } — single mode. Example: { since: "2026-03-01T00:00:00Z", best_metric: "click_rate", limit: 5 } — leaderboard mode.

List contacts who received a broadcast but did NOT click any tracked link in it. When to use: build a follow-up campaign to "people who saw it but didn't act". Pair with create_segment + send_broadcast (or send_email) to re-engage them. Returns: { broadcast: { id, subject }, count, contacts: [{ id, email, first_name, last_name }] }. Example: { broadcast_id: "br_abc", limit: 500 }

Define a custom contact property (typed schema for the contact.properties field). When to use: agent is extending the contact data model — e.g. add a "plan" or "company" field that other tools can filter on. Returns: shaped property definition. Example: { name: "plan", label: "Subscription Plan", type: "select", options: ["free","pro","scale"] }

List all custom contact properties defined for this account. When to use: discover which custom fields are available before creating/updating contacts. Returns: { items: [property, ...] }. Example: {}

Edit a custom contact property's label, options or required flag. When to use: rename a label, expand the option list for a select, or toggle the required flag. Cannot change the type after creation. Returns: shaped property. Example: { id: 5, options: ["free","pro","scale","enterprise"] }

Remove a custom contact property definition. Existing contact values for this property are dropped. When to use: a property is unused and being retired. Confirm with the user — values are not recoverable. Returns: { success: boolean }. Example: { id: 5 }

Create a new contact (person who can receive emails / broadcasts). When to use: ingest a new signup, programmatic enrollment, or one-off addition. For bulk imports prefer the API import endpoint. Returns: shaped contact (id, email, names, properties, createdAt). Example: { email: "ada@lovelace.io", first_name: "Ada", properties: { plan: "pro" } }

List contacts with optional search and segment filtering. When to use: browse the contact book, find candidates by email/name fragment, or list members of a segment. Returns: { items[], meta } — paginated shaped contacts. Example: { search: "@acme.io", segment_id: "seg_xyz" }

Get full details of a contact by id. When to use: inspect a specific contact's properties, subscription state, or last activity. Returns: shaped contact with email, names, properties, unsubscribed flag, createdAt. Example: { id: "con_abc123" }

Update an existing contact's name, properties, or subscription state. When to use: keep the contact record in sync with your app (name change, plan upgrade, opt-out). Returns: shaped contact reflecting the new state. Example: { id: "con_abc123", properties: { plan: "scale" } }

Permanently delete a contact (irreversible — use unsubscribe_contact for opt-outs). When to use: GDPR erasure or removing a test contact. For unsubscribes, prefer unsubscribe_contact which preserves history. Returns: { success: boolean }. Example: { id: "con_abc123" }

Mark a contact as unsubscribed from all email (preserves the contact record). When to use: handle an unsubscribe request received outside PostStack (e.g. CS ticket, app preference). Returns: { success: boolean }. Example: { id: "con_abc123" }

Look up a contact by their email address. When to use: agent has an email address (e.g. from a webhook, signup, or user message) and wants the full contact record without paginating list_contacts. Returns 404 if no contact exists with that email — use create_contact to add one. Returns: shaped contact (id, email, names, properties, unsubscribed, createdAt). Example: { email: "ada@lovelace.io" }

Get a contact's recent email-event timeline grouped by event type (sent / delivered / opened / clicked / bounced / complained / failed). When to use: investigate a specific contact's engagement history before sending — e.g. did they bounce on the last campaign, are they frequently opening, when did they last click. Pass email OR id; email triggers a lookup, id is direct. Returns: { contact_id, email, total, events: { sent, delivered, opened, clicked, bounced, complained, failed, other } } where each is an array of { event_id, event_type, created_at, email_id, subject, from, geo_country, ua_client, is_prefetch, metadata }. Example: { email: "ada@lovelace.io", limit: 20 }

Get a single contact's engagement summary: segment + lifetime counts + open / click rates + last open / click + top tags. When to use: agent wants to qualify a contact before sending — e.g. "is Ada a frequent opener?", "should we exclude her from a re-engagement push?". Distinct from get_contact_activity which returns the raw timeline. Returns: { segment, last_engaged_at, engagement_calculated_at, lifetime_sent, lifetime_delivered, lifetime_opened, lifetime_clicked, open_rate, click_rate, last_open, last_click, top_tags: [{ tag, count }] }. Example: { email: "ada@lovelace.io" }

Search contacts with filters (segment, engagement, unsubscribed) and a fuzzy query across email/first_name/last_name. Adds a match_reason on each row indicating which field matched the query. When to use: agent needs to find a candidate set — e.g. "active contacts at @acme.io", "all dormant contacts", "people called Sarah". Use list_contacts for plain pagination without query, or use this when you need filtering or per-row match annotation. Returns: { items: [shaped contact + match_reason], meta: { page, perPage, total, totalPages } }. Example: { query: "ada", filters: { engagement_segment: "active" }, limit: 25 }

Add a new sending domain to PostStack. When to use: a customer is onboarding a new sending domain. The response includes DNS records (SPF, DKIM, DMARC, return-path) the user must configure before verify_domain succeeds. Returns: shaped domain with dnsRecords[] and pending status. Example: { name: "send.acme.io", region: "eu-west-1" }

List sending domains. When to use: choose which domain to send from, or audit which domains are verified. Returns: { domains: [...] } — array of shaped domains with status and tracking flags. Example: { per_page: 50 }

Get domain details including DNS records and verification status. When to use: read DNS records to display, or check whether the domain is verified before sending. Returns: shaped domain (status, dnsRecords[], tracking flags, verifiedAt). Example: { id: 42 }

Trigger DNS verification for a domain. When to use: user has configured DNS records (SPF/DKIM/DMARC/return-path) and wants PostStack to re-check them. Returns the new status — "verified" means sending is unblocked. Returns: shaped domain with updated status and per-record verified flags. Example: { id: 42 }

Update domain settings (open/click tracking, TLS mode). When to use: toggle tracking on/off, or switch between opportunistic and enforced TLS. Returns: shaped domain with updated settings. Example: { id: 42, click_tracking: false, tls_mode: "enforced" }

Permanently delete a sending domain (irreversible — historical email records remain). When to use: a domain is being decommissioned. Confirm with the user first since future sends from any matching from-address will fail. Returns: { success: boolean }. Example: { id: 42 }

Check whether a from-address is safe to send from RIGHT NOW. When to use: BEFORE sending agent-generated content from a non-default domain. Combines DNS verification (DKIM/SPF/DMARC), 30-day bounce + complaint rates, and the standard deliverability warnings (no plain-text body, link-domain mismatch, oversized HTML, etc.) into one response. Returns: { from, domain, domain_verified, dkim, spf, dmarc, return_path, volume_30d, bounce_rate, complaint_rate, warnings[] }. Example: { from: "Acme hi@acme.io" }

Send a single transactional email immediately, or schedule it for a future time. When to use: the agent has decided what to send (subject + html/text + recipients) and wants PostStack to deliver it. Run preview_email and lint_email first if the body was generated by the agent. Returns: { id } — the new email id, suitable for get_email or cancel_email. Example: { from: "Ada ada@example.com", to: ["new@user.io"], subject: "Welcome", html: "Hi" }

Send multiple emails in a single batch request (up to 100 per call). When to use: agent needs to send the same or different content to many recipients in one round-trip. For broadcasts to a saved segment use create_broadcast/send_broadcast instead. Returns: { data: [{ id }, ...] } — one id per email in the order submitted. Example: { emails: [{ from, to: ["a@x"], subject: "hi", html }] }

List previously-sent emails with optional filters and pagination. When to use: triage delivery, look up a specific recipient's history, or filter by status/tag/date. Returns: { items[], meta } — paginated emails with status, recipient, subject, timestamps. Example: { status: "bounced", date_from: "2026-04-10" }

Get full details and event timeline for a specific email by id. When to use: investigate why one email failed/bounced, or confirm delivery for a single send. Returns: shaped email record + events (queued, sent, delivered, opened, clicked, bounced). Example: { id: "em_7kf2x9" }

Cancel a scheduled email that has not yet entered the sending pipeline. When to use: agent wants to recall a scheduled send before it goes out. Cannot cancel emails already delivered. Returns: { success: boolean }. Example: { id: "em_7kf2x9" }

Reschedule a scheduled email to a new send time. When to use: a queued email needs its delivery time adjusted (e.g. send earlier/later in business hours). Returns: { success: boolean }. Example: { id: "em_7kf2x9", scheduled_at: "2026-04-18T09:00:00Z" }

Run a Rspamd-backed spam pre-flight on a draft email and return the score, action, and per-rule symbols. When to use: BEFORE sending agent-generated content. The score (0–15+) and action (no_action / greylist / add_header / soft_reject / reject) tell you whether the message is likely to be filtered. Symbols list the specific rules that fired. Returns: { score, action, symbols[], skipped, suggestions[] } — suggestions[] is derived from symbols whose score > 1. Example: { from: "Acme hi@acme.io", to: ["a@b.io"], subject: "Welcome", html: "hi" }

Render + lint + measure an email in one shot WITHOUT sending it. When to use: BEFORE send_email when the body was generated by the agent. Combines render_template (if template_id given), spam check, deliverability warnings, and size measurement so you only need one round-trip to know if it's safe to send. Returns: { rendered_subject, rendered_html, rendered_text, size: { html_bytes, text_bytes }, spam: { score, action, symbols[], skipped }, warnings: [{ severity, code, message }] }. Example: { from: "Acme hi@acme.io", to: ["a@b.io"], template_id: "tpl_welcome", variables: { first_name: "Ada" } }

List inbound emails received by mailboxes on this account. When to use: triage support inbox, find a recent message to inspect, or filter for messages needing reply. Returns: { data: [...], meta } shaped — id, from, subject, receivedAt per message. Example: { per_page: 20 }

Get a received inbound email's full headers and body. When to use: read a specific message before drafting a reply (use draft_from_thread or reply_to_inbound_email next). Returns: shaped inbound email with html/text body and headers. Example: { id: 7 }

List attachments on an inbound email (filename, size, contentType). When to use: decide whether to download attachments before forwarding or processing. Returns: { items: [{ filename, contentType, size }] }. Example: { id: 7 }

Send a reply to an inbound email (subject and threading headers are set automatically). When to use: the agent has drafted a reply body and wants to dispatch it. Quote the original message in the body if needed. Returns: { id } of the new outbound email. Example: { id: 7, from: "support@acme.io", html: "Thanks for reaching out…" }

Forward an inbound email to other recipients with an optional cover note. When to use: route a message to a teammate or another address. Returns: { id } of the forwarded outbound email. Example: { id: 7, from: "support@acme.io", to: ["dev@acme.io"], message: "FYI" }

Build a reply-draft skeleton for an inbound email — proper threading, quoted original, salutation/sign-off, suggested from + subject. Heuristic only; the agent fills in the body text. When to use: agent received an inbound email and wants to reply. Call this to get the draft scaffold, fill in body_placeholder with the actual reply, then call reply_to_inbound_email. Returns: { inbound, suggested_from, suggested_subject, salutation, body_placeholder, quoted_html, quoted_text, threading: { in_reply_to, references }, suggested_html, suggested_text }. Example: { inbound_id: 7, tone: "friendly" }

Provision a mailbox (IMAP/SMTP inbox) on a verified domain. When to use: agent is setting up a real human-readable inbox (e.g. support@acme.io). The password is required for IMAP/SMTP login. The domain must already be verified. Returns: shaped mailbox with emailAddress and quotaBytes. Example: { domainId: 42, localPart: "support", password: "", displayName: "Acme Support" }

List mailboxes across all domains. When to use: see which inboxes exist, find a mailbox id by email address. Returns: { items[], meta } — paginated shaped mailboxes. Example: { per_page: 50 }

Get a mailbox's metadata (status, quota, last login). When to use: inspect a specific mailbox before updating or deleting. Returns: shaped mailbox. Example: { id: 17 }

Update a mailbox's display name, quota, status, or webhook setting. When to use: change ownership label, suspend a mailbox, raise quota. Returns: shaped mailbox with new state. Example: { id: 17, status: "suspended" }

Permanently delete a mailbox and all its stored mail. When to use: decommissioning a mailbox. IRREVERSIBLE — confirm with the user, mail is gone. Returns: { success: boolean }. Example: { id: 17 }

Reset a mailbox's IMAP/SMTP password. When to use: rotate after suspected exposure, or onboarding handoff. Returns: { success: boolean }. Example: { id: 17, password: "" }

Suggest sensible from-addresses for a given purpose, drawn from the team's verified domains + existing mailboxes. When to use: agent doesn't know which from-address to use. Pass the purpose ("transactional", "marketing", "support", "newsletter", etc.); the tool ranks options based on existing mailboxes (real inboxes) and conventional local-parts for the purpose. Returns: { recommended: string|null, alternatives: string[], reasoning: string }. Example: { purpose: "transactional" }

Create a static contact segment (manually-managed list). When to use: agent needs a named bucket of contacts to send a broadcast to. Add members via add_contacts_to_segment. Returns: shaped segment with id and contactCount=0. Example: { name: "Spring 2026 launch" }

List contact segments. When to use: pick a segment id for create_broadcast or list_contacts(segment_id=…). Returns: { segments: [...] } — array of shaped segments with contactCount. Example: { per_page: 50 }

Get a segment's details and member count. When to use: confirm a segment's contactCount before broadcasting (to estimate volume). Returns: shaped segment (name, contactCount, createdAt). Example: { id: "seg_abc" }

Rename an existing segment. When to use: clean up segment names. Membership is unaffected. Returns: shaped segment with new name. Example: { id: "seg_abc", name: "Spring 2026 launch (final)" }

Delete a segment definition. Contacts in it are NOT deleted. When to use: remove an obsolete segment. Confirm with the user. Returns: { success: boolean }. Example: { id: "seg_abc" }

Add one or more contacts to a segment. When to use: enroll specific contacts in an existing segment (e.g. agent built a list and wants to materialise it). Returns: { added: number } or similar success indicator. Example: { id: "seg_abc", contact_ids: ["con_1", "con_2"] }

Remove a single contact from a segment. When to use: targeted removal (e.g. opt-out, manual exclusion). Does not delete the contact. Returns: { success: boolean }. Example: { id: "seg_abc", contact_id: "con_1" }

Create a subscription topic (named opt-in/opt-out preference like "Product Updates"). When to use: agent is setting up granular preferences so contacts can subscribe per topic instead of all-or-nothing. Returns: shaped topic. Example: { name: "Product Updates", description: "Monthly product news" }

List all subscription topics defined for this account. When to use: pick a topic_id for a broadcast, or audit which preferences exist. Returns: { items: [topic, ...] } shaped. Example: {}

Permanently delete a subscription topic. Subscriptions are removed. When to use: a topic is being retired. Confirm with the user. Returns: { success: boolean }. Example: { id: 3 }

List the subscription topics a contact is currently opted in to. When to use: check whether a contact is subscribed to a specific topic before sending. Returns: { items: [{ topicId, subscribedAt }] }. Example: { contact_id: "con_abc" }

Opt a contact in to a subscription topic. When to use: explicit user consent ("subscribe me to product updates"). Returns: shaped subscription record. Example: { contact_id: "con_abc", topic_id: 3 }

Opt a contact out of a subscription topic. When to use: explicit user opt-out for a single preference (the contact remains in other topics and the global list). Returns: { success: boolean }. Example: { contact_id: "con_abc", topic_id: 3 }

List suppressed email addresses (will not receive any emails). When to use: audit which addresses are blocked, or paginate to find a specific entry. Returns: { items[], meta } — paginated suppressions with reason and createdAt. Example: { per_page: 100 }

Block an email address from receiving any future sends. When to use: a recipient asked to be removed (manual), or you're importing prior bounces/complaints. Returns: shaped suppression record. Example: { email: "bouncy@aol.com", reason: "hard_bounce" }

Remove an address from the suppression list (sends will resume). When to use: a previously-suppressed user has explicitly opted back in, or a bounce was a misconfiguration. Returns: { success: boolean }. Example: { email: "fixed@aol.com" }

Create a new email template with {{variable}} placeholders. When to use: store a re-usable email body the agent (or app) will send repeatedly. Newly created templates are unpublished — call publish_template before sending. Returns: shaped template with id, version, published=false. Example: { name: "welcome-v3", subject: "Welcome {{first_name}}", html: "Hi {{first_name}}" }

List email templates. When to use: pick a template id for send_email or render_template, or audit which templates exist. Returns: { items[], meta } — paginated shaped templates with name, version, published flag. Example: { per_page: 50 }

Get a template's full body, subject and variables. When to use: read the source HTML/text before editing, or extract the variable list to know what to pass in. Returns: shaped template with htmlBody, textBody, variables[], version. Example: { id: "tpl_abc" }

Update an existing template's name, subject, body or variable list. When to use: edit a template in place. The template version is bumped on update. Returns: shaped template with new version. Example: { id: "tpl_abc", subject: "Updated subject" }

Permanently delete a template (irreversible). When to use: an unused template should be removed. Confirm with the user — emails referencing this template_id will fail. Returns: { success: boolean }. Example: { id: "tpl_abc" }

Mark a template as published so it can be referenced by send_email. When to use: after creating or editing a template you have validated and want available for sending. Returns: shaped template with published=true. Example: { id: "tpl_abc" }

Mark a template as unpublished so it cannot be sent. When to use: hide a template from sending without deleting it (e.g. retiring a campaign while keeping history). Returns: shaped template with published=false. Example: { id: "tpl_abc" }

Create a copy of an existing template (new id, same body, name suffixed " (copy)"). When to use: agent wants to fork a template before editing so the original remains intact. Returns: shaped new template (unpublished draft). Example: { id: 17 }

Server-side render a template with the provided variables. When to use: agent wants to preview the final subject/html/text before sending, or needs to inspect what variables a template requires. Returns missing_variables[] so the agent can prompt the user / fill in defaults. Returns: { subject, html, text, missing_variables[], template_variables[] }. Example: { template_id: "tpl_welcome", variables: { first_name: "Ada" } }

Subscribe a URL to receive event notifications via signed POST requests. When to use: agent is configuring an integration that needs to react to email/contact/domain events in real time. Returns: shaped webhook with id, url, events[], active=true. Example: { url: "https://hooks.acme.io/poststack", events: ["email.bounced", "email.complained"] }

List configured webhook endpoints. When to use: audit which integrations are receiving events. Returns: { webhooks: [...] } — array of shaped webhooks. Example: { per_page: 50 }

Get a webhook's details. When to use: inspect the URL, event list, or active state for a specific webhook. Returns: shaped webhook. Example: { id: 17 }

Edit a webhook's URL, event list, or enabled state. When to use: rotate to a new endpoint, expand/narrow events, or temporarily disable. Returns: shaped webhook with new state. Example: { id: 17, enabled: false }

Permanently delete a webhook endpoint. When to use: the integration is being removed. Confirm with the user — events will no longer be delivered. Returns: { success: boolean }. Example: { id: 17 }