> For the complete documentation index, see [llms.txt](https://docs.mailtrap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailtrap.io/integrations/guides/vercel/connect.md).

# Vercel Connect

Step-by-step guide on how to connect Mailtrap to your application hosted on Vercel through Vercel Connect.

Vercel Connect lets your Vercel apps and AI agents request Mailtrap credentials at runtime instead of storing an API key in environment variables.&#x20;

{% hint style="info" %}
If you'd rather have Mailtrap credentials added to your project as environment variables, use the [native Vercel integration](https://docs.mailtrap.io/guides/integrations/vercel) instead.
{% endhint %}

#### **Prerequisites**

* Admin rights for your Mailtrap account.
* A [verified sending domain](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain) set up within Mailtrap (for sending emails).
* An existing Vercel account with one or more projects.

### Step-by-step integration guide

{% stepper %}
{% step %}

### Create a Mailtrap API token

* Log in to your Mailtrap account.
* Navigate to **Settings** → [**API Tokens**](https://mailtrap.io/settings/api-tokens).
* Click **Add Token** and give it permissions for the domains, sandboxes, and inboxes your app uses.

<div align="left" data-with-frame="true"><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FBtZaiHJN67XDntlWAYrq%2FPasted%20image%202026-11-18%2006.15.38.png?alt=media&amp;token=41df0c41-0403-4721-8529-9af7a637246c" alt=""></div>

* Copy the token since you'll need it in the next step.

<div align="left" data-with-frame="true"><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FIVNbIzFAICuXcjGod8uv%2FPasted%20image%202026-11-18%2006.16.59.png?alt=media&amp;token=677cd475-b6a0-40b2-9cf3-ea0a79f24fb5" alt="" height="256" width="624"></div>
{% endstep %}

{% step %}

### Create the Mailtrap connector

* Open the [Mailtrap connector](https://vercel.com/connect/mailtrap) page or search for it on the Browse Connectors page.

<div align="left" data-with-frame="true"><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2Ft8oZSDXYEiSq8oHskmJR%2FPasted%20image%202026-11-18%2006.17.56.png?alt=media&amp;token=286065b3-722f-45e5-a74c-f9e00e52dba5" alt="" height="243" width="624"></div>

{% hint style="info" %}
Using an AI coding agent? On the Mailtrap connector page, click **Copy Prompt** and paste it into Claude Code, Cursor, or a similar agent to have it set up the connector for you. Keep in mind that you’ll still need a Mailtrap API token from the first step.
{% endhint %}

* In the **Configure** window, fill in the following:
  * **Name** – A name for the connector, for example `acme-mailtrap`.
  * **UID (optional)** – The ID you'll use in your code, for example `mailtrap/acme-mailtrap`. If left empty, Vercel generates it from the name.
  * Select **Shared API Keys** to store one Mailtrap token on the connector for all users of your app.
  * **Key** – Paste the Mailtrap API token you created in the previous step.
  * **Expiration (optional)** – Leave as *No expiration*, or set a date to match your token rotation policy.

<div align="left" data-with-frame="true"><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FQBPeSQdIMJ9pJUXXRDBr%2FPasted%20image%202026-11-18%2006.18.45.png?alt=media&amp;token=5de66436-a1de-46a2-b422-fa3e1c6bcc05" alt="" width="563"></div>

* Click **Create Connector**, then **Continue** on the following window.

<div align="left" data-with-frame="true"><figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FyiRidfGggsbSOY8G78wa%2Funnamed%20(1).png?alt=media&amp;token=dd11c478-c2d9-4415-b7e4-c6af4dfc8b2a" alt="" width="375"><figcaption></figcaption></figure></div>

When your Mailtrap API token expires, Mailtrap API requests stop until you add a new token. To replace it, open the connector in Vercel and update the key under **Settings**.
{% endstep %}

{% step %}

#### Verify the integration in Vercel

Once you create the connector, confirm that the Mailtrap credential is configured and the connector is active on the connector page:

<div align="left" data-with-frame="true"><figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FWvYCU9UfCcxQTOfH3XE3%2FScreenshot%202026-11-17%20at%2016.45.43.png?alt=media&amp;token=e7c080e5-7d66-4321-b7b4-9ee88684d8e4" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Connect your Vercel project

* On the connector page, click **Connect Project**.

<div align="left" data-with-frame="true"><figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FcH1oaWWcKG7ggqN1IPFA%2FScreenshot%202026-11-17%20at%2017.08.21.png?alt=media&amp;token=fafd891b-814f-4961-a3f7-27f0865a4a1f" alt=""><figcaption></figcaption></figure></div>

* Select the project and the environments that should have access.

<div align="left" data-with-frame="true"><figure><img src="https://365478608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgkNigAKiqQtQub1GOdjY%2Fuploads%2FmaRlgg3JBM2QxUUDQefm%2FScreenshot%202026-11-17%20at%2017.08.51.png?alt=media&amp;token=0ce159a0-28f9-4d4b-9e93-4de81867fc5d" alt=""><figcaption></figcaption></figure></div>

And that's it! Your project can now request Mailtrap credentials from its builds and runtime.

To use the connector during local development, run `vercel link` and `vercel env pull` in your project folder.
{% endstep %}
{% endstepper %}

### How to test the integration

To confirm the connector works before building it into your app, you can run a quick check from your project folder.

{% hint style="info" %}
For this test to work, you'll need to&#x20;

* Install Vercel CLI (`npm i -g vercel`)

* Log in (`vercel login`)

* Have Node.js 20.6 or later installed

* Have your project connected to the connector with the Development environment selected
  {% endhint %}

* **Open a terminal and go to your project’s root folder:**

```bash
cd <path-to-your-project>
```

If you don’t have your project’s code locally (for example, if you built the app with v0), create an empty folder for the test instead:

```bash
mkdir mailtrap-test && cd mailtrap-test
```

The test doesn’t need your project’s code. In step 3, you’ll link this folder to your existing Vercel project.

**Important**: Run all of the following commands from this folder, not from your home directory.

* **Install the Vercel Connect SDK, if you haven’t already:**

```
npm install @vercel/connect
```

* **Link the folder to your Vercel project and pull its credentials:**

```
vercel link
vercel env pull
```

When prompted, select the project you connected to the connector.

* **Create a file named `test.mjs` in the same folder by running the following command (it writes the test code into the file):**

Replace `<CONNECTOR_NAME>` with the part of the UID after `mailtrap/` shown on your connector page.

```bash
cat > test.mjs << 'EOF'
import { getToken } from '@vercel/connect';

const token = await getToken('mailtrap/<CONNECTOR_NAME>', { subject: { type: 'app' } });

const res = await fetch('https://mailtrap.io/api/accounts', {
  headers: { Authorization: `Bearer ${token}` },
});
console.log(res.status, await res.json());
EOF
```

* **Run the file:**

```bash
node --env-file=.env.local test.mjs
```

If you see status 200 and your Mailtrap account details, the integration works. Feel free to delete test.mjs, or the whole test folder, afterward.

{% hint style="danger" %}
If you used an empty test folder, don’t run `vercel deploy` from it. That would replace your live app with the test file.
{% endhint %}

### How to use the Mailtrap connector in your application

* Install the Vercel Connect SDK:

```bash
npm install @vercel/connect
```

* Then request the Mailtrap credential from server-side code using your connector UID:

```bash
import { getToken } from '@vercel/connect';

const token = await getToken('mailtrap/<CONNECTOR_NAME>', { subject: { type: 'app' } });
```

* Use the returned token to authenticate Mailtrap API requests:

```bash
const headers = {
  Authorization: `Bearer ${token}`,
  'Content-Type': 'application/json',
};
```

{% hint style="info" %}
Replace `<CONNECTOR_NAME>` with the part of the UID after mailtrap/ shown on your connector page.
{% endhint %}

### Use cases

Some of the most common use cases include:

* **An AI-built app that sends email** – You’ve built an app with[ v0](https://v0.app) or the[ AI SDK](https://vercel.com/ai-sdk), Vercel’s toolkit for adding AI to apps, and want it to send signup confirmations, password resets, or receipts through the[ Mailtrap Email API](https://mailtrap.io/email-api/). The connector supplies the API key, so it never appears in your app’s code.
* **An AI agent with an email tool** – Your agent can send emails or look things up in Mailtrap, while the model itself never sees the API key.
* **Inbound agents** – Your agent gets its own email address and reads incoming messages through the[ Inbound Email API](https://docs.mailtrap.io/inbound-email/overview), for example to handle support requests or process replies.
* **Test email workflows** – Send messages to [Email Sandbox](https://mailtrap.io/email-sandbox/) and inspect them without delivering anything to real recipients.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mailtrap.io/integrations/guides/vercel/connect.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
