ESP Campaign Push

skill

Trigger a campaign in the ESP via POST and stage any record updates for a human to apply.

Download .md

ESP Campaign Push

Trigger a campaign send in the ESP (email service provider) via a REST API call and stage any needed record updates for a human to apply.

When to use

  • A campaign is approved and ready to fire in the ESP (e.g. Klaviyo, Mailchimp, SendGrid, Customer.io).
  • A scheduled or trigger-based send needs to be kicked off programmatically instead of through the ESP's dashboard.
  • A campaign push fails or returns an error and a human needs to be alerted to intervene.
  • Downstream records (CRM contact status, campaign log, tracking sheet) need updating after a push but the ESP or system of record only supports PATCH/PUT/DELETE for that update.

Tools

  • http-post: calls the ESP's REST API to trigger/launch the campaign send.
  • write-file: stages a change list of any record updates the campaign push implies (e.g. contact status, campaign log entries) that cannot be applied directly.
  • send-message: notifies a human to apply staged updates, or to create/fix an Integration, or to review a failed push.

Playbook

  1. Confirm the campaign identifier, target segment, and any send-time parameters you were given before making any call.
  2. Call the ESP REST API with http-post to trigger the campaign (e.g. POST https://a.klaviyo.com/api/campaigns/{id}/send or the ESP's equivalent trigger endpoint). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials.
  3. If the call returns 401/403 or no Integration row exists for the ESP host, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  4. If the push succeeds, capture the response payload (campaign ID, send status, timestamp) for the record.
  5. Determine whether the push implies any downstream record updates (e.g. marking a CRM contact as "campaign sent", updating a tracking sheet, closing a task). Because updating those records typically requires PATCH/PUT/DELETE against a SaaS system, do not attempt it directly — this is not possible with the declared tools.
  6. Compile the full list of implied updates (record, field, old value, new value, source campaign) into a change list using write-file.
  7. Use send-message to hand the staged change list off to a human, describing exactly which records need updating and why, and pointing to the staged file.
  8. If the initial trigger call itself fails for reasons other than auth (e.g. malformed segment ID, campaign already sent), do not retry blindly — message the human via send-message with the error detail so they can correct the input.
  9. Once the human confirms the push and any handoff have been acted on, treat the task as complete.

Failure modes

  • 401/403 response from the ESP -> missing or invalid Integration; stop and escalate via send-message naming the service and required scopes.
  • Empty or unexpected response body -> verify the campaign ID, endpoint path, and payload parameters before retrying.
  • Rate limit (429) response -> back off and note the limit and retry window in memory rather than hammering the endpoint.
  • ESP dashboard/API structure has changed and the documented endpoint no longer matches -> fall back to browser-search to find the current API reference before calling again.

Done when

  • The ESP REST API confirms the campaign was triggered (success response with campaign ID/status captured).
  • Any implied record updates are written to a staged change list via write-file and handed to a human via send-message.
  • A human has acknowledged either the successful push or an escalation for a failed/blocked push.