Skip to main content
The fastest way to explore the SendWhale API is to make a read request against the Brand Context API. This endpoint returns your workspace’s brand data — name, voice, colors, fonts, and more — and requires only a brand read key, which is safe to create and rotate without affecting any live campaigns or contacts.
This quickstart uses the Brand Context API because it is a read-only, low-risk operation. Brand read keys cannot send mail, read contact lists, or modify campaigns. They are a safe starting point for exploring SendWhale’s developer surface.
1

Get your Workspace ID

Your Workspace ID is required on every API request. To find it:
  1. Sign in to SendWhale.
  2. Open your workspace Settings.
  3. Navigate to the Agent Access tab.
  4. Copy the Workspace ID displayed at the top of the page.
Your Workspace ID looks similar to ws_abc123. Keep it handy — you will use it in every API call.
2

Create a brand read key

Brand read keys authenticate requests to the Brand Context API. To create one:
  1. In workspace Settings → Agent Access, click Create Key.
  2. Give the key a descriptive name (for example, my-first-api-test).
  3. Click Create and copy the key immediately — it is only shown once.
Never expose your brand key in client-side code, public repositories, or anywhere else outside a secure server-side environment. If a key is compromised, revoke it immediately from Settings → Agent Access and create a replacement.
Brand read keys expire after 90 days. Set a reminder to revoke and replace the key before it expires to avoid disruption to any integrations that depend on it.
3

Make a read request to the Brand Context API

With your Workspace ID and brand read key ready, run the following command in your terminal. Replace <YOUR_BRAND_KEY> and <YOUR_WORKSPACE_ID> with the values you copied in the previous steps.
A successful request returns an HTTP 200 response with a JSON body. Common errors:
4

Review the response

The response body contains your workspace’s brand context object. It includes fields such as:
  • name — your workspace or brand name
  • description — a short description of your brand
  • voice — brand voice and tone guidelines
  • colors — primary and secondary brand colors
  • fonts — preferred font choices
  • social — social media profile links
  • knowledge — brand knowledge base entries
This is the same brand context that Swell, SendWhale’s AI campaign assistant, uses when drafting emails on your behalf. By reading it through the API, you can give any external AI tool or integration accurate, up-to-date brand information.
5

Use this data in your integrations

Now that you can read brand context programmatically, you can:
  • Feed it as a system prompt to an AI model in your own application.
  • Cache it server-side and refresh it before your 90-day key expires.
  • Use the MCP server to give an AI client like Claude Desktop direct, live access to this data alongside campaign management tools.
To go further, explore the API Reference for campaign and contact operations, or set up Webhooks to receive real-time delivery event notifications.