Skip to main content
The SendWhale MCP server exposes 11 tools for interacting with your workspace. Four tools are read-only and require at minimum the Viewer role. Seven tools perform writes and require Editor, Admin, or Owner role depending on the operation. All tools return a structured response in the format below.
On failure, ok is false, data is null, and error contains a machine-readable error code. Some errors also include a details field with additional context.

​
Read-only tools

​
list_campaigns

Lists campaigns in your workspace. Results are paginated. Recipient addresses are never included in list responses.
​
string
required
Your SendWhale workspace ID.
​
number
Page number to return. Defaults to 1.
​
number
Number of results per page. Defaults to the server maximum.
Response data:
​
Campaign[]
Array of campaign summary objects.
​
number
Total number of campaigns in the workspace.
​
number
Current page number.

​
list_templates

Lists email templates in your workspace. Results are paginated.
​
string
required
Your SendWhale workspace ID.
​
number
Page number to return. Defaults to 1.
​
number
Number of results per page.
Response data:
​
Template[]
Array of template summary objects.
​
number
Total number of templates in the workspace.
​
number
Current page number.

​
list_audiences

Lists audiences in your workspace. Results are paginated. Contact details and recipient addresses are never returned.
​
string
required
Your SendWhale workspace ID.
​
number
Page number to return. Defaults to 1.
​
number
Number of results per page.
Response data:
​
Audience[]
Array of audience summary objects (name, ID, contact count).
​
number
Total number of audiences in the workspace.
​
number
Current page number.

​
get_campaign

Retrieves the full details of a single campaign by ID, including content, status, subject, sender, and metadata.
​
string
required
Your SendWhale workspace ID.
​
string
required
The ID of the campaign to retrieve.
Response data: a campaign object containing content, status, subject line, sender information, audience reference, and updated_at.

​
Write tools

​
create_audience

Creates a new, empty audience in your workspace. This tool does not add contacts — it only creates the audience container.
​
string
required
Your SendWhale workspace ID.
​
string
required
Display name for the new audience.
​
string
Optional description of the audience.
Response data: the created audience object including its new ID.

​
create_email_template

Creates a new email template in your workspace.
​
string
required
Your SendWhale workspace ID.
​
string
required
Display name for the template.
​
string
required
Default subject line for the template.
​
string
required
Full HTML content of the email template.
Response data: the created template object including its ID and updated_at.

​
create_campaign_draft

Creates a new campaign in draft status. This tool never sends or schedules a campaign.
​
string
required
Your SendWhale workspace ID.
​
string
required
Internal name for the campaign.
​
string
required
Subject line for the campaign email.
​
string
ID of an existing template to attach to this draft.
​
string
ID of the audience to target with this campaign.
Response data: the created campaign draft object, including its ID and updated_at. Save updated_at — you will need it to call update_campaign_draft.

​
update_campaign_draft

Updates an existing campaign draft. You must supply the current updated_at value to prevent overwriting concurrent edits. Locked campaigns and campaigns that are not in draft status cannot be modified.
​
string
required
Your SendWhale workspace ID.
​
string
required
The ID of the draft campaign to update.
​
string
required
The updated_at timestamp from your last read of this campaign. Used as a concurrency guard.
​
string
Updated subject line.
​
string
Updated HTML email content.
Response data: the updated campaign object with a new updated_at value. Conflict error: if the updated_at you send does not match the current version stored on the server, the tool returns:
Call get_campaign to retrieve the latest version, re-apply your changes, and retry.

​
remember_brand_fact

Saves a durable brand fact to your workspace’s memory store. Facts persist across sessions and are available to AI clients reading workspace brand context. Requires owner or admin role.
​
string
required
Your SendWhale workspace ID.
​
string
required
The brand fact to store (e.g., “Our brand voice is warm, direct, and never uses jargon.”).
​
string
Optional category to organise the fact (e.g., voice, design, product).
Response data: the saved memory object including its ID and timestamp.

​
update_brand_instructions

Updates persistent brand instructions for your workspace. These instructions are used as design references or AI directions when generating content. Requires owner or admin role.
​
string
required
Your SendWhale workspace ID.
​
string
required
The updated instruction text.
​
string
Optional instruction type or category (e.g., design, tone, layout).
Response data: the updated instructions record.

​
save_image_to_library

Validates a publicly accessible image URL and copies it into your workspace image library. The URL must be publicly reachable — private IPs, localhost URLs, and URLs requiring authentication are rejected.
​
string
required
Your SendWhale workspace ID.
​
string
required
A publicly accessible URL pointing to the image to save.
​
string
Optional display name for the image in the library.
Response data: the saved image object, including the workspace storage URL you can reference in templates. Invalid URL error: if the URL is private, inaccessible, or invalid, the tool returns:
Test the URL in a browser before passing it to this tool.
The write tools create_campaign_draft and update_campaign_draft never send or schedule a campaign. Always open the campaign in SendWhale’s UI to complete preflight checks and confirm delivery before any email is sent.