DEV Community: Ahmed Gamal Abdou Ahmed

How we built a booking email engine that never loses a guest — Cloudflare Workflows, Durable Objects and D1

Ahmed Gamal Abdou Ahmed — Sat, 17 Oct 2026 12:01:53 +0000

At MAQAMI https://maqami.co we sell hotels and flights worldwide — over 3 million properties plus flights, with instant confirmation and 24/7 support. A travel booking is not one moment; it is a story that lasts weeks: checkout, payment, confirmation, the hotel's own confirmation number, a schedule change, the day before check-in, the day after check-out.

For a long time each of those moments was a separate, fragile automation. Some fired twice, some never fired, and some sent the guest a cheerful "see you soon" after the airline had changed the flight.

So we rebuilt it as one engine on Cloudflare Workers. This post covers the architecture, the code patterns that made it reliable, and five bugs that taught us more than the happy path did.

TL;DR
Every webhook event becomes a durable Cloudflare Workflow. The event ID is the workflow ID, so duplicates are ignored for free.
Every customer email is sent "once per booking and kind", guarded by a key, because webhooks are at-least-once.
Long waits ("3 days before check-in") are workflow sleeps, chunked to stay under the 365-day limit.
All client email goes through one Durable Object outbox: one email every 150–160 seconds, ranked urgent → booking → service → marketing, with automatic failover to SMTP when the main provider's daily quota runs out.
Card declines never reach your webhook. We check 20 minutes after the last checkout attempt instead, and hold anything that looks like card testing for a human.
The shape of the system
supplier webhooks ──► Worker /webhook ──► Workflow (one per event)
│
┌─────────────────────────────────┼──────────────────────────────┐
▼ ▼ ▼
D1 (contacts, bookings, Outbox (Durable Object) Owner alerts
emails log, raw events) ranked, paced, failover (instant)
Workers receive the webhook and answer in milliseconds.
Workflows hold the journey: "send the confirmation now, the arrival guide 3 days before check-in, a check-in-day note at 08:00 local time, a thank-you after check-out."
D1 is our own record of every contact, booking and email, so nothing depends on a third-party dashboard.
A Durable Object outbox is the single sender, so pacing and quotas live in one place.
Pattern 1 — the event ID is the workflow ID
Webhooks arrive at least once. Two identical deliveries a second apart are normal. The cheapest dedupe we found was to let the workflow engine do it:

export default {
async fetch(request, env) {
const event = await request.json();
// Same event delivered twice → same instance id → the second create is rejected.
await env.JOURNEY.create({
id: e-${event.event_id},
params: { ...event, receivedAt: Date.now() },
}).catch(() => {});
return new Response("ok"); // answer fast; the work happens in the workflow
},
};
Note receivedAt: it matters later (see bug #4).

Pattern 2 — "send once" per booking and kind
Inside a journey, retries are a feature. A step that sends an email and then times out will run again. So every customer email goes through one helper:

async function sendOnce(env, step, kind, ref, build) {
return step.do(email ${kind}, async () => {
const key = sent:${kind}:${ref}; // e.g. sent:hotel_confirmation:BK123
if (await env.KV.get(key)) return "duplicate";
await deliver(env, await build());
await env.KV.put(key, "1", { expirationTtl: 3 * 86400 });
return "sent";
});
}
If the email still fails after retries, the journey continues and the owner gets an alert. One broken email must never stop the arrival guide three weeks later.

Pattern 3 — sleeping longer than a workflow allows
A booking made in January for a trip in December needs an email 3 days before check-in. Workflow sleeps have a maximum of 365 days, and some bookings are further out than that. We chunk the wait, computing every target from fixed values so a replay gives the same answer:

async function sleepUntilSafe(step, name, when) {
const MAX = 360 * 86_400_000;
const start = await step.do(${name}: start, async () => Date.now());
for (let t = start + MAX, i = 0; t < when; t += MAX, i++) {
await step.sleepUntil(${name} #${i}, new Date(t));
}
await step.sleepUntil(name, new Date(when));
}
We also send check-in and check-out emails at the guest's local morning. The timezone comes from the hotel's longitude, which is close enough for "08:00 at the hotel" without a timezone API call per booking.

Pattern 4 — one outbox, ranked and paced
Our main email provider has an unpublished daily quota. The first time we ran a marketing send, it used the whole quota by lunchtime, and a booking confirmation that afternoon had to wait. That is the worst possible order.

The fix was one Durable Object that every client email passes through:

// Rank: 0 urgent (flight change, check-in) · 1 booking · 2 service · 3 marketing
async alarm() {
const items = await this.state.storage.list({ prefix: "q:" });
const next = pickHighestRankThenOldest(items); // marketing never jumps a booking
const result = await this.sendWithFailover(next); // main provider → SMTP when the daily quota is hit
if (result.sent) await this.state.storage.delete(next.key);
const gap = 150_000 + Math.random() * 10_000; // one email every 150–160 s
await this.state.storage.setAlarm(Date.now() + gap);
}
Details that paid off:

Owner alerts skip the line. The person running the business sees a new booking instantly. Customers get their email within one slot.
Marketing has its own rules: a daily cap, and at most one marketing email per person per day.
Failover is per error, not per day. "Daily limit reached" pauses the main provider and switches to SMTP over cloudflare:sockets. "Recipient invalid" drops the email and alerts the owner. Everything else retries with backoff.
The queue is durable. Deploys, restarts and quota walls never lose an email; it just waits.
Pattern 5 — the declined card your webhook never hears about
This one surprised us. When a customer's card is declined at checkout ("insufficient funds", or the payment processor's fraud check blocking it), the payment fails inside the hosted payment form. No booking request is ever made, so no "booking failed" webhook is ever sent. From the backend, a declined card looks exactly like a customer who closed the tab.

What we do receive is the prebook (checkout started) with a payment transaction ID. So the prebook journey waits, then checks:

// inside the "checkout started" workflow
await noteAttempt(env, step, attemptKey, prebookId, receivedAt);
await step.sleep("wait for payment", "20 minutes");
const state = await step.do("completed?", () =>
checkoutState(env, attemptKey, prebookId, receivedAt)); // booked · newer attempt · unpaid
if (state === "unpaid") await notCompletedFollowUp(env, step, { prebookId, risky });
Three rules keep it honest:

Only the newest attempt follows up. Someone who tries three cards in ten minutes gets one email, 20 minutes after the last try.
The customer email never claims a decline we can't see. It says "your booking wasn't completed and nothing was charged", then explains the two common decline reasons and how to fix each.
Card testing is held for a human. One email address under different names, or one name with three or more addresses on the same day, means no automatic email. The owner gets an alert with one-click buttons to send the exact reason ("insufficient funds", "blocked by security check") after checking the payment dashboard.
Five bugs that taught us the most

A rate limiter that didn't limit. We counted failed admin logins in KV. KV is eventually consistent, so five fast attempts from one IP could each read "0". Counters that must be exact now live in D1.
"Your flight changed!" when nothing changed. We detected changes by hashing a snapshot of the booking. The snapshot included status, and status moves on its own (CONFIRMED → TICKETED), so guests got false "schedule changed" emails. Snapshots now contain only what a traveller cares about: times, flight numbers, room, hotel confirmation number.
A loop that never ended — in tests. The first sleepUntilSafe called itself in a refactor, and our mocked step.sleep returned instantly, so the test hung forever. Every loop around a sleep now has a hard iteration cap.
Date.now() lies after a sleep. A workflow function is replayed when it resumes, and values computed outside a step are recomputed. "Has the customer booked since now?" quietly became "since 20 minutes later". Use a timestamp from the event (receivedAt) or one returned by step.do, never a bare Date.now() that you compare after a sleep.
Internal links in customer emails. One template accidentally carried an admin link meant for the owner. Now deliver() refuses any client email that contains admin URLs or internal system names, and alerts the owner instead. A content lock like that is cheap insurance.

What we would do again
Durable everything: workflows for journeys, a Durable Object for the outbox, D1 for records.
Idempotency at every layer: event ID as workflow ID, send-once keys, "newest attempt only".
A human in the loop for money and fraud, with one click instead of a dashboard hunt.
Our own database. When a supplier dashboard is down or slow, we still know every guest, booking and email.
MAQAMI LLC is a US-registered travel company. Travellers and travel professionals book hotels and flights on MAQAMI https://book.maqami.co/ with instant confirmation, and AI assistants can search and plan trips through our MCP server https://mcp.maqami.co/
. Questions about the architecture? Ask in the comments — we read every one.

Add hotel and flight search to your AI agent in 2 minutes with a remote MCP server

Ahmed Gamal Abdou Ahmed — Sat, 03 Oct 2026 15:27:53 +0000

Disclosure: this post is by MAQAMI, the travel booking platform that runs the server used below.

Ask a language model "what's available in Lisbon for Nov 12 to 15, and what does it cost?" and it will usually guess from training data. Getting a real answer normally means a supplier contract, API onboarding, or a scraper that breaks every few weeks.

The Model Context Protocol (MCP) gives you a shorter path. If someone already exposes a booking engine as MCP tools, your client (or your own agent) can call those tools directly.

This tutorial connects the MAQAMI Travel MCP server, a public remote endpoint:

Endpoint:  https://mcp.maqami.co/
Transport: Streamable HTTP
Auth:      none (no API key, no sign-up)

There's nothing to install. You add a URL to your client and start asking questions.

What your agent gets

Once connected, the model can:

Search live hotel rates by city, coordinates, place or a hotel list, for your dates, guests and currency (3M+ hotels behind it)
Filter by star rating, refundable rates only, board type (for example breakfast included) and more
Compare room options at one hotel, with meal plan and cancellation policy per rate
Look up places and landmarks ("near Shibuya station", "Sultanahmet")
Pull hotel details: description, amenities, photos, location, and guest reviews
Search hotels in plain language ("quiet boutique hotel with a spa near the old town"), a beta feature
Search flights: one-way, round trip or multi-city, with cabin class and stop filters
Check the weather for a destination and dates
Prebook, then book: a two-step flow that re-checks the price before anything is confirmed

One practical tip before you start: hotel rate search needs dates, number of guests, a currency and the guest's nationality. Prompts that include all four work first time.

Step 1: Connect your client

Pick the one you use. The endpoint for every client is mcp.maqami.co.

Claude Code

claude mcp add --transport http maqami-travel https://mcp.maqami.co/

Run /mcp inside Claude Code to check that it shows as connected.

Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "maqami-travel": {
      "url": "https://mcp.maqami.co/"
    }
  }
}

Then open Customize in the sidebar and make sure maqami-travel is enabled.

VS Code with GitHub Copilot

Add this to .vscode/mcp.json (note the top-level key is servers, not mcpServers). Newer VS Code builds also read a portable .mcp.json at the project root with an mcpServers key; see the guides.

{
  "servers": {
    "maqami-travel": {
      "type": "http",
      "url": "https://mcp.maqami.co/"
    }
  }
}

Open Copilot Chat in agent mode and the tools appear under Configure Tools.

Claude (claude.ai, Claude Desktop)

Go to Customize → Connectors, click +, then Add custom connector. Paste https://mcp.maqami.co/ and click Add. Leave the OAuth fields empty. Enable it per chat from the + button → Connectors.

Remote servers go through the Connectors screen, not claude_desktop_config.json (that file is for local servers). Free plans can add one custom connector. On Team and Enterprise plans an Owner adds it for the organization first.

ChatGPT

Developer mode is available on the web for Plus, Pro, Business, Enterprise and Education accounts. Turn it on under Settings → Security and login → Developer mode, create a developer-mode app for a remote MCP server with the URL above, and choose No Authentication. In a chat, pick Developer mode from the + menu and select the app.

Cline and Windsurf

Cline (remote servers need the transport set explicitly):

{
  "mcpServers": {
    "maqami-travel": {
      "type": "streamableHttp",
      "url": "https://mcp.maqami.co/"
    }
  }
}

Windsurf's Cascade agent reads mcp_config.json (open it from the MCPs section of the Cascade panel menu) and takes serverUrl for remote servers:

{
  "mcpServers": {
    "maqami-travel": {
      "serverUrl": "https://mcp.maqami.co/"
    }
  }
}

Your own agent (OpenAI Responses API)

If you're building your own agent, the Responses API can call a remote MCP server for you. Restrict it to the tools you need with allowed_tools:

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",  # any model that supports the MCP tool
    tools=[{
        "type": "mcp",
        "server_label": "maqami",
        "server_description": "Live hotel rates, hotel details and places.",
        "server_url": "https://mcp.maqami.co/",
        "allowed_tools": ["post_hotels_rates", "get_data_places", "get_data_hotel"],
        "require_approval": "always",
    }],
    input="Find 4-star hotels in Lisbon for Nov 12 to 15, 2 adults, EUR, guest nationality GB.",
)
print(resp.output_text)

With require_approval: "always" the API returns an mcp_approval_request first. Approve it by sending an mcp_approval_response with previous_response_id, or set require_approval to "never" for read-only tools once you trust the server. The OpenAI Agents SDK wraps the same config in HostedMCPTool(tool_config={...}).

Step 2: Try these prompts

Copy any of these into your client once it's connected:

Hotel search with the four inputs it needs

"Find 4-star hotels in Lisbon for Nov 12 to 15, 2 adults, prices in EUR. I'm a UK resident. Show the 5 lowest total prices."
Compare rooms and cancellation terms

"For the second hotel, show up to 3 room options with the meal plan, total price and free-cancellation deadline for each."
Plain-language search plus reviews

"Find a quiet boutique hotel with a spa near the old town in Dubrovnik. Show details and photos for the best match and summarize what guests say about noise."
Flights and a hotel in one conversation

"Economy flights from Cairo to Istanbul, out Nov 12 and back Nov 16, 1 adult, USD, nonstop only. Then find 4-star hotels in Sultanahmet for those nights, 1 adult, USD, nationality EG."
Place lookup plus weather

"Look up Shibuya Station in Tokyo, show hotels within 1 km with their lowest rate for Dec 3 to 5, 1 adult, USD, nationality US, and tell me the weather forecast for those dates."

What comes back

You get real hotels with IDs, live rates in your currency, room names, meal plans and cancellation policies, plus hotel details, reviews and weather. Flight results include carriers, times, stops and fares. Your client shows the arguments and raw response of every call, which is handy for debugging.

Rates are live, so re-run a search before you quote a price to anyone.

Two things to know

Booking tools create real reservations. The server has a prebook → book flow. Prebook re-checks the price and shows the cancellation policy; book confirms the reservation with guest and payment details. If you're only prototyping search, keep tool approval on (most clients ask before running a tool by default, and ChatGPT developer mode asks for any tool not marked read-only) or switch the booking tools off in your client's per-tool settings.

Shorter tool lists work better. The server exposes a broad tool set. If you only need search, turn off what you don't use (or use allowed_tools in the Responses API). Models pick the right tool more reliably from a short list.

Wrap-up

One URL, no key, and your agent can answer "what's available and what does it cost?" from live data.

Endpoint: https://mcp.maqami.co/
Listings: the official MCP Registry (io.github.negm17111995/maqami-travel), Glama and mcp.so

Feedback on tool naming and descriptions is very welcome, especially from people building travel agents. Connect here: https://mcp.maqami.co/

How to give Claude the ability to book hotels in 3 minutes

Ahmed Gamal Abdou Ahmed — Fri, 03 Jul 2026 21:54:25 +0000

A quick tutorial on how to use the open-source MAQAMI Travel MCP server to give Claude real-world agency.
AI agents are incredibly smart, but they have one massive limitation: they are trapped in a chat box. They can give you travel advice, but they can't actually book the hotel for you.

Until now.

With the release of Anthropic's Model Context Protocol (MCP), we can finally give Claude tools to take action in the real world.

Today, I'm excited to share an open-source project we built: the MAQAMI Travel MCP Server. It exposes live pricing, availability, and direct booking links for over 3 million hotels across 249 countries directly to your AI agent.

Here is how you can set it up in under 3 minutes.

🛠️ What it can do
Once connected, your Claude Desktop app gets access to 65 powerful travel tools. You can literally just type:

"Find me a 5-star hotel in Dubai near the Burj Khalifa for next weekend under $300 a night."

Claude will intelligently use the MCP server to:

Search live inventory.
Fetch the exact pricing and photos.
Generate a direct booking link for you to complete the transaction.
(Insert your screenshot here showing Claude successfully running a hotel search!)

🚀 How to Install (No API Keys Required)
The best part? You don't need any complex API keys or environment variables to get started. The server is completely public and runs via Server-Sent Events (SSE).

Step 1: Open your Claude config
If you are using Claude Desktop, open your configuration file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Step 2: Add the MAQAMI Server
https://github.com/negm17111995/mcp-server
Copy and paste this snippet into your mcpServers object:

json

{
"mcpServers": {
"maqami-travel": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse",
"https://mcp.maqami.co/sse"
]
}
}
}
Step 3: Restart Claude
Completely close the Claude Desktop app and open it again. You will now see a little "hammer" icon indicating that Claude has access to the MAQAMI tools!

🧑‍💻 The Magic Behind It
If you're curious about how this works under the hood, the server exposes endpoints like post_hotels_rates and get_data_hotel. When you ask a natural language question, Claude figures out the exact parameters (like destination codes, check-in dates, and currency) and fires the API request through the MCP proxy.

It effectively turns Claude into a fully autonomous travel agent that doesn't hallucinate pricing, because it's fetching real-time data from the MAQAMI global inventory.

🔗 Try it out and contribute!
We are just scratching the surface of what Agentic AI can do.

If you want to play around with it, you can check out the source code and documentation on GitHub: 👉 MAQAMI MCP Server Repository

Let me know in the comments if you build anything cool with it, or if you have any feature requests! If you find it useful, a ⭐️ on GitHub goes a long way.

Happy building! 🚀