Sequences

Sequences → open it → Enrollments → Enroll

Start the dunning sequence for ada@example.com, invoice inv_1042.

import { MailKite } from "mailkite";

const mk = new MailKite(process.env.MAILKITE_API_KEY);

const { enrollment } = await mk.startSequence("dunning", {
  email: "ada@example.com",
  input: { invoiceId: "inv_1042", amountDue: 4200 },
  // Your own id, so you never have to store ours to cancel later.
  cancelKey: "inv_1042",
});

import os
from mailkite import MailKite

mk = MailKite(os.environ["MAILKITE_API_KEY"])

res = mk.startSequence("dunning", {
    "email": "ada@example.com",
    "input": {"invoiceId": "inv_1042", "amountDue": 4200},
    "cancelKey": "inv_1042",
})

curl -X POST https://api.mailkite.dev/v1/sequences/dunning/start \
  -H "Authorization: Bearer $MAILKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "input": { "invoiceId": "inv_1042", "amountDue": 4200 },
    "cancelKey": "inv_1042"
  }'

Sequences → New sequence
Name      dunning
Triggers  payment.failed
From      billing@myapp.ai
Steps     Wait 3 days → Send "Your invoice is still unpaid"
Click  [ Create & activate ]

Create a sequence called "dunning" that starts on a payment.failed event,
waits 3 days, then emails a reminder with the invoice id.

import { MailKite } from "mailkite";

const mk = new MailKite(process.env.MAILKITE_API_KEY);

const seq = await mk.createSequence({
  name: "dunning",
  status: "active",
  from: "billing@myapp.ai",
  // The signature. Every way in must supply this shape.
  input: {
    invoiceId: { type: "string", required: true },
    amountDue: { type: "number" },
  },
  // The doors. Each is an event name your code posts.
  triggers: ["payment.failed"],
  steps: [
    { type: "delay", for: "3 days" },
    {
      type: "send",
      subject: "Invoice {{input.invoiceId}} is still unpaid",
      html: "<p>We couldn't take payment for {{input.invoiceId}}.</p>",
    },
  ],
});

import os
from mailkite import MailKite

mk = MailKite(os.environ["MAILKITE_API_KEY"])

seq = mk.createSequence({
    "name": "dunning",
    "status": "active",
    "from": "billing@myapp.ai",
    "input": {
        "invoiceId": {"type": "string", "required": True},
        "amountDue": {"type": "number"},
    },
    "triggers": ["payment.failed"],
    "steps": [
        {"type": "delay", "for": "3 days"},
        {"type": "send", "subject": "Invoice {{input.invoiceId}} is still unpaid",
         "html": "<p>We couldn't take payment for {{input.invoiceId}}.</p>"},
    ],
})

curl -X POST https://api.mailkite.dev/v1/sequences \
  -H "Authorization: Bearer $MAILKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dunning",
    "status": "active",
    "from": "billing@myapp.ai",
    "input": { "invoiceId": { "type": "string", "required": true } },
    "triggers": ["payment.failed"],
    "steps": [
      { "type": "delay", "for": "3 days" },
      { "type": "send", "subject": "Invoice {{input.invoiceId}} is still unpaid", "text": "…" }
    ]
  }'

Sequences are triggered by your application, not from the dashboard.
To start one by hand:  Sequences → open it → Enrollments → Enroll

Record that ada@example.com's payment failed for invoice inv_1042.

// Your app already knows this happened. Say so.
await mk.sendEvent({
  name: "payment.failed",
  email: "ada@example.com",
  payload: { invoiceId: "inv_1042", amountDue: 4200 },
  // A retried webhook stays one event — and therefore one enrollment.
  dedupeKey: "inv_1042-attempt-3",
});

mk.sendEvent({
    "name": "payment.failed",
    "email": "ada@example.com",
    "payload": {"invoiceId": "inv_1042", "amountDue": 4200},
    "dedupeKey": "inv_1042-attempt-3",
})

curl -X POST https://api.mailkite.dev/v1/events \
  -H "Authorization: Bearer $MAILKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payment.failed",
    "email": "ada@example.com",
    "payload": { "invoiceId": "inv_1042", "amountDue": 4200 },
    "dedupeKey": "inv_1042-attempt-3"
  }'

The dashboard composer sends immediately.
Name a sequence from the API, or enrol from Sequences → Enrollments.

Send the invoice email to ada@example.com and start the dunning sequence for her.

await mk.send({
  from: "billing@myapp.ai",
  to: "ada@example.com",
  subject: "Invoice #1042",
  html: "<p>Your invoice is attached.</p>",
  sequence: "dunning",                          // ← the whole integration
  sequenceInput: { invoiceId: "inv_1042" },     // explicit params beat auto-injected ones
});

mk.send({
    "from": "billing@myapp.ai",
    "to": "ada@example.com",
    "subject": "Invoice #1042",
    "html": "<p>Your invoice is attached.</p>",
    "sequence": "dunning",
    "sequenceInput": {"invoiceId": "inv_1042"},
})

curl -X POST https://api.mailkite.dev/v1/send \
  -H "Authorization: Bearer $MAILKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "billing@myapp.ai",
    "to": "ada@example.com",
    "subject": "Invoice #1042",
    "html": "<p>Your invoice is attached.</p>",
    "sequence": "dunning",
    "sequenceInput": { "invoiceId": "inv_1042" }
  }'

Sequences → open it → Enrollments → Cancel

Stop the dunning follow-ups for invoice inv_1042 — it's been paid.

// Directly, with the key you started it with.
await mk.stopSequence({ cancelKey: "inv_1042" });

// …or, if you never set one:
await mk.stopSequence({ sequence: "dunning", email: "ada@example.com" });

// Or indirectly: post the event a wait_for_event step is parked on, and every
// sequence waiting for it moves on — including ones you'd forgotten about.
await mk.sendEvent({ name: "invoice.paid", email: "ada@example.com" });

mk.stopSequence({"cancelKey": "inv_1042"})

mk.stopSequence({"sequence": "dunning", "email": "ada@example.com"})

mk.sendEvent({"name": "invoice.paid", "email": "ada@example.com"})

curl -X POST https://api.mailkite.dev/v1/sequences/stop \
  -H "Authorization: Bearer $MAILKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cancelKey": "inv_1042" }'