Inbound webhooks

// Express
import express from "express";
import { MailKite } from "mailkite";

const SECRET = process.env.MAILKITE_WEBHOOK_SECRET;
const app = express();

// Capture the RAW body — verify the exact bytes, not a re-serialized object.
app.use("/hooks/mailkite", express.raw({ type: "application/json" }));

app.post("/hooks/mailkite", (req, res) => {
  // Reject anything that isn't a genuine, fresh MailKite delivery.
  if (!MailKite.verifyWebhook(req.headers["x-mailkite-signature"], req.body, SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  if (event.type === "email.received") {
    console.log("from", event.from.address, "·", event.subject);
    // ...create a ticket, reply, store it, hand to an agent.
  }
  res.sendStatus(200); // ack fast; do heavy work out of band
});

app.listen(3000);

# Flask
import os
from flask import Flask, request, abort
from mailkite import verify_webhook

SECRET = os.environ["MAILKITE_WEBHOOK_SECRET"]
app = Flask(__name__)

@app.post("/hooks/mailkite")
def mailkite():
    # Reject anything that isn't a genuine, fresh MailKite delivery (RAW body).
    sig = request.headers.get("x-mailkite-signature", "")
    if not verify_webhook(sig, request.get_data(), SECRET):
        abort(401)
    event = request.get_json()
    if event["type"] == "email.received":
        print("from", event["from"]["address"], "·", event["subject"])
        # ...create a ticket, reply, store it, hand to an agent.
    return "", 200  # ack fast; do heavy work out of band

<?php
// Any framework — raw PHP shown.
$mk = new \MailKite\Client(""); // no API key needed to verify
$secret = getenv("MAILKITE_WEBHOOK_SECRET");
$signature = $_SERVER["HTTP_X_MAILKITE_SIGNATURE"] ?? "";
$rawBody = file_get_contents("php://input"); // the RAW request body

if (!$mk->verifyWebhook($signature, $rawBody, $secret)) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true);
if (($event['type'] ?? '') === 'email.received') {
    error_log("from {$event['from']['address']} · {$event['subject']}");
    // ...create a ticket, reply, store it, hand to an agent.
}

http_response_code(200); // ack fast; do heavy work out of band

// Spring Boot — capture the RAW body to verify the exact bytes received.
@PostMapping("/hooks/mailkite")
public ResponseEntity<Void> mailkite(
        @RequestHeader("x-mailkite-signature") String signature,
        @RequestBody byte[] rawBody) throws Exception {
    MailKite mk = new MailKite(""); // no API key needed to verify
    String body = new String(rawBody, StandardCharsets.UTF_8);
    if (!mk.verifyWebhook(signature, body, System.getenv("MAILKITE_WEBHOOK_SECRET"))) {
        return ResponseEntity.status(401).build();
    }
    Map<String, Object> event = new ObjectMapper().readValue(body, new TypeReference<>() {});
    if ("email.received".equals(event.get("type"))) {
        System.out.println("from " + event.get("from") + " · " + event.get("subject"));
        // ...create a ticket, reply, store it, hand to an agent.
    }
    return ResponseEntity.ok().build(); // ack fast; heavy work out of band
}

// net/http
http.HandleFunc("/hooks/mailkite", func(w http.ResponseWriter, r *http.Request) {
	rawBody, _ := io.ReadAll(r.Body) // the RAW request body
	sig := r.Header.Get("x-mailkite-signature")
	if !mailkite.VerifyWebhook(sig, string(rawBody), secret) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
	var event map[string]any
	json.Unmarshal(rawBody, &event)
	if event["type"] == "email.received" {
		log.Println("from", event["from"], "·", event["subject"])
		// ...create a ticket, reply, store it, hand to an agent.
	}
	w.WriteHeader(http.StatusOK) // ack fast; heavy work out of band
})

# Sinatra
require "sinatra"
require "json"
require "mailkite"

post "/hooks/mailkite" do
  raw_body = request.body.read # the RAW request body
  sig = request.env["HTTP_X_MAILKITE_SIGNATURE"]
  halt 401 unless Mailkite.verify_webhook(sig, raw_body, ENV["MAILKITE_WEBHOOK_SECRET"])
  event = JSON.parse(raw_body)
  if event["type"] == "email.received"
    puts "from #{event['from']['address']} · #{event['subject']}"
    # ...create a ticket, reply, store it, hand to an agent.
  end
  status 200 # ack fast; do heavy work out of band
end

Dashboard → Routes → [ + New route ]
Match        support@myapp.ai
Action       Webhook
Destination  https://myapp.ai/hooks/support
Click  [ Save ]

Send mail for support@myapp.ai to https://myapp.ai/hooks/support

await mk.createRoute({
  match: "support@myapp.ai",
  action: "webhook",
  destination: "https://myapp.ai/hooks/support",
});

mk.createRoute({
    "match": "support@myapp.ai",
    "action": "webhook",
    "destination": "https://myapp.ai/hooks/support",
})

$mk->createRoute([
    'match' => 'support@myapp.ai',
    'action' => 'webhook',
    'destination' => 'https://myapp.ai/hooks/support',
]);

mk.createRoute(Map.of(
    "match", "support@myapp.ai",
    "action", "webhook",
    "destination", "https://myapp.ai/hooks/support"
));

_, err := mk.CreateRoute(map[string]any{
	"match":       "support@myapp.ai",
	"action":      "webhook",
	"destination": "https://myapp.ai/hooks/support",
})

mk.createRoute(
  "match" => "support@myapp.ai",
  "action" => "webhook",
  "destination" => "https://myapp.ai/hooks/support"
)

curl https://api.mailkite.dev/api/routes \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "match": "support@myapp.ai",
    "action": "webhook",
    "destination": "https://myapp.ai/hooks/support"
  }'

Dashboard → Domains → myapp.ai → Webhook
Click  [ Send test event ]

Send a test webhook event for myapp.ai

await mk.testWebhook("dom_…");

mk.testWebhook("dom_…")

$mk->testWebhook('dom_…');

mk.testWebhook("dom_…");

_, err := mk.TestWebhook("dom_…")

mk.testWebhook("dom_…")

curl -X POST https://api.mailkite.dev/api/domains/dom_…/webhook/test \
  -H "Authorization: Bearer <session-token>"

Dashboard → Messages → the failed delivery
Click  [ Retry ]

Retry the failed delivery dlv_…

await mk.retryDelivery("dlv_…");

mk.retryDelivery("dlv_…")

$mk->retryDelivery('dlv_…');

mk.retryDelivery("dlv_…");

_, err := mk.RetryDelivery("dlv_…")

mk.retryDelivery("dlv_…")

curl -X POST https://api.mailkite.dev/api/deliveries/dlv_…/retry \
  -H "Authorization: Bearer <session-token>"