Kanorio
Kanorio 開發者

API 參考

Campaigns

Management API: GET /sites/{id}/campaigns, POST /sites/{id}/campaigns, PATCH /sites/{id}/campaigns/{campaignId}

這頁只有英文版。API 參考、Webhook 事件與變更紀錄維持英文，和程式碼裡的欄位名稱、錯誤碼一致。
Base URL https://app.kanorio.com/api/v1ErrorsPagination

List campaigns

GET/sites/{id}/campaigns
betamarketing:viewdefault (120/minute per token)

List email campaigns (newest updated first) with status, audience segment and delivery stats for sent ones. Errors: FORBIDDEN, PLAN_REQUIRED, INVALID_CURSOR.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

  • limitinteger · query

    Maximum number of items to return, 1–100. Defaults to 20.

  • cursorstring · query

    Opaque cursor from the previous page's nextCursor. Omit for the first page.

Response 200

  • dataobject[]required
  • data[].idstringrequired
  • data[].namestringrequired
  • data[].channelstringrequired
  • data[].statusstringrequired

    DRAFT, SCHEDULED, SENDING, PAUSED, SENT or CANCELED. Agents can only edit DRAFT.

  • data[].pausedReasonstring | nullrequired
  • data[].segmentNamestring | nullrequired
  • data[].scheduledAtstring | nullrequired
  • data[].startedAtstring | nullrequired
  • data[].completedAtstring | nullrequired
  • data[].updatedAtstringrequired
  • data[].recipientCountinteger | nullrequired
  • data[].statsobject | nullrequired
  • data[].stats.recipientsintegerrequired
  • data[].stats.pendingintegerrequired
  • data[].stats.sentintegerrequired
  • data[].stats.deliveredintegerrequired
  • data[].stats.bouncedintegerrequired
  • data[].stats.complainedintegerrequired
  • data[].stats.notSentintegerrequired
  • data[].stats.openedintegerrequired
  • data[].stats.clickedintegerrequired
  • data[].stats.unsubscribedintegerrequired
  • hasMorebooleanrequired

    True when another page exists; pass nextCursor to fetch it.

  • nextCursorstring | nullrequired

    Cursor for the next page, or null on the last page.

Errors

  • FORBIDDEN 403
  • PLAN_REQUIRED 403
  • INVALID_CURSOR 400

MCP tool campaigns_list

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/campaigns" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
Response
{
  "data": [
    {
      "id": "camp_example01",
      "name": "October seasonal bake",
      "channel": "EMAIL",
      "status": "DRAFT",
      "pausedReason": null,
      "segmentName": "Ordered in the last 90 days",
      "scheduledAt": null,
      "startedAt": null,
      "completedAt": null,
      "updatedAt": "2026-10-06T08:00:00.000Z",
      "recipientCount": 320,
      "stats": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Create draft

POST/sites/{id}/campaigns
betamarketing:managedefault (120/minute per token)

Create an email campaign as a DRAFT. Agents cannot send or schedule campaigns; the owner reviews and sends from the console. content is optional; when provided it must match the email design-template content shape (subject, previewText, blocks). Audience defaults to the all-subscribers segment. Reference images as asset:<assetId> (media.upload, media.import_stock). Errors: FORBIDDEN, PLAN_REQUIRED, VALIDATION, INVALID_CONTENT (details.detail lists issues), CHANNEL_UNAVAILABLE, ASSET_NOT_FOUND, ASSET_NOT_ALLOWED.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

Request body

  • namestringrequired
  • channel"EMAIL"

    Defaults to EMAIL.

  • contentobject

Response 201

  • idstringrequired
  • namestringrequired
  • channelstringrequired
  • statusstringrequired
  • contentobjectrequired

    Channel content (email: subject, previewText, blocks...). Media-library images appear as asset:<assetId>.

  • assetsobjectrequired

    The media-library images the content uses, by assetId.

  • audienceobject | nullrequired
  • audience.kind"segment"required
  • audience.segmentIdstringrequired
  • scheduledAtstring | nullrequired
  • recipientCountinteger | nullrequired
  • updatedAtstringrequired
  • timeZonestringrequired

Errors

  • FORBIDDEN 403
  • PLAN_REQUIRED 403
  • VALIDATION 400
  • INVALID_CONTENT 400 · details.detail lists issues
  • CHANNEL_UNAVAILABLE 422
  • ASSET_NOT_FOUND 404
  • ASSET_NOT_ALLOWED 422

MCP tool campaigns_create_draft

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/campaigns" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"October seasonal bake","channel":"EMAIL"}'
Response
{
  "id": "camp_example01",
  "name": "October seasonal bake",
  "channel": "EMAIL",
  "status": "DRAFT",
  "content": {
    "subject": "October special: chestnut croissants are here",
    "body": "This month we're baking..."
  },
  "assets": {},
  "audience": {
    "kind": "segment",
    "segmentId": "seg_example01"
  },
  "scheduledAt": null,
  "recipientCount": 320,
  "updatedAt": "2026-10-06T08:00:00.000Z",
  "timeZone": "Asia/Taipei"
}

Update draft

PATCH/sites/{id}/campaigns/{campaignId}
betamarketing:managedefault (120/minute per token)

Update a DRAFT campaign's name, content and/or audience segment. Only drafts can be changed by agents (NOT_EDITABLE otherwise); scheduling and sending stay in the console. Errors: FORBIDDEN, PLAN_REQUIRED, CAMPAIGN_NOT_FOUND, NOT_EDITABLE, INVALID_CONTENT, INVALID_AUDIENCE, SEGMENT_NOT_FOUND, ASSET_NOT_FOUND, ASSET_NOT_ALLOWED.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

  • campaignIdstring · pathrequired

    Campaign id. Get it from campaigns.list.

Request body

  • namestring
  • contentobject
  • audienceobject

    Who receives it: a segment id from segments.list. New drafts default to the all-subscribers segment.

  • audience.kind"segment"required
  • audience.segmentIdstringrequired

Response 200

  • idstringrequired
  • namestringrequired
  • channelstringrequired
  • statusstringrequired
  • contentobjectrequired

    Channel content (email: subject, previewText, blocks...). Media-library images appear as asset:<assetId>.

  • assetsobjectrequired

    The media-library images the content uses, by assetId.

  • audienceobject | nullrequired
  • audience.kind"segment"required
  • audience.segmentIdstringrequired
  • scheduledAtstring | nullrequired
  • recipientCountinteger | nullrequired
  • updatedAtstringrequired
  • timeZonestringrequired

Errors

  • FORBIDDEN 403
  • PLAN_REQUIRED 403
  • CAMPAIGN_NOT_FOUND 404
  • NOT_EDITABLE 409
  • INVALID_CONTENT 400
  • INVALID_AUDIENCE 400
  • SEGMENT_NOT_FOUND 404
  • ASSET_NOT_FOUND 404
  • ASSET_NOT_ALLOWED 422

MCP tool campaigns_update_draft

curl -X PATCH "https://app.kanorio.com/api/v1/sites/{id}/campaigns/{campaignId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audience":{"kind":"segment","segmentId":"seg_example01"}}'
Response
{
  "id": "camp_example01",
  "name": "October seasonal bake",
  "channel": "EMAIL",
  "status": "DRAFT",
  "content": {
    "subject": "October special: chestnut croissants are here",
    "body": "This month we're baking..."
  },
  "assets": {},
  "audience": {
    "kind": "segment",
    "segmentId": "seg_example01"
  },
  "scheduledAt": null,
  "recipientCount": 320,
  "updatedAt": "2026-10-06T08:00:00.000Z",
  "timeZone": "Asia/Taipei"
}