send_email
Send a transactional email, immediately or scheduled. scheduled at takes a relative phrase like 'in 3 days' or an ISO timestamp. The From domain must already be verified. Every accepted send answers with the same fields: id, status, thread id, scheduled at, skipped, reason and approval id. skipped: true (status 'rejected', with reason) means every recipient was suppressed or opted out and nothing was sent; a retry answers the same. status 'pending approval' (with approval id) means a person must release it; a retry does not release it. Otherwise skipped is false and reason and approval id are
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"from",
"to",
"subject"
],
"properties": {
"cc": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 49,
"description": "Cc addresses, each an address or 'Name <address>'. to, cc and bcc together hold at most 50"
},
"to": {
"type": "string",
"description": "Recipient address, or 'Ana Lima <ana@example.com>' to show their name in the To line. Suppressions and opt-outs match the address either way"
},
"bcc": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 49,
"description": "Bcc addresses. Each is a recipient: it counts toward the 50, the key's allowlist and its daily limit"
},
"from": {
"type": "string",
"description": "Sender address on a verified domain, e.g. 'Team <team@mail.example.com>'"
},
"html": {
"type": "string",
"description": "HTML body; provide html, text, or both"
},
"tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 10,
"description": "Up to 10 name/value labels, e.g. [{name:'category', value:'win-back'}]. They do not change delivery. Pass the same pair as tag 'category:win-back' to list_emails or list_threads to find this mail and its conversation again; a conversation carries the tags of every message sent on it"
},
"text": {
"type": "string"
},
"subject": {
"type": "string"
},
"scheduled_at": {
"type": "string",
"description": "'in 3 days' or an ISO 8601 timestamp"
},
"idempotency_key": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Optional. Any unique string for this one message, e.g. 'welcome-ana-2026-09-15'. Retrying with the same key and the identical arguments returns the first answer instead of sending again. A key reused for a different message is refused with 422 idempotency_key_reused and nothing is sent. 409 idempotency_in_progress means the first attempt is still running; a retry with the same key a few seconds later returns its answer"
}
},
"additionalProperties": false
}
list_emails
List messages newest first with their delivery status, including held, scheduled, skipped and failed ones and the mail campaigns and automations sent. Filter by status, recipient or tag. Paged: at most 100 per call; while has more is true, next cursor passed back as cursor with the same filters returns the next page. An unknown status is refused with 422 invalid request rather than answering an empty log.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"to": {
"type": "string",
"description": "Filter to one recipient address"
},
"tag": {
"type": "string",
"description": "One tag as name:value, e.g. 'category:win-back': only what carries exactly that pair. Without a colon it is refused with 422 invalid_request"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
},
"status": {
"enum": [
"queued",
"scheduled",
"sent",
"delivered",
"bounced",
"complained",
"rejected",
"canceled",
"failed"
],
"type": "string",
"description": "rejected: every recipient was suppressed or opted out, so nothing was sent. canceled: a scheduled send was cancelled. failed: the provider refused it, or a scheduled send could not go out"
}
},
"additionalProperties": false
}
get_email
Fetch one message with its full event timeline (send, delivery, bounce, complaint, open, click). The timeline shows why an email didn't arrive.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Message id"
}
},
"additionalProperties": false
}
cancel_scheduled_email
Cancel a scheduled email before it sends. Only works while status is 'scheduled': a message that has already started sending, or is in any other state, answers 409 invalid state naming its status; a retry answers the same, and get email shows where it stands. An unknown id answers 404 not found.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}
update_email_tags
Add or remove tags on an email already sent, scheduled or held, to refile it for the tag filters of list emails and list threads. Removals apply first, then additions, so one call swaps a tag: remove tags [{name:'recovery case'}] (no value: every tag with that name) with add tags [{name:'category', value:'billing-recovery'}]. The thread and the dashboard's tag suggestions follow. Changes only what SendRaven stores, not what the provider already saw. Safe to repeat. Answers the email as get email does. broadcast id, set on campaign mail, cannot be changed (422 invalid request), nor can a messag
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Message id"
},
"add_tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 10,
"description": "Pairs to add; one already present is not added twice"
},
"remove_tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 50,
"description": "Tags to take off; leave value out to remove every tag with that name"
}
},
"additionalProperties": false
}
list_sending_domains
List sending domains with their verification status and the DNS records each one needs. Each record shows what is currently published, so this diagnoses a stuck verification. mail from says whether SES has adopted the bounce. subdomain as the Return-Path: pending while SES polls for its MX record, then active. SES polls for 72 hours from when the domain was added, not from when the MX appears, and then marks it failed; publishing the MX later and calling verify sending domain restarts it. A verified domain sends fine meanwhile; only SPF alignment waits.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
add_sending_domain
Register a sending domain and get back the DNS records to publish. It takes the domain mail is sent from — mail. and news. are provisioned beneath it and the right one is chosen per message, so a marketing complaint spike can never affect password reset delivery. subdomains names the pair differently (tx. and promo.), still one domain. risk class provisions one identity on the domain exactly as given instead; it cannot be combined with subdomains. Two records come back marked optional: an inbound MX so replies land in threads, and a link. CNAME that turns on click tracking on the customer's ow
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"minLength": 3,
"description": "The bare domain mail is sent from, e.g. example.com: no scheme, path or @, and not a public suffix"
},
"risk_class": {
"enum": [
"transactional",
"marketing"
],
"type": "string",
"description": "Omitted, both are provisioned, which almost every sender needs"
},
"subdomains": {
"type": "object",
"properties": {
"marketing": {
"type": "string",
"description": "One label, e.g. promo for promo.example.com. Default news"
},
"transactional": {
"type": "string",
"description": "One label, e.g. tx for tx.example.com. Default mail"
}
},
"description": "Only to name the pair something other than mail. and news.; the two must differ",
"additionalProperties": false
}
},
"additionalProperties": false
}
verify_sending_domain
Re-check a domain's DNS records now instead of waiting for the background monitor. Also restarts bounce-path (mail from) verification when SES gave up before the MX record existed.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The sending domain's id from list_sending_domains (a UUID), not the domain name"
}
},
"additionalProperties": false
}
list_suppressions
List addresses we refuse to mail and why (hard bounce, complaint, unsubscribe, manual, list hygiene), newest first, each with its scope. When someone reports not receiving email, this shows whether the address is suppressed. email returns one address's suppressions directly; scanning pages instead is how the wrong suppression gets cleared. At most 100 per call; while has more is true, next cursor passed back as cursor returns the next page.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"email": {
"type": "string",
"description": "One address: every scope it is suppressed for"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
}
},
"additionalProperties": false
}
add_suppression
Stop sending to an address. Scope 'marketing' leaves transactional mail working; the default is 'all'. Reason 'unsubscribe' is a real opt-out: it also cancels the person's queued scheduled sends and ends their automation enrolments, which is what a person who asked to stop expects and 'manual' does not do. A hard bounce or complaint already on file is never replaced; the response is the stored suppression (id, email, reason, scope, detail, created at), so its reason says which one stands.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"scope": {
"enum": [
"all",
"transactional",
"marketing"
],
"type": "string",
"description": "Defaults to all"
},
"reason": {
"enum": [
"manual",
"list_hygiene",
"unsubscribe"
],
"type": "string",
"description": "Defaults to manual. unsubscribe also cancels queued mail and ends enrolments"
}
},
"additionalProperties": false
}
remove_suppression
Remove a suppression so the address can be mailed again. A hard bounce means the address was rejected by the receiving server, and re-sending raises the bounce rate that AWS enforces on. The scope must match the stored one: removed: false means nothing was suppressed in that scope (an address suppressed for 'marketing' is not lifted by 'all'); list suppressions with email shows the scope that is stored.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"scope": {
"enum": [
"all",
"transactional",
"marketing"
],
"type": "string",
"description": "Defaults to all"
}
},
"additionalProperties": false
}
create_broadcast
Create a campaign as a draft. Nothing is sent: preview broadcast reports its reach and send broadcast sends it. identity id must be a marketing sending domain (see list sending domains; risk class 'marketing'). topic key must name an existing topic (list topics); an unknown one is refused with 422 unknown topic, since it would count everyone as opted out. A segment id must filter the same audience as audience id. An A/B test takes 2 to 10 'variants' that differ in subject, from name or send at, and optionally 'ab test'. A subject or from-name test sends sample share of the audience (default 0.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"audience_id",
"identity_id",
"name",
"subject",
"html"
],
"properties": {
"html": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"ab_test": {
"type": "object",
"properties": {
"metric": {
"enum": [
"open",
"click"
],
"type": "string",
"description": "What decides the winner; default 'open'"
},
"sample_share": {
"type": "number",
"description": "Share of the audience in the test, 0.05 to 1; default 0.2. Ignored for a send-time test"
},
"decide_after_minutes": {
"type": "integer",
"description": "How long after the sample is fully sent to decide; 15 to 10080, default 240"
}
},
"additionalProperties": false
},
"segment": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 20,
"description": "Only contacts carrying every one of these tags, e.g. ['audio-player'] to mail one product's users from an audience that holds everyone. list_tags returns the tags that exist"
},
"exclude_tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 20,
"description": "Leave out contacts carrying any of these tags, e.g. ['premium']"
},
"opened_within_days": {
"type": "integer",
"maximum": 3650,
"minimum": 1
},
"clicked_within_days": {
"type": "integer",
"maximum": 3650,
"minimum": 1
},
"engaged_within_days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Only contacts who opened, clicked or were active in your product (last_active_at) in N days. Unlike exclude_unengaged_days, which keeps everyone new, this one filters a freshly imported list."
},
"exclude_unengaged_days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Drops mailed contacts with no open or click in N days; keeps anyone never mailed or added in the window"
}
},
"additionalProperties": false
},
"subject": {
"type": "string",
"maxLength": 998,
"minLength": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"maxLength": 32,
"description": "A name for this variant, lowercase letters, digits, - or _: 'urgent', 'question'"
},
"send_at": {
"type": "string",
"description": "ISO 8601 send time, for a send-time test only. Set it on every variant or on none; a send-time test mails the whole audience, each variant at its own time, with nothing held back"
},
"subject": {
"type": "string",
"maxLength": 998,
"minLength": 1,
"description": "Subject for this variant; the campaign's when omitted"
},
"from_name": {
"type": "string",
"description": "From display name for this variant; the campaign's when omitted"
}
},
"additionalProperties": false
},
"maxItems": 10,
"minItems": 2
},
"from_name": {
"type": "string",
"description": "From display name, e.g. 'Ana at Example'"
},
"topic_key": {
"type": "string",
"description": "An existing topic's key from list_topics. Lets recipients opt out of this kind of mail only"
},
"segment_id": {
"type": "string",
"description": "A saved segment's id from list_segments (a UUID), not its name or key"
},
"audience_id": {
"type": "string",
"description": "The audience's id from list_audiences (a UUID), not its name"
},
"identity_id": {
"type": "string",
"description": "A marketing sending domain's id from list_sending_domains (a UUID), not the domain name"
},
"view_in_browser": {
"type": "boolean",
"description": "Open every message with a 'View this email in your browser' link to the campaign's web_version_url. Needs the sending domain's click tracking to be active (list_sending_domains); otherwise 422"
}
},
"additionalProperties": false
}
get_broadcast
One campaign, with a 'progress' object while it is sending, paused or testing: how many addresses are still pending, sent, failed, or skipped because the person opted out after the campaign started. This is what tells a paused campaign that is still making progress from one that is waiting; pause reason says on what, and resume after when a warm-up pause renews. progress is null for a campaign not in flight. For an A/B test, progress.by variant is a list of { key, pending, sent, failed, skipped } in variant order, ending with a row whose key is null: the addresses still waiting for the winner.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The campaign's id from create_broadcast or list_broadcasts (a UUID), not its name"
}
},
"additionalProperties": false
}
list_broadcasts
List campaigns, newest first, with their status. Paged: at most 100 per call; while has more is true, next cursor passed back as cursor returns the next page. Each row is the campaign object get broadcast returns, live progress and A/B results included, without its html, which only get broadcast returns. Every field is snake case and always present, null when unset. A campaign showing 'paused' is not broken; its pause reason says why. A quota or interrupted pause continues on its own. A warm-up pause is the sending domain's daily allowance protecting its reputation: it resumes on its own at re
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
}
},
"additionalProperties": false
}
preview_broadcast
How many contacts a campaign would reach, and whether the reputation gate would allow it. It is the only way to see the size of a campaign without starting it. For an A/B test it also reports the sample size and per-variant count against the 100-per-variant floor; a send below the floor is refused.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The campaign's id from create_broadcast or list_broadcasts (a UUID), not its name"
}
},
"additionalProperties": false
}
send_broadcast
Send a draft or scheduled campaign now, or schedule it with scheduled at. This mails every contact in the segment and cannot be undone once started; preview broadcast shows the count beforehand. Marketing mail must carry a postal address: a workspace without one is refused with 422 no postal address (a person adds it in Settings), and a suspended workspace with 422 workspace suspended, whether sending now or scheduling. Calling this on an already-scheduled campaign with a new scheduled at moves it; with no scheduled at it starts now. Any other status answers 409 invalid state, and a malformed
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The campaign's id from create_broadcast or list_broadcasts (a UUID), not its name"
},
"scheduled_at": {
"type": "string",
"description": "UTC ISO 8601 timestamp with a Z suffix, e.g. 2026-09-16T09:00:00.000Z; offsets and phrases like 'in 2 hours' are refused. Omitted, it sends now"
}
},
"additionalProperties": false
}
pick_broadcast_winner
Decide an A/B test now instead of waiting for decide at. 'variant' names the winning key; without it the metric decides on the figures so far. The rest of the audience is then sent to the winner and cannot be redirected. Only a campaign in status 'testing' can be decided; anything else, or a campaign that is not an A/B test, answers 409 invalid state. A variant key the campaign does not have answers 422 invalid request. get broadcast shows the figures so far — a variant with a handful of opens more is not a result, and the worker decides on its own at decide at. Returns the campaign object, as
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The campaign's id from create_broadcast or list_broadcasts (a UUID), not its name"
},
"variant": {
"type": "string",
"description": "Variant key to send the remainder to; when omitted the metric decides"
}
},
"additionalProperties": false
}
resume_broadcast
Continue a paused campaign now. It mails only the addresses still pending — the audience was frozen when the campaign started and everyone already reached is marked — so calling this twice cannot double-send. Only works on a paused campaign; anything else answers 409 invalid state. pause reason says why it paused. A background worker resumes quota, interrupted and suspension pauses on its own, so this only saves waiting. A warm-up pause cannot be resumed before its resume after (409 invalid state naming the time) and resumes on its own then; a retry answers the same, because the allowance is p
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The campaign's id from create_broadcast or list_broadcasts (a UUID), not its name"
}
},
"additionalProperties": false
}
list_threads
List email conversations. awaiting reply=true returns only the threads where someone has written in and no answer has been sent, which is what needs a response. A reply held for approval or scheduled does not count as sent: such a thread stays in that list with pending reply true, meaning its answer is already on the way. Most recently active first, at most 100 per call; while has more is true, next cursor passed back as cursor with the same awaiting reply and tag returns the next page. Each thread lists the tags of the messages sent on it.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"tag": {
"type": "string",
"description": "One tag as name:value, e.g. 'category:win-back': only what carries exactly that pair. Without a colon it is refused with 422 invalid_request"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
},
"awaiting_reply": {
"type": "boolean",
"description": "true: only threads waiting on an answer. false: only threads that are not. Omitted: all"
}
},
"additionalProperties": false
}
get_thread
Read a conversation as a chronological transcript of outbound and inbound messages. Inbound text already has quoted history and signatures stripped; raw text holds the untrimmed body, for when the stripped version looks wrong. sender authenticated says whether the sender is who the From line claims; when false the From line may be forged, and a forged sender still passes SPF, so spf verdict does not show it. automated is true on an out-of-office or bounce report, which needs no answer (null on mail before 22 Sep 2026). pending reply is true when an answer written after the latest inbound messa
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Thread id"
}
},
"additionalProperties": false
}
reply_to_message
Reply to a message, keeping it on the same conversation. Sets the threading headers so the recipient's mail client shows it as part of the existing exchange rather than a new one, which send email does not do. It is a send, so it answers exactly as send email does and meets the same refusals (422 no verified identity, 429 daily limit, 403 recipient not allowed, and so on); idempotency key makes a retry safe.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reply_to_message_id",
"from",
"to",
"subject"
],
"properties": {
"to": {
"type": "string",
"description": "Recipient address, or 'Name <address>' to show their name"
},
"from": {
"type": "string",
"description": "Sender address on a verified domain"
},
"html": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 10,
"description": "Up to 10 name/value labels, e.g. [{name:'category', value:'win-back'}]. They do not change delivery. Pass the same pair as tag 'category:win-back' to list_emails or list_threads to find this mail and its conversation again; a conversation carries the tags of every message sent on it"
},
"text": {
"type": "string"
},
"subject": {
"type": "string"
},
"scheduled_at": {
"type": "string",
"description": "Send the reply later, still on this thread: 'in 3 days' or an ISO 8601 timestamp. Answers status 'scheduled' with the message id; cancel_scheduled_email with that id stops it, which is how a follow-up is withdrawn when the person answers first"
},
"idempotency_key": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Optional. Any unique string for this one message, e.g. 'welcome-ana-2026-09-15'. Retrying with the same key and the identical arguments returns the first answer instead of sending again. A key reused for a different message is refused with 422 idempotency_key_reused and nothing is sent. 409 idempotency_in_progress means the first attempt is still running; a retry with the same key a few seconds later returns its answer"
},
"reply_to_message_id": {
"type": "string",
"description": "Id of the message being answered, sent or received: usually the inbound entry's id from get_thread. An id that matches no message in this workspace is refused with 422 invalid_request rather than starting a new thread"
}
},
"additionalProperties": false
}
mark_thread_handled
Clear a conversation's awaiting reply flag without sending anything, for when the last inbound message needs no answer — a "thanks, all sorted" — so it stops appearing in list threads with awaiting reply=true. A reply sent only to clear the flag mails a person for bookkeeping; this clears it without one. The next message they send flags the thread again.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Thread id"
}
},
"additionalProperties": false
}
list_templates
List stored email templates and the variables each one needs. Unlike HTML composed at send time, templates carry the workspace's reviewed subject, copy and styling. They do not carry the unsubscribe footer: that is added at send time to marketing mail, whether or not it came from a template.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
render_template
Render a template with values, without sending, showing how the copy reads before it mails a real person. A missing variable answers 422 missing variables with the list in missing ; an unknown slug answers 404. Returns subject, html and text; text is null when the template has no plain-text part.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"slug",
"variables"
],
"properties": {
"slug": {
"type": "string"
},
"variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
}
send_template_email
Send an email built from a stored template. Variable values are HTML-escaped on substitution, so they are safe to fill from user-supplied text. Nothing is sent when a value is missing: 422 missing variables lists the names in missing , and a call with those filled in goes through (render template checks this without sending). An unknown slug answers 422 invalid request. The response has the same fields as send email: id, status, thread id, scheduled at, skipped, reason and approval id. Refusals, by type: 422 no verified identity (the From domain has no verified sending domain; a retry answers
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"template",
"variables",
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "Recipient address, or 'Name <address>' to show their name"
},
"from": {
"type": "string"
},
"subject": {
"type": "string",
"description": "Overrides the template's subject"
},
"template": {
"type": "string",
"description": "Template slug"
},
"variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"scheduled_at": {
"type": "string"
},
"idempotency_key": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Optional. Any unique string for this one message, e.g. 'welcome-ana-2026-09-15'. Retrying with the same key and the identical arguments returns the first answer instead of sending again. A key reused for a different message is refused with 422 idempotency_key_reused and nothing is sent. 409 idempotency_in_progress means the first attempt is still running; a retry with the same key a few seconds later returns its answer"
}
},
"additionalProperties": false
}
list_pending_approvals
List messages held for human approval, with their full content. A key configured to require approval drafts rather than sends; a person releases it. A send that returned status 'pending approval' is waiting here, and retrying the send does not release it. Oldest first, each with its expires at; an expired approval drops out of the list and can no longer be decided.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
decide_approval
Approve or reject a held message. Approving releases it: it sends now, or at its scheduled at when the draft was scheduled for later. If every recipient unsubscribed or was suppressed while it waited, nothing is sent and the answer says skipped: true with a reason (both always present: false and null otherwise, beside scheduled at). The approval hold exists so that a person, not an agent, makes this decision; decided by records the person who authorised it. The API enforces that with 403 forbidden for: a client connected by signing in (an OAuth access token, which is how a remote MCP connectio
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"decision",
"decided_by"
],
"properties": {
"id": {
"type": "string",
"description": "The approval's id from list_pending_approvals, not the message_id"
},
"reason": {
"type": "string",
"maxLength": 500
},
"decision": {
"enum": [
"approve",
"reject"
],
"type": "string"
},
"decided_by": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Who authorised this decision"
}
},
"additionalProperties": false
}
list_automations
List multi-step email sequences and how many people are currently in each, with the id each one is enrolled by. Newest first, at most 100 per call; while has more is true, next cursor passed back as cursor returns the next page. A 'paused' automation holds its people on their current step rather than ending their sequence: they stay 'active' and continue from that step once it is active again. list automation enrollments lists who is on one, and who left and why.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
}
},
"additionalProperties": false
}
get_automation
Fetch one automation: its status, trigger, steps, exit rules and how many people are in each state. The same object list automations returns, for a caller that already holds the id. People themselves are listed by list automation enrollments. An unknown automation id answers 404 not found; a name or slug passed instead is answered with the matching id.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id"
],
"properties": {
"automation_id": {
"type": "string",
"description": "The automation's id from list_automations (a UUID), not its name or slug"
}
},
"additionalProperties": false
}
list_automation_enrollments
The people in one automation, newest enrolment first: each row has the email, status, current step, next due at and, for a cancelled one, cancel reason. It answers 'is this person still on the sequence?', 'who is waiting on step 2?' and 'why did this sequence stop for them?', which find contact and list emails do not. status narrows to one state: 'active' (still going, including people held while the automation is paused), 'completed', 'failed', or 'canceled' for everyone who left early, where cancel reason says why (unsubscribed, unsubscribed from topic, replied, suppressed, exit tag, require
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
},
"status": {
"enum": [
"active",
"completed",
"canceled",
"failed"
],
"type": "string",
"description": "Only enrolments in this state; all when omitted"
},
"automation_id": {
"type": "string",
"description": "The automation's id from list_automations (a UUID), not its name or slug"
}
},
"additionalProperties": false
}
create_automation
Define a multi-step sequence as a draft; nothing is sent until it is activated, from the dashboard or with set automation status. Unlike several separately scheduled emails, it ends on its own when the person unsubscribes, replies, bounces, opts out of its topic, or their tags say so. identity id must be a marketing sending domain (see list sending domains; risk class 'marketing') and from must sit on it; both are checked here rather than at the first send. reply to sends replies somewhere other than from, and it disables the reply exit: SendRaven never sees mail sent to another domain. Every
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"slug",
"identity_id",
"from",
"trigger",
"steps"
],
"properties": {
"from": {
"type": "string",
"minLength": 3,
"description": "On the identity's domain, e.g. 'Ana <ana@news.example.com>'"
},
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"slug": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"description": "Lowercase letters, digits and hyphens"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"delay_minutes",
"subject"
],
"properties": {
"html": {
"type": "string",
"description": "Inline body; template_slug is the alternative. One of the two is required"
},
"subject": {
"type": "string",
"maxLength": 998,
"minLength": 1
},
"delay_minutes": {
"type": "integer",
"maximum": 525600,
"minimum": 0,
"description": "From enrolment for the first step, from the previous step for the rest. At most 525600 (one year)"
},
"template_slug": {
"type": "string",
"minLength": 1,
"description": "A template from list_templates, rendered with the enrolment's variables. Must already exist"
}
},
"additionalProperties": false
},
"maxItems": 20,
"minItems": 1
},
"trigger": {
"type": "object",
"required": [
"kind"
],
"properties": {
"tag": {
"type": "string",
"maxLength": 60,
"minLength": 1,
"description": "Required for tag_added, e.g. audio-player. Normalised like contact tags"
},
"kind": {
"enum": [
"api",
"contact_added",
"event",
"tag_added"
],
"type": "string",
"description": "api: enrol with enroll_in_automation. contact_added: starts when someone joins audience_id. event: starts on emit_event with event_name. tag_added: starts when a contact gains tag (tag_contact, or a contact added carrying it); a contact that already had the tag starts nothing, so turning it on does not mail everyone tagged"
},
"event_name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Required for event, e.g. trial_started. Up to 120 characters, matched exactly"
},
"audience_id": {
"type": "string",
"description": "Required for contact_added; the audience's id, not its name"
}
},
"additionalProperties": false
},
"reply_to": {
"type": "string",
"description": "Where replies go instead of from, e.g. the founder's own inbox. SendRaven receives mail for its own domains only, so with a reply-to elsewhere a reply cannot stop the sequence, however exit_on_reply is set"
},
"exit_tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 20,
"description": "Contact tags that end the sequence: nobody carrying one is enrolled, and adding one ends the enrolment. A trial sequence with exit tag 'customer' stops for someone tagged 'customer' when they upgrade"
},
"topic_key": {
"type": "string",
"minLength": 1,
"description": "Send every step under this topic (see list_topics). Its unsubscribe link then opts the person out of this kind of mail only, and opting out ends the sequence. Must be an existing topic's key; an unknown one is refused with 422 unknown_topic"
},
"identity_id": {
"type": "string",
"description": "A marketing sending domain's id from list_sending_domains (a UUID), not the domain name"
},
"reenrollment": {
"enum": [
"after_completion",
"never"
],
"type": "string",
"description": "after_completion (the default): someone whose enrolment completed or was cancelled can be enrolled again. never: each person goes through it once, and a later enrolment answers enrolled: false with reason previously_enrolled. never suits onboarding or a one-time offer, where a second run would mail someone the same sequence twice"
},
"exit_on_reply": {
"type": "boolean",
"description": "End the enrolment when the person replies. Defaults to true; false suits dunning"
},
"required_tags": {
"type": "array",
"items": {
"$ref": "#/properties/exit_tags/items"
},
"maxItems": 20,
"description": "Tags a person must keep: only people carrying all of them are enrolled, and removing one ends the enrolment. Someone with no contact record has no tags, so is never enrolled"
},
"default_variables": {
"type": "object",
"description": "Template values every enrolment gets, under the variables an enrolment passes (which win). Required for contact_added and tag_added, which enrol with no values: every placeholder in the steps' subjects, html and templates needs one here, or the call answers 422 missing_variables naming the missing ones. Read at each step, so a fix reaches people already enrolled",
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
}
update_automation
Change the rules that take someone out of a sequence (topic key, exit tags, required tags, exit on reply), its reply to, its reenrollment, or its default variables (replaces the whole set; {} clears it). Steps and the trigger are fixed once created. A reenrollment change applies from the next enrolment; nobody already enrolled is touched. Fields left out keep their value; a null topic key or reply to, or an empty tag list, clears it. People already enrolled see the change from their next step, so a mistaken edit can be put back before it has ended anyone's sequence. Clearing reply to has repli
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id"
],
"properties": {
"reply_to": {
"type": [
"string",
"null"
],
"description": "Where replies go instead of from, e.g. the founder's own inbox. SendRaven receives mail for its own domains only, so with a reply-to elsewhere a reply cannot stop the sequence, however exit_on_reply is set"
},
"exit_tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 20,
"description": "Contact tags that end the sequence: nobody carrying one is enrolled, and adding one ends the enrolment. A trial sequence with exit tag 'customer' stops for someone tagged 'customer' when they upgrade"
},
"topic_key": {
"anyOf": [
{
"anyOf": [
{
"not": []
},
{
"type": "string",
"minLength": 1
}
],
"description": "Send every step under this topic (see list_topics). Its unsubscribe link then opts the person out of this kind of mail only, and opting out ends the sequence. Must be an existing topic's key; an unknown one is refused with 422 unknown_topic"
},
{
"type": "null"
}
],
"description": "Send every step under this topic (see list_topics). Its unsubscribe link then opts the person out of this kind of mail only, and opting out ends the sequence. Must be an existing topic's key; an unknown one is refused with 422 unknown_topic"
},
"reenrollment": {
"enum": [
"after_completion",
"never"
],
"type": "string",
"description": "after_completion (the default): someone whose enrolment completed or was cancelled can be enrolled again. never: each person goes through it once, and a later enrolment answers enrolled: false with reason previously_enrolled. never suits onboarding or a one-time offer, where a second run would mail someone the same sequence twice"
},
"automation_id": {
"type": "string",
"description": "The automation's id from list_automations (a UUID), not its name or slug"
},
"exit_on_reply": {
"type": "boolean",
"description": "End the enrolment when the person replies. Defaults to true; false suits dunning"
},
"required_tags": {
"type": "array",
"items": {
"$ref": "#/properties/exit_tags/items"
},
"maxItems": 20,
"description": "Tags a person must keep: only people carrying all of them are enrolled, and removing one ends the enrolment. Someone with no contact record has no tags, so is never enrolled"
},
"default_variables": {
"type": "object",
"description": "Template values every enrolment gets, under the variables an enrolment passes (which win). Required for contact_added and tag_added, which enrol with no values: every placeholder in the steps' subjects, html and templates needs one here, or the call answers 422 missing_variables naming the missing ones. Read at each step, so a fix reaches people already enrolled",
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
}
set_automation_status
Activate, pause or return an automation to draft. A new automation is a draft and sends nothing until it is set to 'active'. Pausing ('paused' or 'draft') holds everyone on their current step: nobody is sent a step and nobody new is enrolled, but nobody's sequence ends, and setting 'active' again continues each person from where they were, with steps that came due meanwhile going out from the next worker run at the usual pace. A step's content is read when it is sent, so a paused automation's steps can be fixed without deleting it. Activating does not re-check the sending domain; if it is no l
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id",
"status"
],
"properties": {
"status": {
"enum": [
"active",
"paused",
"draft"
],
"type": "string"
},
"automation_id": {
"type": "string",
"description": "The automation's id from list_automations (a UUID), not its name or slug"
}
},
"additionalProperties": false
}
enroll_in_automation
Put someone into a multi-step sequence. Unlike several separately scheduled emails, the sequence stops on its own if they unsubscribe (from everything or from the automation's topic), reply, hard bounce, gain one of its exit tags, or lose one of its required tags, which would otherwise have to be tracked and cancelled by hand. A sequence stops for someone who converted when the contact is tagged with an exit tag; nothing needs cancelling. Enrolling the same person twice is a no-op, so a retry is harmless. The answer always carries enrolled, reason and enrollment: enrolled: true with reason nul
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"automation_id",
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"variables": {
"type": "object",
"description": "Values for any templated steps in the sequence",
"additionalProperties": {
"type": "string"
}
},
"automation_id": {
"type": "string",
"description": "The automation's id from list_automations (a UUID), not its name or slug"
}
},
"additionalProperties": false
}
emit_event
Emit a named event, starting every automation that waits on it — for example 'trial started' or 'invoice overdue'. The configured sequences decide what happens, rather than the caller naming an automation. Returns automations started; 0 means nothing was waiting on that name or the person was excluded. The calling key's guardrails apply as for enroll in automation, before anything is looked up: a key that holds its sends for approval gets 403 forbidden, and a key with a recipient allowlist gets 403 recipient not allowed for an address not on it.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name",
"email"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Event name, e.g. trial_started"
},
"email": {
"type": "string",
"format": "email"
},
"variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
}
list_topics
List subscription topics — the categories a person can opt out of individually. Marketing mail sent under a topic lets recipients unsubscribe from that kind alone rather than from everything.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
get_email_preferences
What one person has chosen to receive. It shows whether someone who isn't getting a particular kind of email opted out of it — an opt-out looks identical to a delivery failure from the outside.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": false
}
set_email_preferences
Set which topics a person receives, recording what they asked for — silently re-subscribing someone who opted out is what generates spam complaints. Every key must be an existing topic from list topics: one unknown key refuses the whole call with 422 unknown topic and nothing is saved. Setting a topic to false also ends any automation enrolment sent under that topic.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"topics"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"topics": {
"type": "object",
"description": "Topic key to subscribed, e.g. {\"newsletter\": false}",
"additionalProperties": {
"type": "boolean"
}
}
},
"additionalProperties": false
}
list_audiences
List contact lists, newest first, with each one's id and contact count. Paged: at most 100 per call; while has more is true, more lists are on later pages, returned when next cursor is passed back as cursor.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
}
},
"additionalProperties": false
}
add_contact
Add someone to an audience. A contact exists once per workspace and can be on any number of audiences, so adding an address that already exists joins them to this list rather than creating a second copy. status records that the person opted out elsewhere — it writes the suppression as well as the flag, and an add never resubscribes someone who opted out here. Someone new to the audience starts any automation triggered by joining it; re-adding an existing member starts nothing. A retry has the same result. import contacts adds up to 5,000 people in one call.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"audience_id",
"email"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 50,
"description": "Flat labels; lower-cased, spaces become hyphens"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"enum": [
"subscribed",
"unsubscribed",
"bounced",
"complained"
],
"type": "string",
"description": "Standing with the previous sender. unsubscribed suppresses for marketing; bounced and complained suppress for everything. Defaults to subscribed."
},
"last_name": {
"type": "string",
"maxLength": 120
},
"attributes": {
"type": "object",
"description": "Custom properties by key. An unknown key creates a string property.",
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
"first_name": {
"type": "string",
"maxLength": 120
},
"audience_id": {
"type": "string",
"description": "The audience's id from list_audiences (a UUID), not its name. list_audiences maps each name to its id."
},
"last_active_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 time the person was last active in your product (a login, a session). Counted by a segment's engaged_within_days. Kept only if later than the stored value."
}
},
"additionalProperties": false
}
import_contacts
Import up to 5,000 contacts into an audience in one call, with names, tags, custom properties and subscription status. This is the migration tool: the previous provider's unsubscribed, bounced and complained lists, imported with the matching status before the first campaign, keep the new domain from mailing people who opted out, which loses a domain its reputation in a day. Existing contacts are updated rather than duplicated, and nobody who opted out here is resubscribed, so re-running an import is safe. Returns counts: inserted, updated, skipped, unsubscribed, bounced, complained, suppressed
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"audience_id",
"contacts"
],
"properties": {
"source": {
"type": "string",
"description": "Where the list came from, e.g. \"Mailchimp\" — recorded on each suppression"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"email"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 50,
"description": "Flat labels; lower-cased, spaces become hyphens"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"enum": [
"subscribed",
"unsubscribed",
"bounced",
"complained"
],
"type": "string",
"description": "Standing with the previous sender. unsubscribed suppresses for marketing; bounced and complained suppress for everything. Defaults to subscribed."
},
"last_name": {
"type": "string",
"maxLength": 120
},
"attributes": {
"type": "object",
"description": "Custom properties by key. An unknown key creates a string property.",
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
"first_name": {
"type": "string",
"maxLength": 120
},
"last_active_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 time the person was last active in your product (a login, a session). Counted by a segment's engaged_within_days. Kept only if later than the stored value."
}
},
"additionalProperties": false
},
"maxItems": 5000,
"minItems": 1
},
"audience_id": {
"type": "string",
"description": "The audience's id from list_audiences (a UUID), not its name. list_audiences maps each name to its id."
},
"trigger_automations": {
"type": "boolean",
"description": "Start automations triggered by joining this audience for everyone new to it. Off by default: a migrated list is not new signups, and a welcome sequence to all of it at once is a cold blast that burns the sending domain. It is meant for genuinely new people."
}
},
"additionalProperties": false
}
get_contact
Fetch one contact by id, with their audience memberships, custom properties and engagement dates.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}
update_contact
Update a contact. Attributes are merged, so sending one field does not clear the rest. unsubscribed: true is a real opt-out: it suppresses the address for marketing, cancels their pending sends and ends their automation enrolments. unsubscribed: false lifts a marketing unsubscribe, which is for a person who asked to be resubscribed. Resubscribing someone who hard bounced or complained is refused with 409 invalid state before anything in the request is written.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The contact's id (a UUID) from find_contact, add_contact or get_contact — not the email address. find_contact returns the id for an address."
},
"last_name": {
"type": "string",
"maxLength": 120
},
"attributes": {
"type": "object",
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
"first_name": {
"type": "string",
"maxLength": 120
},
"unsubscribed": {
"type": "boolean",
"description": "true to opt them out of marketing, false to undo an unsubscribe"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "ISO 8601 time of their last activity in your product. Only moves forward; null clears it."
}
},
"additionalProperties": false
}
list_segments
List saved audience filters. A campaign created with a segment id, rather than a filter described inline, shares one definition that can be reused and counted.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
list_tags
Every tag in use in the workspace, with how many contacts carry each. Tags are free-form, so this is the only way to know what exists before applying one.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
count_segment
How many contacts a segment currently matches. A filter that matches nobody shows up here as 0, before any campaign is built around it or sent.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}
get_email_metrics
Delivery and engagement over a window. Open and click rates are over delivered, not sent — a low open rate with a high bounce rate is a deliverability problem, not an engagement one.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Defaults to 30"
}
},
"additionalProperties": false
}
list_scheduled_emails
Messages queued to send later but not yet sent, newest first; cancel scheduled email cancels one. At most 100 per call; while has more is true, next cursor passed back as cursor returns the next page.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
}
},
"additionalProperties": false
}
suppress_many
Stop sending to many addresses at once — the path for importing another provider's unsubscribe list before a first campaign. Without it, everyone who already opted out there gets mailed again here. The defaults differ from add suppression: scope 'marketing' and reason 'list hygiene'. reason 'unsubscribe' marks a list of opt-outs, and also cancels their queued scheduled sends and ends their automation enrolments. Addresses are de-duplicated; the response counts suppressed and duplicates.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"emails"
],
"properties": {
"scope": {
"enum": [
"all",
"transactional",
"marketing"
],
"type": "string",
"description": "Defaults to marketing"
},
"emails": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"maxItems": 10000,
"minItems": 1
},
"reason": {
"enum": [
"manual",
"list_hygiene",
"unsubscribe"
],
"type": "string",
"description": "Defaults to list_hygiene. unsubscribe also cancels queued mail and ends enrolments"
}
},
"additionalProperties": false
}
list_webhook_deliveries
Recent delivery attempts for a webhook endpoint: each with event, status, attempts, last status code, last error and delivered at (null until it succeeds). This is what tells 'we never sent it' from 'your endpoint returned 500'. Newest first, the most recent limit only; not paged.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"endpoint_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "1 to 200; defaults to 50"
},
"endpoint_id": {
"type": "string"
}
},
"additionalProperties": false
}
list_broadcast_recipients
Who a campaign reached and what happened to each message, with the A/B variant when there is one. At most 200 per call; while has more is true, next cursor (a message id) passed back as cursor returns the next page.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The campaign's id from create_broadcast or list_broadcasts (a UUID), not its name"
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Page size, 1 to 200; defaults to 200"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, passed back unchanged"
}
},
"additionalProperties": false
}
get_usage
This workspace's plan, what it has sent this billing period, what the period costs so far, and — the fields worth branching on — sending locked and lock reason, which name the exact 402 a send would be refused with right now, before a large batch or campaign is tried: on Free a send that would cross the 3,000 included emails is refused whole, and a workspace with no verified payment method cannot send at all, on any plan. lock reason payment method required is the one no tool can fix: only a person can add a payment method, in the dashboard. Pricing is one meter, outbound emails sent: contacts
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": []
}
find_contact
Find a contact by address across every audience, without knowing which list they are on, or list the workspace's contacts by tag or subscription. email matches exactly, and q matches an address prefix. A person exists once per workspace, so each row is one contact with audience ids listing every list they are on, first name, last name, tags, attributes and whether they are unsubscribed. Newest first, at most 100 per call; while has more is true, next cursor passed back as cursor with the same filters returns the next page.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"q": {
"type": "string",
"description": "Address prefix, for a partial match. Ignored when email is given"
},
"tag": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only contacts carrying every one of these tags (see list_tags)"
},
"email": {
"type": "string",
"description": "Exact address"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size, 1 to 100; defaults to 50"
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous call, passed back unchanged"
},
"unsubscribed": {
"type": "boolean",
"description": "Filter to only opted-in or only opted-out"
}
},
"additionalProperties": false
}
remove_from_audience
Take a contact off one audience. They stay in the workspace and keep every other audience, their suppression and their engagement history. delete contact removes the person entirely — leaving a list and being forgotten are different things.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"audience_id",
"contact_id"
],
"properties": {
"contact_id": {
"type": "string",
"description": "The contact's id (a UUID) from find_contact, add_contact or get_contact — not the email address. find_contact returns the id for an address."
},
"audience_id": {
"type": "string",
"description": "The audience's id from list_audiences (a UUID), not its name. list_audiences maps each name to its id."
}
},
"additionalProperties": false
}
delete_contact
Remove a person from the workspace entirely, along with every audience membership. Their suppression and topic preferences are kept on purpose — an opt-out has to outlive the contact record, or the next import silently puts them back on the list. remove from audience takes someone off a single audience instead.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contact_id"
],
"properties": {
"contact_id": {
"type": "string",
"description": "The contact's id (a UUID) from find_contact, add_contact or get_contact — not the email address. find_contact returns the id for an address."
}
},
"additionalProperties": false
}
tag_contact
Add or remove tags on a contact. Tags are flat labels — vip, beta, churned — as opposed to custom properties, which are declared fields with a value. They are lower-cased and spaces become hyphens, so VIP and vip are the same tag. Tagging reaches the person across every audience they are on. list tags returns the tags the workspace already uses, so an existing tag can be reused rather than a synonym created. Adding a tag an automation exits on (e.g. customer), or removing one it requires (e.g. trial), ends the person's enrolment in it at once. Adding a tag the contact did not already carry sta
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contact_id"
],
"properties": {
"add": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 50
},
"remove": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 50
},
"contact_id": {
"type": "string",
"description": "The contact's id (a UUID) from find_contact, add_contact or get_contact — not the email address. find_contact returns the id for an address."
}
},
"additionalProperties": false
}