Desk Frog Mail 🐸

Email marketing made simple. Free with the Desk Frog badge, paid plans remove it. Next.js 15 · Supabase (Postgres + Auth) · Amazon SES.

Dashboard: deskfrogmail.com · API: deskfrogmail.com/api/v1

How it works

App (ArgusIQ, Midas, …) ──API key──▶ /api/v1/*  ──▶ messages table (the queue)
Dashboard user ──────────────────────▶ server actions ─┘          │
                                                               worker (every minute)
                                                                   │  claim_messages() — SKIP LOCKED
                                                                   ▼
                                                           Amazon SES ──events──▶ SNS ──▶ /api/ses/events
                                                                                         (bounce/complaint → suppress,
                                                                                          open/click → stats, webhooks out)

• Multi-tenant: everything is scoped by workspace_id. Dashboard users go through RLS; the API and worker use the service role.
• Plans live in the plans table (AUD/month incl. GST, yearly = 10× monthly): Free $0 (500 contacts, 1,000 sends, badge) · Tadpole $19 (1,500 / 9,000) · Bullfrog $59 (5,000 / 30,000) · King Frog $129 (15,000 / 90,000). Over 15,000: custom. (The club row is retired.) Limits are enforced when queuing: contacts, monthly sends, daily sends. New workspaces are capped at 100/day for their first 7 days.
• Free plan sends from <workspace-slug>@SHARED_SENDING_DOMAIN with the customer's address as Reply-To, and every email carries the badge. Paid plans send from their own verified domain.
• Compliance (Spam Act / Gmail+Yahoo bulk rules): consent source recorded per contact, footer with sender identification and an unsubscribe link, RFC 8058 one-click List-Unsubscribe headers, unsubscribes honoured instantly.
• Abuse guardrails: hard bounces and complaints go on a global suppression list. Workspaces auto-pause at a 4% bounce or 0.08% complaint rate (30 days, after 100 sends).

Setup

1. Supabase

Migrations are in supabase/migrations (already applied to project tbvcxjztgvcwifygdcjf). Auth → enable email/password. Set the Site URL to https://deskfrogmail.com.

2. Amazon SES (region ap-southeast-2)

1. Verify the shared sending domain (e.g. send.deskfrogmail.com). Not deskfrog.studio, which keeps the studio's mail reputation clean. Add the DKIM CNAMEs, plus SPF/DMARC.
2. Create a configuration set deskfrog-mail:
   • turn on open and click tracking
   • add an event destination → SNS topic, with events Send, Delivery, Bounce, Complaint, Reject, Open, Click, Rendering failure
3. Subscribe the SNS topic over HTTPS to https://deskfrogmail.com/api/ses/events. The subscription is confirmed automatically, and signatures are verified.
4. Create an IAM user with ses:SendEmail, ses:CreateEmailIdentity and ses:GetEmailIdentity.
5. Request production access (out of the sandbox). Describe the double opt-in, the consent checkbox, the automatic bounce/complaint suppression and auto-pause.

3. Environment

Copy .env.example to .env.local and fill it in.

4. Worker

Call POST /api/cron/worker with Authorization: Bearer $CRON_SECRET every minute. It releases scheduled campaigns, drains the queue at SES_MAX_PER_SECOND, and delivers webhooks. Options:

• Vercel Cron (minute schedules need the Pro plan)
• Supabase pg_cron + pg_net:

  select cron.schedule('deskfrog-worker', '* * * * *', $$
    select net.http_post('https://deskfrogmail.com/api/cron/worker',
      headers => jsonb_build_object('Authorization', 'Bearer <CRON_SECRET>'));
  $$);
  

API

All requests: Authorization: Bearer dfm_live_… (create keys in Settings). JSON in, { data } or { error: { code, message } } out.

Method	Path
GET / POST	/contacts	List (filters: status, tag, email, external_id) / upsert one or { contacts: [...] } up to 1000. consent_source is required
GET / PATCH / DELETE	/contacts/:id	add_tags, remove_tags, fields, status: "unsubscribed"
GET / POST	/lists
POST / DELETE	/lists/:id/members	{ contact_ids } or { emails }
GET / POST, GET / PATCH / DELETE	/templates, /templates/:id
GET / POST	/campaigns	Draft from html or template_id; target list_id and/or tag_filter
GET / PATCH / DELETE	/campaigns/:id	DELETE cancels a scheduled or sending campaign
POST	/campaigns/:id/send	Send now, or { scheduled_at }
GET	/campaigns/:id/stats
POST	/send	Transactional email to one recipient. data for {{merge}} and idempotency_key supported
GET / POST, DELETE	/webhooks, /webhooks/:id	The secret is returned once
GET / POST, GET / DELETE	/domains, /domains/:id	Paid plans. GET re-checks verification
GET	/usage	Plan, limits and usage

Merge tags: {{first_name}}, {{last_name}}, {{email}}, any key in fields, with fallbacks: {{first_name|racer}}.

Example: ArgusIQ syncing an entrant

curl -X POST https://deskfrogmail.com/api/v1/contacts \
  -H "Authorization: Bearer $DFM_KEY" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","first_name":"Jess","external_id":"argus-member-123",
       "tags":["budget-enduro","2026-season"],"fields":{"class":"Outright","car_number":"42"},
       "consent_source":"argusiq_entry_form"}'

Webhooks

Events: email.sent, email.delivered, email.bounced, email.complained, email.opened, email.clicked, email.failed, contact.unsubscribed, workspace.paused.

Verify DeskFrog-Signature: t=<unix>,v1=<hex>, where v1 = HMAC_SHA256(secret, "<t>.<raw body>"). Reject anything where t is older than 5 minutes. Failed deliveries retry with backoff (1m → 24h).

This is the beginning of the README. Read the rest at the original. Read the full README ↗