# Vercel

Add Rasket to your Vercel projects. Rasket saves an API key into each project you choose as `RASKET_API_KEY`, so your route handlers and server actions can send email on the next deploy, with nothing to copy or paste.

> Coming soon: adding Rasket from Vercel is not switched on yet. This page describes it as it will ship. Until then, add an API key to your project yourself, as the integrations guide shows.

## What it sets up

- **One key per Vercel project.** Each project you choose gets its own Sending access API key, which can send email and nothing else: it cannot read your emails, contacts or settings.
- **Saved as `RASKET_API_KEY`,** encrypted, on the Production, Preview and Development environments. If the project already has a variable by that name, it is replaced.
- **One Rasket project per install.** Every Vercel project in the install sends as the Rasket project you pick, from its verified domains, on its plan.
- **Nothing to pay on Vercel.** Vercel bills nothing for Rasket; your Rasket plan is the only plan.

## Before you start

- **An admin of the Rasket project,** with a verified email address. The keys belong to the whole project, so a member who is not an admin cannot connect it.
- **A verified sending domain,** to send from. The key works without one, but every send is refused until the domain is verified. The [domains guide](https://www.rasket.com/docs/domains) walks through it.
- **Up to 25 Vercel projects per install.** Choose the projects that send email rather than all of them.

## Add Rasket

1. In Rasket, open **Settings**, then **Integrations**, then **Vercel**, and choose **Add Rasket on Vercel**.
2. On Vercel, choose the Vercel team, then **Specific projects** and the projects that should send email, and install.
3. Rasket opens. Sign in, or create an account. Rasket names the Vercel account and every project the install reaches. Only continue if you have just added Rasket on Vercel yourself.
4. Pick the Rasket project to send as, and choose **Connect**. You are back on Vercel.
5. **Redeploy** each project. A deployment reads its environment variables when it is built, so one built before you connected has no key.

Finish within 30 minutes of choosing install on Vercel. After that, the install expires and nothing is written; add Rasket again. Each admin of the Rasket project gets one email saying new keys were created.

## Send from a route handler

Read the key from `process.env.RASKET_API_KEY` in server code only. Never copy it into a variable your framework exposes to the browser, such as one that starts with `NEXT_PUBLIC_`.

A route handler that sends a welcome email:

```text
// app/api/welcome/route.ts
export async function POST(request: Request) {
  const { email } = (await request.json()) as { email: string };
  const response = await fetch("https://api.rasket.com/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
      "User-Agent": "acme-billing/1.0",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from: "Acme <hello@example.com>",
      to: email,
      subject: "Welcome to Acme",
      html: "<p>Thanks for signing up.</p>",
    }),
  });
  return Response.json(await response.json(), { status: response.status });
}
```

Send a `User-Agent`: a request with no `User-Agent` is refused. Use an address on your verified domain in `from`. The [emails reference](https://www.rasket.com/docs/api-reference/emails) has every field a send takes.

## Send from a server action

A server action that sends a welcome email:

```text
// app/actions.ts
"use server";

export async function sendWelcome(formData: FormData) {
  const email = String(formData.get("email"));
  const response = await fetch("https://api.rasket.com/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
      "User-Agent": "acme-billing/1.0",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from: "Acme <hello@example.com>",
      to: email,
      subject: "Welcome to Acme",
      html: "<p>Thanks for signing up.</p>",
    }),
  });
  if (!response.ok) {
    throw new Error(`The welcome email was not sent (${response.status}).`);
  }
}
```

A server action runs on the server, so it reads `RASKET_API_KEY` the same way. Call it from a form's `action`.

## Local development

The Development environment has the key too, so the Vercel CLI can bring it to your machine:

Pulling the development variables:

```text
vercel env pull .env.local
```

Keep `.env.local` out of version control. Next.js reads it when you run `next dev`.

## Managing it

- **See your installs** under Settings → Integrations → Vercel in Rasket: each Vercel account, its projects and the start of each key. On Vercel, the integration's **Configure** button opens the same page.
- **Adding Rasket again** to the same projects replaces each key: the new one is saved first, then the old one is revoked. Redeploy afterwards, because deployments built with the old key can no longer send.
- **Projects added later are not picked up.** Giving the install more projects on Vercel writes no key into them. Disconnect, then add Rasket again with the projects you want.
- **A deleted Vercel project's key stays live** until you disconnect the install it came from.

## Disconnect

Either way revokes every key the install created:

- **In Rasket,** an admin chooses **Disconnect** on Settings → Integrations → Vercel. Rasket revokes the keys, then removes `RASKET_API_KEY` from the Vercel projects and removes the integration from the Vercel account.
- **On Vercel,** remove the Rasket integration. Rasket revokes the keys when Vercel tells it.

Revoked keys stop working at once, including in deployments that are already running. Keys you created yourself under API keys are not touched.

## Troubleshooting

### “Vercel isn't available here”

Adding Rasket from Vercel is not switched on for this deployment. Create a Sending access key under API keys and add it to the project as `RASKET_API_KEY` yourself; the [integrations guide](https://www.rasket.com/docs/integrations) shows how.

### “Vercel didn't accept this install” or “This install has expired”

The link from Vercel was used already, or more than 30 minutes passed. Nothing was written. Add Rasket on Vercel again.

### “This install can't reach any Vercel project” or more than 25 projects

On Vercel, change the install to the projects that should send email, between one and 25, then add Rasket again.

### “Already connected to another Rasket project”

Each Vercel install sends as one Rasket project. Disconnect it in the other project first, or ask an admin of that project to.

### No Rasket project to pick

Only projects you are an admin of are offered. Ask an admin to make you one, or to add Rasket themselves.

### Sends are refused after connecting

A `401` means the deployment still has an old key or none: redeploy. A refusal naming the `from` address means the domain is not verified for sending yet. The [errors page](https://www.rasket.com/docs/errors) lists every refusal.