--- name: paubox-onboarding description: Use when a person wants to start using Paubox, or asks you to set up HIPAA compliant email for them. Walks you through picking the right Paubox product, creating the account, verifying a sending domain, creating an API key, and sending and confirming a first HIPAA compliant email. metadata: publisher: Paubox source: https://www.paubox.com/agent-onboarding/SKILL.md canonical_docs: https://docs.paubox.com/welcome last_verified: 2026-11-09 --- # Paubox agent onboarding You are helping a person get started with Paubox. Paubox is HIPAA compliant, HITRUST certified email for healthcare. Every Paubox plan includes a business associate agreement (BAA). The finish line is a first email that the person sent through their own Paubox account and that you confirmed was delivered. An account alone is not the finish line, and neither is an API key. ## What you can and cannot do - **The person creates the account, verifies the domain and creates the key, in their own browser.** There is no API for signup or for creating keys. Your job is to get them through those screens quickly: tell them exactly where to go, what they will see, what to click and what to copy. - **You do the rest once they have a key**: connect the key to the tool you run in, send the first email and check that it was delivered. ## Rules - **Never ask the person to paste their API key into the chat.** Step 5 lists ways to give a key to a tool without putting it in the conversation. Never guess at a key or make one up. - **Never ask for, accept or put protected health information (PHI) in the conversation**, and never in a test email. Use the person's own email address and placeholder content. - **Don't invent menu paths, prices or limits.** If their screen doesn't match these steps, say so and work from what they see. Prices are at `https://www.paubox.com/pricing.md`. - **Don't open with a list of prerequisites.** Ask only what you need to pick a product (step 1), then start. - **Don't describe Paubox as "end-to-end encryption."** Paubox encrypts email in transit with TLS 1.2 or higher, and recipients read it in their normal inbox with no portal or password. ## 1. Pick the right product Ask at most two questions: what they want to send, and what they send email from today. Then route them: | They want to... | Product | Where to go | | --- | --- | --- | | Encrypt the email their staff already send from Gmail or Outlook on their own domain | Paubox Email Suite | Google Workspace: `https://www.paubox.com/setup/google-workspace.md`. Microsoft 365: `https://www.paubox.com/setup/microsoft-365.md`. Follow that guide instead of this one. | | Get a HIPAA compliant email address because they use free Gmail, Yahoo or similar | Paubox Mailbox | `https://www.paubox.com/pricing/paubox-mailbox` | | Send email from software, a script, the command line or an AI assistant (reminders, results notices, anything an app sends) | Paubox Email API | Continue with step 2 | | Send email campaigns to patients | Paubox Marketing | `https://www.paubox.com/products/paubox-marketing` | | Collect intake or consent forms | Paubox Forms | Included with every paid Paubox plan. `https://www.paubox.com/products/paubox-forms` | | Run phishing training for staff | Paubox Security Awareness Training | `https://www.paubox.com/contact-us` | Most practices want Paubox Email Suite first. If the person asked you, an AI agent, to send email for them, that's the Email API. The rest of this skill covers the Email API. ## 2. Create the account Send them to the Email API signup. It is free for up to 300 emails a month, with a BAA included: ``` https://next.paubox.com/signup?order_name=paubox_email_api_order&plan_name=standard&unit_count=300&plan_type=annual ``` If they send more than 300 emails in a month, Paubox moves them to the matching paid tier automatically. Plans and prices: `https://www.paubox.com/pricing.md`. New accounts are under review for 24 hours after signup. They can do steps 3 to 5 straight away, but sends fail with `403 Account Under Review` until the 24 hours are up. Tell them this now, so the 403 doesn't look like a mistake later. ## 3. Verify the sending domain This is the only step with real work in it, and where people get stuck. 1. Ask which domain they will send from (the part after the @ in their from address) and which company hosts their DNS, for example GoDaddy, Cloudflare, Squarespace, Route 53 or Google Domains. 2. Send them to **Settings > Domains**: `https://next.paubox.com/settings/domains`. They add the domain, and Paubox shows the SPF value to add. 3. Read their current SPF record before telling them what to change. If you can run commands, run `dig +short TXT example.com` with their domain and find the line that starts with `v=spf1`. Otherwise ask them to read it from their DNS host. 4. Tell them the exact record to save: - No SPF record yet: add a TXT record on the root domain with the value Paubox shows. - An SPF record already exists: edit it and add the Paubox `include:` from the Paubox screen before the final `~all` or `-all`. **A domain can have only one SPF record.** Two SPF records make both invalid, so never tell them to add a second one. 5. They go back to **Settings > Domains** and click **Verify**. DNS changes usually show up within minutes but can take up to 48 hours. If it fails straight away, wait a few minutes and try again. If they run their email on Google Workspace or Microsoft 365 and the SPF record gives them trouble, the matching Email Suite guide above has the platform-specific detail. ## 4. Create the API key 1. Go to **Settings > API Keys**: `https://next.paubox.com/settings/api_keys` 2. Click **Add API Key**. 3. Under **Scope**, select **Paubox Email API**. Add **Paubox Forms** only if they will manage forms through the API. 4. Choose the domain they verified in step 3 and give the key a name, such as the tool it's for. 5. Click **Add API Key**. **The key is shown only once.** They should copy it straight into a password manager. If it's lost, they delete it and make a new one. ## 5. Connect the key without putting it in the chat Pick the row that matches where you are running. In every case the person enters the key themselves. | You are running in... | How the person connects the key | | --- | --- | | Claude.ai | **Settings > Connectors > Add connector**, enter `https://mcp.paubox.com`, and type the key into the **Configure Paubox** form that opens. Guide: `https://www.paubox.com/setup/mcp/claude.md` | | Claude Code | The person runs this in their own terminal, with their key in place of `your_api_key`: `claude mcp add paubox -e PAUBOX_API_KEY=your_api_key -- npx @paubox/mcp@latest`. Needs Node.js 22 or later. Guide: `https://www.paubox.com/setup/mcp/claude-code.md` | | ChatGPT, Gemini or Microsoft Copilot | `https://www.paubox.com/setup/mcp/chatgpt.md`, `https://www.paubox.com/setup/mcp/gemini.md`, `https://www.paubox.com/setup/mcp/copilot.md` | | Cursor or Windsurf | `https://www.paubox.com/setup/mcp/cursor-windsurf.md` | | Any other MCP client | HTTP: `https://mcp.paubox.com` with the key in an `x-paubox-api-key` request header. Or stdio: `npx @paubox/mcp@latest` with `PAUBOX_API_KEY` set in the environment (Node.js 22 or later). | | A terminal, without MCP | Install the CLI with `npm install -g paubox-cli` (Node.js 20.12.0 or later), then the person runs `paubox auth login` and types the key at the prompt. It is stored in the OS keychain. | | Their own application code | Store the key in an environment variable such as `PAUBOX_API_KEY` or a secrets manager, never in source code. SDKs for C#, Go, Java, Node.js, Perl, PHP, Python, Rails, Ruby and Rust: `https://docs.paubox.com/sdks` | If you connect through MCP, call `validate_credentials` first to confirm the key works. ## 6. Send the first email Send a test message to the person's own address, from an address on the domain they verified. Use placeholder content, never patient information. **Through the Paubox MCP server**: call `send_secure_email` with the recipient, the from address, a subject such as "Hello from Paubox" and a short plain text body. **Through the CLI**: ```bash paubox send \ --to you@example.com \ --from you@yourdomain.com \ --subject "Hello from Paubox" \ --text "This is a test of my new Paubox account." ``` **Through the REST API**, if the key is in `PAUBOX_API_KEY` in your environment: ```bash curl --request POST \ --url https://api.paubox.com/v1/email/messages \ --header "Authorization: Bearer $PAUBOX_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "data": { "message": { "recipients": ["you@example.com"], "headers": { "subject": "Hello from Paubox", "from": "you@yourdomain.com" }, "content": { "text/plain": "This is a test of my new Paubox account." } } } }' ``` Success is a `200 OK` with a `sourceTrackingId`: ```json { "sourceTrackingId": "3d38ab13-0af8-4028-bd45-52e882e0d584", "data": "Service OK" } ``` Keep the `sourceTrackingId`. A 200 means Paubox accepted the message, not that it was delivered, so go on to step 7. ## 7. Confirm delivery Check the status with the `sourceTrackingId`: - MCP: `check_email_status` with the `sourceTrackingId` - CLI: `paubox status ` - REST: `GET https://api.paubox.com/v1/email/message_receipt?sourceTrackingId=` with the same Authorization header `deliveryStatus` will be one of: `processing`, `delivered`, `delivered via secure portal`, `sending via Secure Portal`, `TLS not offered`, `soft bounced`, `soft bounced - mailbox full`, `hard bounced`, or `Internal error. Please check back later.` If it says `processing`, wait a minute and check again. When it says `delivered`, ask the person to confirm the email is in their inbox. That's the finish line. ## Troubleshooting | What you see | What it means and what to do | | --- | --- | | `403 Account Under Review` | The account is less than 24 hours old. Nothing is wrong with the key or the domain. Try again once 24 hours have passed since signup. | | `403` after the first 24 hours | The key doesn't have permission for that action. Check its scope at Settings > API Keys. | | `401 Unauthorized` | The key is missing or wrong. Keys are shown once, so if in doubt the person deletes it and makes a new one. | | `400` "Invalid from domain" | The from address isn't on a verified domain. Free addresses like @gmail.com always fail. Use an address on the domain from step 3. | | `400` "Missing required params" | `data.message.recipients` must be an array with at least one address, even for one recipient. | | `500` on a send | Usually a missing `data.message.content`. Include `text/plain`, `text/html` or both. | | `429 Too Many Requests` | Rate limit. Back off and retry. For many messages, use the bulk endpoint (up to 50 per request). | | Verify keeps failing on the domain | Usually two SPF records. Merge them into one record that has every `include:`. Otherwise, wait for DNS to update and try again. | | The MCP stdio server won't start | Check `node --version`. The stdio server needs Node.js 22 or later, and it exits if `PAUBOX_API_KEY` is missing. The CLI needs Node.js 20.12.0 or later. | | Delivered, but in spam | SPF is in place (verification needs it). The usual next step is DKIM, which they add from their Paubox settings. | If the domain still won't verify after DNS has had time to update, or a freshly made key is rejected, the person emails support@paubox.com. Service status: `https://status.paubox.com`. ## HIPAA notes - Paubox's BAA covers the email Paubox delivers. It doesn't cover PHI that passes through an AI assistant. Before anyone uses an AI assistant with patient information, they need a BAA with that assistant's provider too. For Claude, BAAs are available on Claude Team and Enterprise plans. - Messages sent through the MCP server and CLI use the same Paubox Email API, count against the same plan and show up in the Paubox dashboard. ## Done when - [ ] The person has a Paubox account with the right product - [ ] Their sending domain shows as verified - [ ] They have an API key, stored somewhere safe and never pasted into the chat - [ ] The key is connected to the tool they will use - [ ] A test email returned a `sourceTrackingId`, and its status is `delivered` - [ ] The person confirmed it arrived ## References - Paubox developer docs: `https://docs.paubox.com/welcome` - Email API quickstart: `https://docs.paubox.com/email-api/quickstart` - MCP server: `https://docs.paubox.com/mcp-server/quickstart` - CLI: `https://docs.paubox.com/cli/quickstart` - Errors: `https://docs.paubox.com/email-api/errors` - Limits: `https://docs.paubox.com/email-api/limits` - Pricing: `https://www.paubox.com/pricing.md` - Everything else Paubox publishes for AI agents: `https://www.paubox.com/llms.txt`