Zinn® Campaigns API and MCP: developer guide

Everything you can do in Zinn® Campaigns on the dashboard you can also do through the API, and most of it from an AI assistant connected to your account over MCP. This guide covers signing in, the permissions, a worked example both ways, the limits, the errors and every one of the 89 Campaigns operations. The operation list below is generated from our API specification, so it always matches what the API does. Every field of every operation is in the API reference at zinndigital.com/developers/api/zinn-campaigns.

Signing in

• API keys. Create a key in the dashboard under Settings → API keys and send it as Authorization: Bearer zdk_live_… (a zdk_test_… key works in sandbox mode). Give the key the Campaigns permissions it needs and nothing more.
• AI assistants (MCP). Connect Claude, ChatGPT, Cursor or any MCP client to https://api.zinndigital.com/v1/mcp, either by signing in from the app or with a connection token (zmcp_live_…). See Connecting Claude, Cursor or ChatGPT to your account. On the consent screen, tick the Zinn® Campaigns permissions.
• Permissions. email_marketing.view reads campaigns, lists, contacts, forms, senders, SMS settings and reports; email_marketing.manage creates and changes them. The campaigns you send through your own email service use campaigns.view and campaigns.manage.
• Resellers. Pass org_id to act on one of your client organisations. Leave it out when your key or connection reaches exactly one organisation.

Example: create a draft campaign with the API

curl -X POST https://api.zinndigital.com/v1/email-marketing/campaigns \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring sale",
  "subject": "Our spring sale starts today",
  "list_id": "<list id>",
  "sender_id": "<sender id>",
  "template": "basic"
}'

The answer is 201 with the draft. Test it with POST /v1/email-marketing/campaigns/{campaign_id}/test, check it with GET /v1/email-marketing/campaigns/{campaign_id}/lint, and send it with POST /v1/email-marketing/campaigns/{campaign_id}/send.

Example: the same draft from an AI assistant

Ask your assistant in plain words, for example "draft a Zinn® Campaigns email called Spring sale with the subject 'Our spring sale starts today'". Behind the scenes it finds the operation with api_operations_search, reads its parameters with api_operation_get, and runs it with api_operation_call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "api_operation_call",
    "arguments": {
      "operation_id": "createEmailMarketingCampaign",
      "confirm": true,
      "body": {
        "name": "Spring sale",
        "subject": "Our spring sale starts today"
      }
    }
  }
}

What an assistant will not do. Anything that sends to your recipients or spends money or allowance — sending a campaign, sending SMS or WhatsApp messages, writing with AI credits, registering for US texting — is refused to an assistant, so a misunderstood instruction can never reach your customers. The assistant prepares the draft; you press Send in the dashboard or call the API yourself. Secrets such as an SMTP password are also never passed through an assistant: enter them in the dashboard.

Limits

• 1,200 requests a minute for each person or API key, and 6,000 requests a minute for each organisation. The tighter of the two applies.
• 600 requests a minute for each MCP connection.
• Over a limit, the answer is 429 with a Retry-After header: wait that many seconds.
• Adding list members takes at most 1,000 addresses a request; your plan's contact and email allowances apply to everything you do through the API.

Errors

Every error has the same shape:

{"error": {"code": "UNPROCESSABLE_ENTITY", "message": "…", "details": [{"field": "subject", "code": "REQUIRED", "message": "…"}], "request_id": "…"}}

code never changes for the same problem, so test it rather than message. Quote request_id when you contact support. The answers you will meet: 401 UNAUTHORIZED, 403 FORBIDDEN, 404 NOT_FOUND, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 429 TOO_MANY_REQUESTS. A 403 means the key or connection lacks a permission the list below names; a 404 also covers something in an organisation you cannot see; a 422 lists each wrong field in details; after a 429, wait the number of seconds in the Retry-After header.

Webhooks

Delivery results come into Zinn® Campaigns from the provider that sends your email:

• With your own provider (for example Resend), store its webhook signing secret on the sending connection in the dashboard (Campaigns → Sending). You get a webhook_url; point the provider's delivered, bounced and complained events at it. A bounce or a spam complaint removes the address from future sends at once.
• With Zinn® sending, there is nothing to set up.

Read the results with the report operations (getEmailMarketingCampaignReport, getSmsMarketingCampaignReport).

Every Campaigns operation

Overview

• GET /v1/email-marketing — Zinn® Campaigns overview for one organisation. Operation getEmailMarketingOverview. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.

Email campaigns

• GET /v1/email-marketing/campaigns — E-mail campaigns, newest first, one keyset page. Operation listEmailMarketingCampaigns. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/campaigns — Create a draft e-mail campaign. Operation createEmailMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/campaigns/{campaign_id} — One e-mail campaign. Operation getEmailMarketingCampaign. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• PATCH /v1/email-marketing/campaigns/{campaign_id} — Edit a draft (or a refused campaign, which returns to draft). Operation updateEmailMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/campaigns/{campaign_id}/lint — Check a campaign's copy for deliverability problems before it is sent. Operation lintEmailMarketingCampaign. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/campaigns/{campaign_id}/report — A campaign's numbers. Operation getEmailMarketingCampaignReport. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/campaigns/{campaign_id}/send — Start sending a campaign to its list. Operation sendEmailMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (sends to real recipients and spends allowance).
• POST /v1/email-marketing/campaigns/{campaign_id}/test — Send one test copy now to a member of the organisation. Operation testEmailMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/campaigns/{campaign_id}/translate — Translate a campaign into every contact language that is missing or stale. Operation translateEmailMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/campaigns/{campaign_id}/translations — Each contact language of a campaign's list and whether its translation is current. Operation listEmailMarketingCampaignTranslations. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.

Writing with AI

• POST /v1/email-marketing/ai/write — Write a draft campaign email from a short brief with Zinn® AI. Operation writeEmailMarketingCampaignWithAi. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (AI writing spends AI credits).

Brand kit

• GET /v1/email-marketing/brand-kit — The organisation's brand kit (name, logo, colours, font, voice). Operation getEmailMarketingBrandKit. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• PUT /v1/email-marketing/brand-kit — Edit the brand kit. Operation updateEmailMarketingBrandKit. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/brand-kit/read — Read the brand kit from the organisation's website. Operation readEmailMarketingBrandKit. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.

Contacts and one-off messages

• GET /v1/email-marketing/contacts — The organisation's contacts, one keyset page at a time. Operation listEmailMarketingContacts. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/contacts/{contact_id}/messages — Send one SMS to one contact, paid from the Zinn® credit balance. Operation sendEmailMarketingMessage. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (a one-off message to a contact spends allowance).
• GET /v1/email-marketing/messages — SMS and WhatsApp messages the organisation sent, newest first, one keyset page. Operation listEmailMarketingMessages. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.

Lists

• GET /v1/email-marketing/lists — The organisation's mailing lists with subscribed / unsubscribed counts. Operation listEmailMarketingLists. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/lists — Create a mailing list (or return the one with that name). Operation createEmailMarketingList. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/lists/{list_id}/members — Add contacts to a list by e-mail address (at most 1,000 a request). Operation addEmailMarketingListMembers. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.

Imports

• GET /v1/email-marketing/imports — Past contact imports, newest first, one keyset page at a time. Operation listEmailMarketingImports. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/imports — Import one chunk of contacts with its consent attestation. Operation createEmailMarketingImport. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.

Sign-up forms

• GET /v1/email-marketing/forms — Sign-up forms (double opt-in), newest first, one keyset page. Operation listEmailMarketingForms. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/forms — Create a sign-up form that adds confirmed people to one list. Operation createEmailMarketingForm. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• DELETE /v1/email-marketing/forms/{form_id} — Delete a sign-up form (people already confirmed stay on the list). Operation deleteEmailMarketingForm. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• PATCH /v1/email-marketing/forms/{form_id} — Change a sign-up form (wording, list, redirect, on or off). Operation updateEmailMarketingForm. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.

Sending connections

• GET /v1/email-marketing/senders — The organisation's sending connections. Operation listEmailMarketingSenders. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/senders — Connect a campaign sender (Zinn® sending, or the customer's own SMTP server). Operation createEmailMarketingSender. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: API and dashboard only: it carries a secret that must never reach an AI model (the body is the SMTP password).
• DELETE /v1/email-marketing/senders/{sender_id} — Remove a sending connection and its stored password. Operation deleteEmailMarketingSender. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/senders/{sender_id}/verify — Prove a sending connection works, without sending anything. Operation verifyEmailMarketingSender. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• PUT /v1/email-marketing/senders/{sender_id}/webhook — Store your e-mail provider's webhook signing secret for this connection. Operation setEmailMarketingSenderWebhook. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: called by another system (a provider or a visitor), not by you (stores a provider's webhook secret).

SMS and WhatsApp

• GET /v1/email-marketing/sms — What the SMS screen needs — open?, paused?, credit balance and prices. Operation getEmailMarketingSms. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/sms/campaigns — Bulk SMS campaigns, newest first, one keyset page. Operation listSmsMarketingCampaigns. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/sms/campaigns — Create a draft SMS to a list. Operation createSmsMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/sms/campaigns/{campaign_id} — One bulk SMS campaign. Operation getSmsMarketingCampaign. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• PATCH /v1/email-marketing/sms/campaigns/{campaign_id} — Edit a draft (or a refused campaign, which returns to draft). Operation updateSmsMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/sms/campaigns/{campaign_id}/report — A bulk SMS campaign's numbers. Operation getSmsMarketingCampaignReport. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/sms/campaigns/{campaign_id}/send — Start sending an SMS to everyone on its list who agreed to SMS — or resume one paused for credit. Operation sendSmsMarketingCampaign. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (sends paid SMS/WhatsApp messages).
• GET /v1/email-marketing/sms/registrations/us — This organisation's US 10DLC registration, and what one costs. Operation getEmailMarketingUsRegistration. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/sms/registrations/us — Submit this organisation's brand and campaign for US 10DLC (charged on submit). Operation submitEmailMarketingUsRegistration. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (US 10DLC registration carries carrier fees).

Campaigns through your own email service (templates, segments, suppressions)

• GET /v1/campaigns — The organisation's campaigns. Operation listCampaigns. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns — Create a campaign from a template and an audience. Operation createCampaign. From an AI assistant: yes, through the MCP.
• DELETE /v1/campaigns/esp — Disconnect the provider account and remove its stored key. Operation disconnectEsp. From an AI assistant: API and dashboard only: it carries a secret that must never reach an AI model (destroys the stored ESP key).
• GET /v1/campaigns/esp — The organisation's own e-mail provider account. Operation getEspConnection. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/esp — Connect an e-mail provider account. Operation connectEsp. From an AI assistant: API and dashboard only: it carries a secret that must never reach an AI model (the body is the ESP API key).
• POST /v1/campaigns/esp/verify — Prove the provider account works and read its verified domains. Operation verifyEspConnection. From an AI assistant: API and dashboard only: it carries a secret that must never reach an AI model (re-checks a stored ESP key).
• POST /v1/campaigns/preview — Render a template with example values. Operation previewCampaignTemplate. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/segments — Your saved audience segments. Operation listCampaignSegments. Permissions checked: campaigns.view. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/segments — Save a new audience segment. Operation createCampaignSegment. Permissions checked: campaigns.manage. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/segments/fields — The filter vocabulary, its value lists and the magic tags. Operation getCampaignSegmentFields. Permissions checked: campaigns.view. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/segments/preview — How many people this reaches, who they are, and who it leaves out. Operation previewCampaignSegment. Permissions checked: campaigns.view. From an AI assistant: yes, through the MCP.
• DELETE /v1/campaigns/segments/{segmentId} — Archive a segment. Operation archiveCampaignSegment. Permissions checked: campaigns.manage. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/segments/{segmentId} — One saved segment. Operation getCampaignSegment. Permissions checked: campaigns.view. From an AI assistant: yes, through the MCP.
• PATCH /v1/campaigns/segments/{segmentId} — Rename a segment or change its filters. Operation updateCampaignSegment. Permissions checked: campaigns.manage. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/suppressions — Addresses that must not receive marketing. Operation listCampaignSuppressions. Permissions checked: campaigns.view. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/suppressions — Add an address to the suppression list. Operation createCampaignSuppression. Permissions checked: campaigns.manage. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/tags — The magic-tag palette a campaign composer offers. Operation listCampaignTags. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/templates — The organisation's campaign templates. Operation listCampaignTemplates. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/templates — Author a campaign template. Operation createCampaignTemplate. From an AI assistant: yes, through the MCP.
• DELETE /v1/campaigns/templates/{templateId} — Archive a template and retire its translation sources. Operation archiveCampaignTemplate. From an AI assistant: yes, through the MCP.
• GET /v1/campaigns/templates/{templateId} — One campaign template. Operation getCampaignTemplate. From an AI assistant: yes, through the MCP.
• PUT /v1/campaigns/templates/{templateId} — Edit a campaign template. Operation updateCampaignTemplate. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/unsubscribe — Leave a marketing list. No account needed. Operation unsubscribeFromCampaigns. From an AI assistant: API and dashboard only: it carries a secret that must never reach an AI model (takes a recipient's signed unsubscribe token).
• DELETE /v1/campaigns/{campaignId} — Delete a campaign and retire its delivery rows. Operation deleteCampaign. From an AI assistant: API and dashboard only: it needs a permission AI connections are not offered (deleting an ESP campaign needs campaigns.send).
• GET /v1/campaigns/{campaignId} — One campaign and its delivery report. Operation getCampaign. From an AI assistant: yes, through the MCP.
• POST /v1/campaigns/{campaignId}/control — Pause, resume or cancel a running send. Operation controlCampaign. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (pauses/resumes a live send).
• POST /v1/campaigns/{campaignId}/send — Start the durable send. Operation sendCampaign. From an AI assistant: API and dashboard only: it spends money or allowance, so a person presses it (sends an ESP campaign to real recipients).
• POST /v1/campaigns/{campaignId}/test — Send one real message on the channel the campaign will actually use. Operation testSendCampaign. From an AI assistant: API and dashboard only: it needs a permission AI connections are not offered (an ESP test send needs campaigns.send).

Public pages and incoming webhooks

• GET /v1/public/email-marketing/c/{token} — The click counter. Records one click per recipient and redirects to the original link. Operation emailMarketingClick. From an AI assistant: a page your recipients open from an email (the click-tracking redirect).
• GET /v1/public/email-marketing/f/{public_id} — A sign-up form's hosted page (no login). Operation emailMarketingFormPage. From an AI assistant: a page your recipients open from an email (the public signup form page).
• POST /v1/public/email-marketing/f/{public_id} — Submit a sign-up form (hosted page, embed or JSON). Operation emailMarketingFormSubmit. From an AI assistant: called by another system (a provider or a visitor), not by you (a visitor submits a signup form).
• GET /v1/public/email-marketing/fc — The double opt-in confirmation page (no login). Operation emailMarketingFormConfirmPage. From an AI assistant: a page your recipients open from an email (the double opt-in confirmation page).
• POST /v1/public/email-marketing/fc — Confirm a sign-up (adds the person to the list with a consent record). Operation emailMarketingFormConfirm. From an AI assistant: called by another system (a provider or a visitor), not by you (a visitor confirms a double opt-in).
• GET /v1/public/email-marketing/o/{token} — The open-tracking image (a 1x1 GIF). Counts one open per recipient. Operation emailMarketingOpenPixel. From an AI assistant: a page your recipients open from an email (the open-tracking pixel).
• GET /v1/public/email-marketing/u/{token} — The footer unsubscribe link (no login). Operation emailMarketingUnsubscribePage. From an AI assistant: a page your recipients open from an email (the unsubscribe page).
• POST /v1/public/email-marketing/u/{token} — RFC 8058 one-click unsubscribe (and the page's "stop everything" button). Operation emailMarketingUnsubscribeOneClick. From an AI assistant: called by another system (a provider or a visitor), not by you (RFC 8058 one-click unsubscribe).
• GET /v1/public/email-marketing/warmup-u/{token} — The marketing pool warm-up mail's unsubscribe link (no login). Operation emailMarketingWarmupUnsubscribePage. From an AI assistant: a page your recipients open from an email (the warm-up unsubscribe page).
• POST /v1/public/email-marketing/warmup-u/{token} — RFC 8058 one-click unsubscribe from the warm-up mail. Operation emailMarketingWarmupUnsubscribeOneClick. From an AI assistant: called by another system (a provider or a visitor), not by you (warm-up one-click unsubscribe).
• POST /v1/webhooks/campaign-events — Ingest a signed delivery event from the e-mail provider. Operation receiveCampaignDeliveryWebhook. From an AI assistant: called by another system (a provider or a visitor), not by you (signed ESP delivery webhook).
• POST /v1/webhooks/campaigns/telnyx — Inbound SMS replies (STOP / START) from our SMS vendor. Operation receiveCampaignsTelnyxInbound. From an AI assistant: called by another system (a provider or a visitor), not by you (signed Telnyx inbound webhook).
• POST /v1/webhooks/email-marketing/{connection_id} — A customer's own e-mail provider's delivery events for one sending connection. Operation receiveEmailMarketingProviderWebhook. From an AI assistant: called by another system (a provider or a visitor), not by you (signed sender-provider webhook).

Flows

• GET /v1/email-marketing/flows — E-mail flows (welcome, drip, a yearly date), one keyset page. Operation listEmailMarketingFlows. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/flows — Create a flow (it starts as a draft). Operation createEmailMarketingFlow. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• DELETE /v1/email-marketing/flows/{flow_id} — Delete a flow and its enrolments (its sent runs stay, as campaigns). Operation deleteEmailMarketingFlow. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• GET /v1/email-marketing/flows/{flow_id} — One flow with its steps and its report (enrolled, in progress, runs and recipients per step). Operation getEmailMarketingFlow. Permissions checked: email_marketing.view. From an AI assistant: yes, through the MCP.
• PATCH /v1/email-marketing/flows/{flow_id} — Change a flow; steps, when given, replaces the whole sequence. Operation updateEmailMarketingFlow. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/flows/{flow_id}/activate — Switch a flow on; only people who join the list from now on are enrolled. Operation activateEmailMarketingFlow. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.
• POST /v1/email-marketing/flows/{flow_id}/pause — Pause a flow; due steps wait and nobody new is mailed until it is switched back on. Operation pauseEmailMarketingFlow. Permissions checked: email_marketing.manage, email_marketing.view. From an AI assistant: yes, through the MCP.