# Your first real API key — get your projects sending email (Kit 6)

Every kit so far handed Claude a key: Cloudflare, your storage, your registrar. Those keys manage
your setup. This one is different. This is the first key that makes something happen for other
people: your projects can send email. A welcome message, a receipt, a password reset, a note to
you when something breaks. All of it runs on one key you create once and hand to Claude.

So this kit does two jobs. It gets your email working, and it teaches you what an API key actually
is, because from here on almost everything you add is "make an account, get a key, give it to
Claude." Learn the shape once and the rest of the internet opens up.

I use Mailgun for this. It's built to send email from code (not a human clicking "compose"), it
plays nicely with the Cloudflare foundation you already built, and it has the two-tier key setup
that makes the security part easy to teach.

## What an API key actually is (read this once)
When you log into a website, you type a password. But your code, and your AI, talk to services
with no human clicking anything. So they prove who they are a different way: an **API key**. It's
just a long secret string that says "this request is really me."

Three things to hold onto:
1. **You create it once** in the service's dashboard, and hand it to your tool. From then on, the
   tool acts as you, no login screen.
2. **Whoever holds the key can act as you** (send email, spend your money). So it's a secret you
   guard exactly like a password. It's usually shown only once, so you copy it and store it safe.
3. **Good services let you make a scoped key** that can do only one narrow thing. Mailgun does: a
   key that can *only send email for one domain*, nothing else. If it ever leaks, the damage is
   contained. That's the key you give Claude.

That's the whole concept. Email is just the first place you use it.

## Prerequisite
- The Cloudflare account from Kit 3 (your DNS lives there — Claude adds Mailgun's records for you).
- The domain from Kit 5 (email sends *from* your own domain, like you@yourdomain.com).
- Kit 1's terminal, so Claude can run the setup and the test send.
- A safe home for the key. If you set up the vault from the 5.1 note, drop it there. If not, keep
  it out of any file you commit.

## How to use it (any OS)
- **Quick:** hit Copy, open Claude Code, paste this in, and say the line below.
- **Most reliable:** hit Download, then tell Claude:
  *"read ~/Downloads/mailgun-email-setup.md and set it up with me."*

Either way, say:

> "Help me set up Mailgun so my projects can send email from my own domain. Walk me through
> creating a Mailgun account and picking a region (US or EU), then add my domain as a sending
> domain. Using my Cloudflare account from Kit 3, add the DNS records Mailgun asks for: the SPF
> (TXT) and DKIM (TXT) records, and the tracking CNAME. Do NOT add Mailgun's MX records unless I
> tell you I want to receive mail there, so we don't break my existing email. Then verify the
> domain and tell me when it passes. Create a domain-scoped SENDING key (not my full account key),
> store it safely, and send one test email to me so I can see it land. Remember my region so we
> always use the right API URL. Tell me exactly which clicks are mine as we go."

## What it sets up

**1. A Mailgun account, in a region you pick.** At signup you choose **US or EU**. This matters:
your API URL is `api.mailgun.net` for US and `api.eu.mailgun.net` for EU, and using the wrong one
fails even when your key is correct. Pick one, and Claude remembers it.

**2. Your domain added as a sending domain.** You send from your own name (you@yourdomain.com),
not a generic address. New accounts also get a free **sandbox** domain for testing, but it can
only email up to 5 addresses you pre-approve. To reach real people you verify your own domain,
which is the next step.

**3. The DNS records, added to your Cloudflare (Kit 3).** Mailgun gives you a short list; Claude
adds them to Cloudflare for you:
- **SPF** (a TXT record) — says "these servers are allowed to send as my domain." Required.
- **DKIM** (a TXT record) — a cryptographic signature proving the mail really came from you and
  wasn't tampered with. Required. (Cloudflare handles the long-key formatting automatically.)
- **Tracking** (a CNAME) — lets Mailgun track opens and clicks. Optional but nice.
- **MX records — skip these unless you want to RECEIVE mail at this domain.** MX is for inbound.
  If you already get email at your domain, adding Mailgun's MX would break it. Sending needs only
  SPF + DKIM. Claude will ask before touching MX.

**4. Verification.** Claude clicks (or calls) "verify," Cloudflare's records propagate (usually
minutes, occasionally longer), and Claude tells you the moment it passes. A verified domain lifts
the 5-recipient limit and drops the "sent via mailgun" tag.

**5. A domain-scoped sending key, handed to Claude.** Mailgun has two kinds of keys: a full
**account key** (can do everything) and a **sending key** scoped to one domain's send endpoint.
You give Claude the **sending key**. If it ever leaks, all it can do is send mail for this one
domain, not touch your whole account. Store it in your vault; it's shown once.

**6. A test send.** Claude fires one email to you through the API. When it lands, you're done, and
"email me when the order comes in" is now a sentence Claude can act on.

## Security — the part not to skip
- **Give Claude the sending key, never the account key.** Least privilege: contain the blast
  radius to one domain's outbox.
- **Store the key in your vault or an env var**, never hardcoded, never committed to a repo, never
  pasted into a public thread. (This is what the 5.1 note was for.)
- **Rotate it** every so often, or immediately if you think it leaked. Make a new key, switch
  Claude to it, then delete the old one. Zero downtime.
- **Match your region.** US key + EU URL (or the reverse) will just fail. Note your region once.
- **Let SPF and DKIM actually pass.** A typo'd record can "verify" but still land you in spam.
  Adding a DMARC record on top is the standard finishing touch for good delivery.

## If Claude needs the exact specs
Send endpoint: `POST /v3/{domain}/messages`. Base URL by region: US `https://api.mailgun.net`,
EU `https://api.eu.mailgun.net`. Auth is HTTP basic auth: username `api`, password = your sending
key (not a bearer token). Body is `multipart/form-data` with `from`, `to`, `subject`, and at least
one of `text` or `html`. Minimal test:

```
curl -s --user 'api:YOUR_SENDING_KEY' \
  https://api.mailgun.net/v3/YOUR_DOMAIN/messages \
  -F from='You <you@YOUR_DOMAIN>' \
  -F to=you@example.com \
  -F subject='It works' \
  -F text='Sent from my own domain, by Claude.'
```

A success returns a queued message id. DNS to add on the Cloudflare side: SPF TXT
(`v=spf1 include:mailgun.org ~all`), the DKIM TXT Mailgun provides, and the tracking CNAME. Leave
MX alone unless the domain is meant to receive. Official SDKs exist (Python, Node, PHP, Ruby, Go)
if you'd rather a library than curl.

## Cost, straight
The free plan sends 100 emails a day and needs no card to sign up, which is plenty to build and
test on. To send to real people from your own domain, plan on adding a card (and the entry paid
tier is about fifteen dollars a month once you outgrow free). Same theme as the last few kits: the
basics are cheap, and now your projects can talk to the world instead of just sitting there.

## Make it stick
Region noted, domain verified, sending key in your vault and handed to Claude. From then on,
sending an email is one instruction. Wire it into anything: a note to yourself when a sale hits, a
welcome message to a new signup, an alert when something breaks at 3am.

You're done when: your domain is verified in Mailgun, Claude holds a domain-scoped sending key, and
a test email from you@yourdomain.com actually landed in your inbox.

That's Kit 6. You created your first real API key, you understand what it is, and your projects can
send email. Next up, the small server your site actually lives on, and then we finally put
something online.

-- Cliff (connectwithcliff.com)