> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to obtain and pass credentials to the Paubox MCP Server.

The Paubox MCP Server authenticates against the Paubox Email API on your behalf. You provide your API key once when configuring the server; it is never sent to the AI model.

<Steps>
  <Step title="Sign up for a Paubox account">
    If you don't have one, [sign up for Paubox Email API](https://www.paubox.com/pricing/paubox-email-api). Free tier includes up to 300 emails per month.
  </Step>

  <Step title="Add and verify your domain">
    Go to [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) and add the domain you will send from. Complete domain verification before generating an API key; unverified domains cannot send email.
  </Step>

  <Step title="Generate an API key">
    From [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings), click your domain, then press **Add API Key**. Give the key a description and save it immediately; it is displayed only once.

    You will also need your **API username**, shown on the same settings page.
  </Step>

  <Step title="Pass credentials to the MCP server">
    The server resolves credentials using the following priority order. Use whichever method fits your client:

    **1. OAuth connector form (recommended for Claude.ai and Claude Desktop)**

    Add `https://mcp.paubox.com` as a connector. The client presents a **Configure Paubox** form automatically. Enter your API username and API key once; the client stores a short-lived encrypted Bearer token and sends it on every subsequent request.

    **2. Custom request headers**

    Some MCP clients let you set custom headers on the connector. Pass:

    ```
    x-paubox-api-key: your_api_key
    x-paubox-api-user: your_api_username
    ```

    **3. Environment variables (stdio / Claude Code)**

    ```bash theme={null}
    export PAUBOX_API_KEY=your_api_key
    export PAUBOX_API_USER=your_api_username
    ```

    Claude Code / stdio config:

    ```json theme={null}
    {
      "mcpServers": {
        "paubox": {
          "command": "npx",
          "args": ["-y", "@paubox/mcp@latest"],
          "env": {
            "PAUBOX_API_KEY": "your_api_key",
            "PAUBOX_API_USER": "your_api_username"
          }
        }
      }
    }
    ```

    **4. Per-call tool parameters (any transport)**

    Pass `apiKey` and `apiUser` directly in each tool call. This takes the highest runtime priority and overrides any other credential source. Useful for scripted clients or one-off requests.
  </Step>
</Steps>

<Note>
  Never commit API keys to source control. Use environment variables or a secrets manager to inject credentials at runtime.
</Note>

## Required permissions

| Tool                   | Credential required                   |
| :--------------------- | :------------------------------------ |
| `send_secure_email`    | Paubox Email API key with send access |
| `check_email_status`   | Paubox Email API key with read access |
| `validate_credentials` | Any valid Paubox Email API key        |
| `get_form`             | None (public endpoint)                |
| `submit_form`          | None (public endpoint)                |

A single API key generated from the Paubox Email API settings page covers all authenticated tools. The `get_form` and `submit_form` tools call public Forms API endpoints and require no credentials.