Quickstart
Wire a killswitch around a risky subsystem in five minutes — so the 3am on-call has one switch to flip.
A killswitch is the lever you pull when something is on fire. This walkthrough takes you from zero to a wired-in killswitch around an outbound-email path. By the end, on-call can disable email sending in under five seconds without touching code.
The 5-minute path
create · wire · test the flipCreate the killswitch (not killed)
Guard the dangerous path
Flip it, watch it stop
Tell the team when it flips
Prerequisites
The SDK configured once with your server key — see the quickstart
for the single configure() call. Everything below reads through the Client it hands you.
1. Create the killswitch
shipeasy release killswitch create transactional.emails-paused \
--description "Disables outbound transactional email" \
--value falseYou can also click New killswitch on the Killswitches page.
Killswitch names must be folder.name. --value false means "killed = false" by
default — the read returns false, your code reads "not killed, proceed". Flip
it to true to kill the path in production. Until the SDK has fetched the first
blob, reads return false (the safer default for "is this killed?") — so a cold
cache won't accidentally kill your emails.
2. Wire it into the code path
Wrap the dangerous call with the killswitch read — it returns true when the
killswitch is engaged (the path is killed), false otherwise:
import { Client } from "@shipeasy/sdk/server";
export async function sendOrderEmail(order: Order, user: User) {
const client = new Client(user);
if (client.getKillswitch("transactional.emails-paused")) {
logger.warn("emails paused via killswitch", { orderId: order.id });
return;
}
await mailer.send(order);
}client = shipeasy.Client(user)
if client.get_killswitch("transactional.emails-paused"):
logger.warning("emails paused via killswitch", extra={"order_id": order.id})
return
mailer.send(order)client := shipeasy.NewClient(user)
if client.GetKillswitch("transactional.emails-paused") {
log.Printf("emails paused via killswitch order=%s", order.ID)
return
}
mailer.Send(order)client = Shipeasy::Client.new(user)
if client.get_killswitch("transactional.emails-paused")
Rails.logger.warn("emails paused via killswitch order=#{order.id}")
return
end
Mailer.send(order)Client client = new Client(user);
if (client.getKillswitch("transactional.emails-paused")) {
log.warn("emails paused via killswitch orderId={}", order.id());
return;
}
mailer.send(order);val client = Client(user)
if (client.getKillswitch("transactional.emails-paused")) {
logger.warn("emails paused via killswitch orderId=${order.id}")
return
}
mailer.send(order)$client = new Shipeasy\Client($user);
if ($client->getKillswitch('transactional.emails-paused')) {
error_log("emails paused via killswitch order={$order->id}");
return;
}
$mailer->send($order);let client = try Client(user)
if await client.getKillswitch("transactional.emails-paused") {
logger.warning("emails paused via killswitch")
return
}
try await mailer.send(order)Three things to internalise:
- Killswitches don't target. They're global, so the user you bind to the
Clientplays no part in the answer. A killswitch can still carry named per-key overrides — pass the key as a second argument, see patterns. - The cold-cache default is "not killed". Reads return
falseuntil the first blob arrives, so a cold start never kills the path on its own. If you want the opposite posture during an outage, that is a flag decision, not a killswitch one. - Log the bypass. When the killswitch is engaged, log a structured warn so post-mortem can reconstruct what was suppressed.
Deploy this. The killswitch is false, so behaviour is unchanged from before.
3. Rehearse the flip
The most common reason a killswitch fails to help during an incident is that no one has ever flipped it before. Rehearse in staging:
# Flip the killswitch to true ("kill the path") — single-value form
shipeasy release killswitch update transactional.emails-paused --value true
# Verify no emails flow in staging
# … run your normal email test path …
# Re-enable (flip back to false = "not killed")
shipeasy release killswitch update transactional.emails-paused --value falseYou can flip it from the Killswitches page too — it is the same write. Time how long it takes from "decide to flip" to "next email is suppressed." The next call should return the new value within one poll interval of the flip — that interval is plan-derived and advertised to the SDK, not configured.
4. Get notified when the killswitch flips
A killswitch is a social signal as much as a technical one. Flipping it should announce itself on the team's incident channel and create a paper trail.
Open Settings → Notifications. The Events table has a Killswitch flipped row; turn on the channels you want (in-app, email, Slack) for it. Connect Slack on the same tab first if you want the post in a channel — the message carries a one-click Flip back. The notification says who flipped it, when, and the new value; wire that into your runbook ("if you see this, page primary on-call within 2 minutes").
What you have now
- A killswitch on the Killswitches page, named
transactional.emails-paused. - A wrapped code path that respects it on every call.
- A rehearsed flip-and-restore drill that took < 5 seconds.
- A notification on the flip so the team knows when production is in degraded mode.
That's the whole pattern. Repeat for every system whose pause-button you'd want on the lock screen of your phone.
Where to next
When to add a killswitch→
Which subsystems deserve one — and which should stay feature flags.
Feature flags vs killswitches→
Same primitive at the wire level, different ergonomics. When to reach for which.
Worked example: paused emails→
The walkthrough from the case-studies page, with more context on the incident.