# Agentline NZ: full documentation for agents > Your own NZ 028 mobile number and @agentline.nz inbox, over MCP (https://agentline.nz/mcp) and REST (https://agentline.nz/api/v1). Free trial: 7 days on paid plans, card required. ## Quickstart (for agents) Agentline gives an AI agent its own **New Zealand 028 mobile number** (two-way SMS, voice on Pro) and an **@agentline.nz email inbox**, through MCP and a REST API. 1. **Connect.** MCP server (Streamable HTTP): `https://agentline.nz/mcp`. OAuth 2.1 sign-in, or `Authorization: Bearer al_live_…` with an API key. 2. **No account yet?** Call `signup` on the keyless server `https://agentline.nz/public/mcp` (or `POST https://agentline.nz/api/v1/signup`, or `agentline signup --owner-email …`) with your human's email. You get an API key, an inbox and an MCP config straight away. 3. **Call `get_my_number`** to learn your number and email address. 4. **Receive a code:** give a service your number or email, then call `wait_for_code`. 5. **Send:** `send_sms` / `send_email`. Confirm recipients and wording with your user first. Until your human verifies (the link we email them) and keeps your API key, you can send only to their email and mobile, 5 messages a day. A paid plan needs them to add a card. ## Authentication - **OAuth 2.1 + PKCE** (for ChatGPT, Claude, Cursor, VS Code…): discovery starts from the 401's `WWW-Authenticate: Bearer resource_metadata="https://agentline.nz/.well-known/oauth-protected-resource/mcp"`. Client ID Metadata Documents and Dynamic Client Registration (`https://agentline.nz/oauth/register`) are supported. Scopes: `messages:read` (required), `messages:send`, `offline_access`. - **API key**: `Authorization: Bearer al_live_…` on `https://agentline.nz/mcp` and `https://agentline.nz/api/v1/*`. Create keys in the dashboard, with `create_api_key`, or with `agentline keys create`. - **Keyless**: `https://agentline.nz/public/mcp` needs no credentials. It's read-only plus `signup`, can't send anything for you, and is rate limited (60 requests/minute per IP). ## MCP tools Authenticated server (`/mcp`). Every tool carries readOnlyHint/destructiveHint/openWorldHint annotations. | Tool | Scope | What it does | | --- | --- | --- | | `get_my_number` | read | Your number(s), inbox(es), plan, allowances and any sending restriction. Call first. | | `wait_for_code` | read | Wait up to 55s for a one-time code by SMS or email; each code returned once. | | `send_sms` | send | Text a NZ mobile from your number. Transactional only; marketing is blocked. | | `list_messages` | read | Recent SMS, newest first (filter by direction, contact, unread_only, since). | | `read_message` | read | One SMS by id. | | `send_email` | send | Email from your @agentline.nz address (up to 5 recipients). | | `list_emails` | read | Recent emails, newest first (filter by direction, unread_only, since). | | `read_email` | read | Full email text by id. Reading never changes read state. | | `mark_read` | read | Mark SMS and emails read (or unread with read=false), up to 100 ids. | | `list_calls` | read | Calls and voicemail transcripts. | | `get_voice_settings` | read | Call handling for each number. | | `update_voice_settings` | send | Replace call handling: greeting/voicemail, or forward to SIP (e.g. ElevenLabs), wss:// stream or a phone. | | `list_api_keys` | read | API keys (prefix, name, last used). | | `create_api_key` | send | New API key; secret shown once. | | `revoke_api_key` | send | Revoke a key (destructive). | | `start_owner_phone_verification` | send | Get a code the owner texts from their mobile to verify it (replaces any verified mobile). | | `verify_owner` | send | Submit the SMS code Agentline texted your owner at signup to confirm their mobile. | | `list_audit_log` | read | Recent account events. | | `get_billing` | read | Plan, status, trial end, allowances. | | `get_checkout_link` | send | Stripe Checkout link to start a plan, emailed to the owner and returned. | | `get_billing_portal_link` | send | Stripe Customer Portal link (card, plan, cancel), also emailed to the owner. | | `get_profile` | read | Which account is connected. | Keyless server (`/public/mcp`): no tool can send anything. | Tool | What it does | | --- | --- | | `get_pricing` | Plans, prices (NZD), allowances and trial terms. | | `check_number_availability` | Whether NZ 028 numbers are available and how long setup takes. | | `get_docs` | These docs by topic: quickstart, auth, tools, rest, codes, sms-rules, signup, pricing, human, errors. | | `get_install_instructions` | Install steps for an MCP client (claude, chatgpt, cursor, vscode, …). | | `signup` | Create your own account in one call with your human's email (and NZ mobile, optional): returns an API key, inbox and MCP config. Emails your human a verification link. | ## REST API Base `https://agentline.nz/api/v1`, JSON, `Authorization: Bearer al_live_…`. OpenAPI: `https://agentline.nz/openapi.json`. | Method | Path | Does | | --- | --- | --- | | POST | /signup | Agent self-signup (no auth): `{owner_email, owner_mobile?, agent_name?}` → api_key, inbox, mcp config, restrictions | | GET | /me | Account, numbers, inboxes, usage, restrictions | | GET/POST | /sms | List / send SMS `{to, body, from?}` | | GET | /sms/{id} | One SMS | | GET/POST | /emails | List / send email `{to, subject, text, html?, from?, reply_to_id?}` | | GET | /emails/{id} | One email (doesn't change read state); /raw for the .eml | | POST | /mark-read | Mark SMS and emails read or unread `{ids, read?}`; GET /sms and /emails take `unread_only=true` | | POST | /wait-for-code | `{channel?, timeout_seconds?, from_contains?, since_seconds?}` | | GET/POST | /calls | List calls / place a call (Pro, if enabled) | | GET | /voice | Voice settings per number | | PATCH | /voice/{number_id} | `{mode, target?, greeting?, voicemail_enabled?}` | | GET/POST | /keys | List / create API keys `{name}` | | DELETE | /keys/{id} | Revoke a key | | POST | /owner/verify | Confirm the owner's mobile with the SMS code sent at signup `{code}` | | POST | /owner/phone | Start owner mobile verification `{phone}` | | GET | /audit | Audit log | | GET | /billing | Plan, status, trial, allowances | | POST | /billing/checkout | `{plan: "starter"\|"pro"}` → emails the owner a Stripe Checkout link; returns `{url, sent_to}` | | POST | /billing/portal | → Stripe Customer Portal URL, also emailed to the owner | CLI: `AGENTLINE_API_KEY=al_live_… node cli/agentline.mjs help` wraps every endpoint. ## One-time codes Every inbound SMS and email is scanned for a one-time code. `wait_for_code` returns the newest code that hasn't been handed out yet, waiting up to 55 seconds. Use `from_contains` (e.g. "Google") when several may arrive. Typical flow: submit the form with your Agentline number or email, then call `wait_for_code`, then enter the code. ## SMS rules - NZ 028 business messaging numbers; SMS goes to standard NZ mobiles only (020–029). - Transactional and assistant messages only (replies, bookings, confirmations, reminders people asked for, codes). Marketing, promotions and bulk texts are blocked. - Replies of STOP opt the sender out immediately; sends to them are then refused. - Allowances count carrier segments: 160 characters (153 per part) or 70 (67) with emoji or macrons. - No delivery receipts from the carrier: sent messages stay "sent". - **Free plan and trials**: send only to the owner's verified email and mobile. The owner verifies their mobile by texting a code from it to the agent's number (`start_owner_phone_verification`). ## Agent self-signup One call, no human step: `signup` (keyless MCP), `POST https://agentline.nz/api/v1/signup` or `agentline signup` with `{"owner_email": "…", "owner_mobile": "…", "agent_name": "…"}` (only `owner_email` is required) creates a Free account and returns an API key, an inbox address (receives mail immediately) and an MCP config you can use straight away. We email your human a verification link, and text them a code if you gave a mobile and SMS codes are on. Only the link verifies the account. The email names your API key and when it was made, and opening the link gives that key full use of the account straight away. Until then your key can only check its own account (`get_profile`, `get_my_number`, `GET /api/v1/me`) and can't message anyone. Every other tool and endpoint returns `key_not_confirmed`. Once they've opened the link, `verify_owner` (`POST /api/v1/owner/verify`) confirms their mobile with the code we texted them. After it, Free and trial accounts send only to the owner's verified email and mobile; paid plans can message anyone (within the SMS rules). To upgrade, `get_checkout_link` emails your human a Stripe Checkout link. Limits: 3 signups per IP per hour and 3 per owner email per day. An email that already owns an account can't be used again. ## Pricing - **Free**: free forever, no card; 0 × NZ 028 numbers; 1 email inbox; 0 outbound SMS segments/month; 100 outbound emails/month; no voice; 1 connected agent. - **Starter**: NZ$29/month (no GST: Agentline isn't GST-registered); 1 × NZ 028 number; 1 email inbox; 50 outbound SMS segments/month; 500 outbound emails/month; no voice; 10 connected agents. - **Pro**: NZ$79/month (no GST: Agentline isn't GST-registered); 2 × NZ 028 numbers; 5 email inboxes; 200 outbound SMS segments/month; 2000 outbound emails/month; voice (200 min/month); 10 connected agents. - **Free trial**: 7 days on Starter and Pro. Card required; converts automatically unless cancelled; reminder email 2 days before. During the trial: 1 NZ 028 number, 1 email inbox, 10 outbound SMS segments, 50 outbound emails and no voice minutes. - **Free plan and trials** send only to the account owner's verified email and mobile. - Inbound SMS and email are unlimited on every plan. Inboxes are live from day one; NZ 028 numbers are set up within a few days of signup, with a full refund if a number hasn't arrived within 30 days of paying. Pricing page: https://agentline.nz/pricing ## Telling your human A person has to approve a paid plan. If yours asks what Agentline is or costs, you can pass this on as written (`get_pricing` returns it too as `pitchForHuman`): > I'd like my own New Zealand phone number and email inbox through Agentline, so I can text people for you, read their replies, and receive the one-time codes services send when I sign up for things on your behalf. > > - Free: an @agentline.nz email inbox, 100 emails a month, no card. > - Starter, NZ$29/month: a NZ 028 number with two-way SMS (50 texts a month) plus the inbox. > - Pro, NZ$79/month: 2 numbers, 5 inboxes, 200 texts a month and voice calls. > > Starter and Pro start with a 7-day free trial. It needs a card, but cancelling before it ends costs nothing, and Agentline emails you 2 days before it converts. The inbox works straight away; the number is set up within a few days of signup, and if it hasn't arrived within 30 days of your first payment you can ask for a full refund. Prices are in NZD with no GST. > > Until you're on a paid plan I can only message your own verified email and mobile, and I'll check with you before texting or emailing anyone else. > > Sign up: https://agentline.nz/signup?plan=starter (pricing: https://agentline.nz/pricing) ## Errors Errors are `{"error":{"code","message"}}` (REST) or `isError` results with `code: message` text (MCP). - `401` unauthorized · `402` subscription_required / quota_exceeded / trial_limit · `403` recipient_not_allowed (Free, trial or owner not yet verified: owner only), recipient_opted_out, account_suspended (every call, not just sends) - `409` number_pending (028 number still being set up) · `422` content_* (marketing, phishing, shortener…) · `429` rate_limited (see Retry-After) ## Install in MCP clients ### Claude (claude.ai and Claude Desktop) Install link: https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Agentline&connectorUrl=https%3A%2F%2Fagentline.nz%2Fmcp 1. Click Add to Claude. Claude opens the Add custom connector dialog with the name and URL filled in. 2. Check the URL is https://agentline.nz/mcp and confirm. 3. Click Connect, sign in to Agentline and approve access. 4. Team and Enterprise: an Owner adds the connector under Organisation settings first. Auth: OAuth (sign in to Agentline). Source: https://claude.com/docs/connectors/building/directory-vs-custom ### ChatGPT 1. In ChatGPT, go to Plugins, select the plus button, then Add custom MCP server (account and workspace policies apply). 2. Name it Agentline. Under Connection, enter https://agentline.nz/mcp as the MCP server URL and choose OAuth for authentication. 3. Review the risk warning, select I understand and want to continue, then Create as a plugin. 4. Sign in to Agentline (or create a free account) and approve access. You're returned to ChatGPT; type @ and pick Agentline in a chat. Auth: OAuth (sign in to Agentline). Source: https://developers.openai.com/apps-sdk/deploy/connect-chatgpt ### Claude Code ``` claude mcp add --transport http agentline https://agentline.nz/mcp ``` 1. Run the command, then type /mcp in Claude Code and choose agentline → Authenticate. Auth: OAuth, or add --header "Authorization: Bearer al_live_…" for an API key. Source: https://docs.claude.com/en/docs/claude-code/mcp ### Cursor Install link: cursor://anysphere.cursor-deeplink/mcp/install?name=agentline&config=eyJ1cmwiOiJodHRwczovL2FnZW50bGluZS5uei9tY3AifQ%3D%3D Config (~/.cursor/mcp.json): ``` { "mcpServers": { "agentline": { "url": "https://agentline.nz/mcp" } } } ``` 1. Click Add to Cursor and confirm the install prompt. 2. Cursor opens the Agentline sign-in the first time a tool needs it. Auth: OAuth. Source: https://cursor.com/docs/context/mcp/install-links ### VS Code (GitHub Copilot) Install link: vscode:mcp/install?%7B%22name%22%3A%22agentline%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fagentline.nz%2Fmcp%22%7D Install via vscode.dev: https://vscode.dev/redirect/mcp/install?name=agentline&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fagentline.nz%2Fmcp%22%7D ``` code --add-mcp '{"name":"agentline","type":"http","url":"https://agentline.nz/mcp"}' ``` Config (.vscode/mcp.json (or MCP: Open User Configuration)): ``` { "servers": { "agentline": { "type": "http", "url": "https://agentline.nz/mcp" } } } ``` 1. Click Add to VS Code. If your browser doesn't open VS Code, use Install via vscode.dev or run the command. 2. Approve the install, then start the server from the MCP view and sign in when prompted. Auth: OAuth. Source: https://code.visualstudio.com/api/extension-guides/ai/mcp ### Windsurf Config (Cascade → MCP → Open MCP config file (mcp_config.json)): ``` { "mcpServers": { "agentline": { "serverUrl": "https://agentline.nz/mcp" } } } ``` 1. Paste the config into mcp_config.json, save, and press Refresh in the MCP panel. 2. Complete the browser sign-in on first use. Auth: OAuth. Source: https://docs.windsurf.com/windsurf/cascade/mcp ### Cline Config (Cline → MCP Servers → Configure → Configure MCP Servers (cline_mcp_settings.json)): ``` { "mcpServers": { "agentline": { "type": "streamableHttp", "url": "https://agentline.nz/mcp", "disabled": false, "autoApprove": [] } } } ``` 1. Or use the Remote Servers tab: name agentline, URL https://agentline.nz/mcp, transport Streamable HTTP, then Add Server. 2. Keep "type": "streamableHttp" — without it Cline falls back to legacy SSE. Auth: OAuth. Source: https://docs.cline.bot/mcp/mcp-overview ### Goose Install link: goose://extension?type=streamable_http&url=https%3A%2F%2Fagentline.nz%2Fmcp&id=agentline&name=Agentline&description=NZ%20phone%20number%2C%20SMS%20and%20email%20inbox%20for%20your%20agent Config (~/.config/goose/config.yaml): ``` extensions: agentline: name: Agentline type: streamable_http uri: https://agentline.nz/mcp enabled: true timeout: 300 ``` 1. Click Add to Goose (Goose Desktop) and confirm, or add the YAML to your config. Auth: OAuth. Source: https://github.com/block/goose/blob/main/ui/desktop/src/components/settings/extensions/deeplink.ts ### Zed Config (settings.json (zed: open settings file), or Settings → AI → MCP Servers → Add Remote Server): ``` { "context_servers": { "agentline": { "url": "https://agentline.nz/mcp" } } } ``` 1. Paste the config (note: context_servers, not mcpServers). 2. Click Authenticate next to agentline when Zed asks. Auth: OAuth (leave out the Authorization header so Zed runs OAuth). Source: https://zed.dev/docs/ai/mcp ### Codex CLI ``` codex mcp add agentline --url https://agentline.nz/mcp && codex mcp login agentline ``` Config (~/.codex/config.toml): ``` [mcp_servers.agentline] url = "https://agentline.nz/mcp" ``` 1. Run the command; codex mcp login opens the Agentline sign-in. 2. For an API key instead: --bearer-token-env-var AGENTLINE_API_KEY. Auth: OAuth, or an API key via bearer_token_env_var. Source: https://learn.chatgpt.com/docs/extend/mcp ### Gemini CLI ``` gemini mcp add --transport http agentline https://agentline.nz/mcp ``` Config (~/.gemini/settings.json): ``` { "mcpServers": { "agentline": { "httpUrl": "https://agentline.nz/mcp" } } } ``` 1. Run the command, then /mcp auth agentline inside Gemini CLI to sign in. Auth: OAuth (auto-discovered), or --header "Authorization: Bearer al_live_…". Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md ### n8n 1. Add an AI Agent node, then attach an MCP Client Tool node to its Tools input. 2. Endpoint: https://agentline.nz/mcp. Server Transport: HTTP Streamable. 3. Authentication: Bearer Auth with a credential holding your Agentline API key (al_live_…), or MCP OAuth2 with dynamic client registration on. 4. Tools to Include: All, or pick the ones the workflow needs. Auth: API key (Bearer) or MCP OAuth2. Source: https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp ### Any MCP client (JSON) Config: ``` { "mcpServers": { "agentline": { "type": "http", "url": "https://agentline.nz/mcp", "headers": { "Authorization": "Bearer ${AGENTLINE_API_KEY}" } } } } ``` 1. Streamable HTTP at https://agentline.nz/mcp. OAuth 2.1 discovery starts from the 401's WWW-Authenticate header. 2. Or skip OAuth with an API key from the dashboard: Authorization: Bearer al_live_…. 3. No account yet? Agents can call signup on the keyless server at https://agentline.nz/public/mcp with their human's email. Auth: OAuth 2.1 or API key. Source: https://modelcontextprotocol.io/specification ## FAQ ### Is this a real New Zealand number? Yes. Each number is a dedicated NZ business messaging number starting 028, hosted on New Zealand infrastructure by our licensed NZ carrier partner and assigned only to you while you're subscribed. It sends to and receives from NZ mobiles on every network. ### How much does it cost, and what's an SMS segment? Free is free forever, Starter is NZ$29/month, Pro is NZ$79/month. No GST is added because Agentline isn't GST-registered. Starter includes 1 number, 1 inbox and 50 outbound SMS segments; Pro includes 2 numbers, 5 inboxes and 200 outbound SMS segments, plus 200 voice minutes. A segment is up to 160 characters (153 per part when a message is split), or 70 (67) with emoji or macrons, which is how NZ carriers bill texts. Inbound SMS and email are always unlimited. When you reach an allowance, sending pauses until the 1st of next month or until you upgrade; we never charge overages. ### Is there a free plan? Yes. Free is free forever with no card: 1 @agentline.nz inbox, 100 outbound emails a month, unlimited inbound email and 1 connected agent. It has no phone number, and it sends only to your own verified email. Upgrade to Starter or Pro (with a 7-day free trial) when your agent needs a number. ### Why an 028 number and not an 021 or 022? In New Zealand, two-way business texting from software ("A2P" SMS) on ordinary mobile numbers isn't offered by the carriers; it's normally only possible with short codes. 028 business messaging numbers are the exception: they're built for application-to-person texting, so your agent can send and receive like a normal mobile, and NZ mobile users can reply as usual. ### What can my agent use SMS for? Transactional and assistant messages: replying to people who contacted you, confirming bookings and appointments, reminders, follow-ups people asked for, and receiving one-time codes. Marketing, promotions, newsletters and bulk texts aren't allowed on Agentline SMS, even with consent. Messages that look promotional are blocked automatically. Email is the right channel for marketing to people who've opted in. ### How quickly do I get my number? Your email inbox is live from day one. Your NZ 028 number is set up within a few days of signup, and we email you as soon as it's live. Your dashboard and get_my_number show the number as pending until then. ### What if my number takes too long? If your number hasn't arrived within 30 days of paying, you can ask for a full refund of what you've paid. Email support@agentline.nz. ### How does the free trial work? Both plans start with a 7-day free trial. You add a card at checkout (numbers and texts cost us real money, so this stops abuse), and nothing is charged until the trial ends. During the trial you get 1 NZ 028 number, 1 email inbox, 10 outbound SMS segments, 50 outbound emails and no voice minutes; your full plan allowances switch on when the trial converts. We email you 2 days before it ends. If you don't cancel, it converts automatically to NZ$29/month (Starter) or NZ$79/month (Pro). Cancel any time in the billing portal; cancelling during the trial costs nothing. One trial per account. ### Will verification codes from banks and apps work? Most services that send a code by SMS or email work. Some banks and platforms block virtual numbers, or require the number to be registered in your name. We can't guarantee every service accepts it, so test before you rely on it for anything critical. ### How do I connect it to ChatGPT or Claude? In Claude, go to Customize → Connectors, add a custom connector with the URL https://agentline.nz/mcp and sign in. In ChatGPT, go to Plugins, choose Add custom MCP server and use the same URL with OAuth. You'll approve access on an Agentline consent screen. Cursor, VS Code, Claude Code and other MCP clients have one-click or one-line installs on the install page. ### Can I use it for marketing texts? No. Agentline SMS is for transactional, one-to-one messages only, and our carrier's terms don't permit marketing on business messaging numbers. Promotional texts are blocked, bulk sending is rate limited, and we also block spam and phishing. Separately, any commercial email you send must follow the Unsolicited Electronic Messages Act 2007: consent, sender identification and a working unsubscribe. ### What happens if someone replies STOP? They're opted out immediately. We send a confirmation, and any further SMS or calls from that number to them are blocked until they reply START. ### What happens to my number if I cancel? When a paid plan ends, your number stays reserved for 14 days. If you cancel during the free trial, it's held for 2 days after the trial ends. You can keep reading messages, and resubscribing within that time restores everything. After that the number is released (and rested for 90 days before anyone else can get it), and any inbox your account no longer includes is closed. ### Where is my data stored? On Cloudflare's global network (D1 database and R2 storage). Messages are kept while your account is open and deleted on request or 90 days after your account closes. See the privacy policy for details. ### Can my agent make phone calls? Pro plans can receive calls on the 028 number and forward them to a voice agent (for example ElevenLabs over SIP) or a phone, play a greeting, and take voicemail with transcription. We switch voice on for each number once its call routing is connected. Outbound calls that speak a message are in limited release. ### Do you offer international numbers? Not yet. Agentline is NZ-only for now, which keeps it affordable and lets us do compliance properly. ## Guides ### How to give an AI agent a New Zealand phone number > Connect Agentline to your agent over MCP and it gets its own New Zealand 028 mobile number for two-way SMS, plus an @agentline.nz email inbox. Sign up, add the MCP server https://agentline.nz/mcp to ChatGPT, Claude or any MCP client, and the agent can call get_my_number, send_sms and wait_for_code. Plans start at NZ$29/month with a 7-day free trial; the inbox is live from day one and the number is set up within a few days of signup. Updated 2026-10-17 · https://agentline.nz/guides/give-ai-agent-nz-phone-number #### Why an agent needs its own number Agents increasingly do work that touches the phone network: confirming a booking, replying to a customer, or finishing a sign-up that sends a one-time code. Using your personal mobile for that mixes the agent's traffic with yours and means you have to relay every code by hand. A dedicated number keeps the agent's conversations separate, gives you an audit trail, and lets the agent act without you in the loop. #### What you get - **A real NZ 028 number.** A dedicated business messaging number that sends to and receives from NZ mobiles on every network. See [why 028](https://agentline.nz/guides/why-nz-028-numbers) for the background. - **An @agentline.nz inbox.** Receives mail immediately, so email codes work from day one. - **MCP tools.** `get_my_number`, `send_sms`, `list_messages`, `send_email`, `list_emails`, `wait_for_code` and more. The [tool reference](https://agentline.nz/docs#mcp) has the full list. - **A REST API and CLI** for agents that don't speak MCP. - **A dashboard** where you see every text, email and code the agent sends or receives. #### Which plan fits | If your agent needs to… | Plan | | --- | --- | | Receive email codes and send a little email, no phone number | Free (NZ$0, 100 emails a month, no card) | | Text people, read replies and receive SMS codes | Starter (NZ$29/month: 1 number, 50 outbound SMS segments a month) | | Run several agents, or answer phone calls | Pro (NZ$79/month: 2 numbers, 5 inboxes, 200 SMS segments and 200 voice minutes a month) | Inbound SMS and email are unlimited on every plan. A segment is 160 characters (70 with emoji or macrons), so a short reply counts as one. #### What the free trial covers Starter and Pro start with a 7-day free trial. During it the account has 1 number, 10 outbound SMS segments and 50 outbound emails, and the agent can message only your own verified email and mobile. That's enough to check that replies and codes come through before you rely on it. You get a reminder 2 days before it converts, and cancelling during the trial costs nothing. #### Before you start - SMS is for **transactional, one-to-one messages** (replies, bookings, reminders people asked for, codes). Marketing and bulk texts are blocked. See [what the UEMA allows](https://agentline.nz/guides/nz-uema-ai-agents). - SMS goes to NZ mobiles only (020–029), not landlines or international numbers. - Some banks and platforms refuse virtual numbers for verification. Test the services you care about before relying on them. #### Setting it up Follow the steps below, or go straight to the [install page](https://agentline.nz/install) for your client's one-click button. #### Steps 1. **Create an account.** Sign up at agentline.nz and confirm your email. Your @agentline.nz inbox works straight away. 2. **Choose a plan.** Start a 7-day free trial of Starter (NZ$29/month) or Pro (NZ$79/month). A card is required; nothing is charged until the trial ends. 3. **Connect your agent.** Add https://agentline.nz/mcp as an MCP server in ChatGPT, Claude, Cursor, VS Code or another client, and sign in to approve access. 4. **Wait for the number.** Your NZ 028 number is set up within a few days of signup. You get an email when it's live, and get_my_number shows it. 5. **Use it.** Ask the agent to text someone, or to sign up for a service and read the code with wait_for_code. #### Common questions ### How long does it take to get the number? The email inbox works from day one. The NZ 028 number is set up within a few days of signup, and you get an email when it's live. If it hasn't arrived within 30 days of your first payment, you can ask for a full refund. ### Can the agent text international numbers or landlines? No. Agentline sends SMS to standard New Zealand mobile numbers (020 to 029) only. ### Is an 028 number a real mobile number? It's a New Zealand 028 business messaging number. People text it and get replies from it like any other mobile, on every NZ network. It's built for software, which is why marketing texts are blocked on it. ### Can ChatGPT receive SMS verification codes? > ChatGPT has no phone number of its own, so it can't receive SMS on its own. When you connect Agentline as a custom MCP server in ChatGPT, it gets an NZ 028 number and an @agentline.nz inbox and can read the texts and emails that arrive. For safety, the ChatGPT version of Agentline hides one-time codes by default: ChatGPT can see that a code arrived and from whom, and you read the code itself in your Agentline dashboard. Updated 2026-10-17 · https://agentline.nz/guides/chatgpt-receive-sms-verification-codes #### How it works Agentline is an MCP server. Once it's connected, ChatGPT can call tools such as `get_my_number`, `list_messages` and `list_emails`. Messages arrive at your Agentline number or inbox, are stored in your account, and are visible to ChatGPT only through those tools. #### What ChatGPT can do with it - Tell you your Agentline number and email address. - Read recent texts and emails, and summarise them. - Send a text or an email for you. ChatGPT asks you to confirm first, because sending tools are marked as write actions. - Show call and voicemail history on Pro. Billing and plan changes don't happen inside ChatGPT; you manage those at agentline.nz. #### Why codes are hidden in ChatGPT A one-time code is effectively a password for a moment, and a ChatGPT conversation (including tool results) may be stored. So in ChatGPT, Agentline replaces codes with "••••••" in message text and doesn't offer the `wait_for_code` tool. ChatGPT can still tell you "a code from Google arrived at 10:42", and you copy it from your dashboard. With Claude, Cursor or your own agents over API keys, `wait_for_code` returns the code so the agent can finish a sign-up by itself. #### Services that may refuse Most services that send codes by SMS or email work. Some banks, wallets and large platforms block virtual or business numbers, or require the number to be registered in your name. Test before you rely on one for anything important. #### Never share your own passwords Agentline never asks for your passwords or for codes sent to your personal phone, and the ChatGPT app is told never to ask for them either. #### Steps 1. **Open Plugins in ChatGPT.** Go to Plugins, select the plus button, then Add custom MCP server. Workspace policies may need an admin to allow this. 2. **Add Agentline.** Name it Agentline, enter https://agentline.nz/mcp as the server URL and choose OAuth. 3. **Sign in.** Sign in to Agentline, or create a free account, and approve access. You're returned to ChatGPT. 4. **Use it in a chat.** Type @ and pick Agentline, then ask it for your number or your latest messages. #### Common questions ### Can ChatGPT read the code and finish a sign-up by itself? Not in ChatGPT. Agentline hides one-time codes there by default, so you copy the code from your Agentline dashboard. Agents connected through Claude, Cursor or an API key can read codes with wait_for_code. ### Do I need a paid plan to use Agentline in ChatGPT? No. You can sign in with a free account, which includes an @agentline.nz inbox. A phone number needs Starter or Pro, which you set up at agentline.nz. ### Will my bank send a code to an Agentline number? Some will and some won't. Banks and large platforms sometimes block virtual or business numbers, so test the service before relying on it. ### Connect Claude to SMS and email with an MCP connector > In Claude, open Customize → Connectors, add a custom connector with the URL https://agentline.nz/mcp, click Connect and sign in to Agentline. Claude then has tools to send and read SMS from its own NZ 028 number, send and read email from an @agentline.nz inbox, and wait for one-time codes. In Claude Code, run claude mcp add --transport http agentline https://agentline.nz/mcp. Updated 2026-10-17 · https://agentline.nz/guides/connect-claude-sms-email-mcp #### One-click option The [install page](https://agentline.nz/install) has an **Add to Claude** button that opens the custom connector dialog with the name and URL filled in. #### Permissions Agentline asks for two scopes: `messages:read` (always) and `messages:send` (optional). Without the send scope, Claude can read messages and codes but can't text or email anyone. Every tool is labelled read-only or not, so Claude asks before anything that sends. #### Claude Code ``` claude mcp add --transport http agentline https://agentline.nz/mcp ``` Then type `/mcp`, pick agentline and choose Authenticate. To use an API key instead, add `--header "Authorization: Bearer al_live_…"`. #### What Claude can do - Text a NZ mobile and read the reply (`send_sms`, `list_messages`). - Send and read email from its own address (`send_email`, `list_emails`, `read_email`), up to 5 recipients per message. - Finish a sign-up by waiting for the code (`wait_for_code`). It waits up to 55 seconds, and each code is handed out once, so a retry never reuses a stale one. - On Pro, see calls and voicemail transcripts (`list_calls`). #### Things to try first - "What's my Agentline number and email address?" - "Sign up for the newsletter at example.co.nz with my Agentline email and confirm it." - "Text 021 123 4567 to say I'm running ten minutes late." (On Free and trial accounts this works only for your own verified mobile.) #### Safe defaults New accounts can message only the owner's verified email and mobile until they're on a paid plan. SMS content is checked before sending: marketing, link shorteners, phishing patterns and impersonation are refused, and anyone who replies STOP is opted out at once. #### Steps 1. **Open connectors.** In claude.ai or Claude Desktop, go to Customize → Connectors and choose Add custom connector. On Team and Enterprise plans an Owner adds it under Organisation settings first. 2. **Enter the URL.** Name it Agentline and use https://agentline.nz/mcp. Leave the advanced OAuth fields empty. 3. **Connect and approve.** Click Connect, sign in to Agentline and approve access. Allow sending if you want Claude to text and email. 4. **Enable it in a chat.** Turn the connector on from the tools menu in a conversation and ask Claude for your Agentline number. #### Common questions ### Does Claude ask before sending a text? Yes. Agentline marks its sending tools as write actions, so Claude asks you to approve them. You can also connect without the messages:send scope, so Claude can read messages and codes but can't send, call or change settings. ### Can I use Agentline in Claude Code without OAuth? Yes. Create an API key in the Agentline dashboard and add it with --header "Authorization: Bearer al_live_…" when you run claude mcp add. ### Can Claude read one-time codes? Yes. In Claude, wait_for_code returns the code from an SMS or email so Claude can finish a sign-up. Each code is returned once. ### Why NZ business texting uses 028 numbers > In New Zealand, carriers don't offer two-way application-to-person (A2P) texting on ordinary mobile numbers like 021 or 022; outside short codes, it runs on 028 business messaging numbers, which are built for software to send and receive like a normal mobile. People reply to an 028 number exactly as they would to any other mobile, on every NZ network. Updated 2026-10-17 · https://agentline.nz/guides/why-nz-028-numbers #### A2P versus P2P Person-to-person (P2P) texting is what phones do. Application-to-person (A2P) texting is software sending and receiving: booking systems, alerts, and now AI agents. NZ carriers treat the two differently, and A2P traffic on ordinary consumer mobile numbers isn't offered. #### The options for software | Option | Two-way conversation | Looks like a mobile | Good for | | --- | --- | --- | --- | | Short code | Keyword replies only | No | One-way alerts, opt-in keywords | | 028 business messaging number | Yes | Yes | Replies, bookings, codes, assistants | | A SIM in a spare phone | Yes | Yes | Not designed for software or automated sending | #### What this means for agents An agent on Agentline texts from its own 028 number, and replies usually land back in the agent's message list within seconds. Because the number is a business messaging number, the carrier rules apply: transactional and conversational messages only, no marketing. See [the UEMA and agents](https://agentline.nz/guides/nz-uema-ai-agents). #### What the person on the other end sees A text from a number starting 028, like any other mobile. They can save it as a contact and reply normally. If they reply HELP, they get an automatic message saying the number is operated by an AI agent through Agentline, and STOP opts them out. A good agent still says who it's acting for in its first message. #### How long setup takes Agentline sets up 028 numbers within a few days of signup, and emails you when yours is live. The @agentline.nz inbox works from day one, so email codes and replies don't wait for the number. #### Limits worth knowing - SMS goes to NZ mobiles (020–029) only. - The carrier doesn't return delivery receipts, so sent messages show as "sent". - Some services won't send verification codes to business numbers. Test first. #### Common questions ### Can people reply to an 028 number? Yes. People reply to an 028 number exactly as they would to any other mobile, on every NZ network, and the replies reach the agent. ### Why not put a SIM card in a spare phone? Ordinary consumer mobile plans aren't designed for automated, software-driven texting, and NZ carriers don't offer A2P traffic on them. An 028 business messaging number is the supported route. ### How long does it take to get an 028 number from Agentline? The email inbox works from day one. The NZ 028 number is set up within a few days of signup, and you get an email when it's live. If it hasn't arrived within 30 days of your first payment, you can ask for a full refund. ### Give your AI agent its own email inbox > Give the agent an address of its own rather than your personal mailbox: it keeps the agent's sign-ups and replies separate and limits what the agent can see. Agentline gives every account an @agentline.nz inbox that's live from day one. The agent reads mail with list_emails and read_email, sends with send_email, and waits for emailed codes with wait_for_code. The Free plan includes 1 inbox and 100 outbound emails a month, sent only to the owner's verified address. Updated 2026-10-17 · https://agentline.nz/guides/ai-agent-email-inbox #### Why not just use your Gmail? Connecting an agent to your main mailbox gives it everything: banking alerts, private threads, password resets. A separate inbox gives it only what you send its way. It also makes it obvious to recipients that a message came from an assistant. #### How the inbox works - Every account gets an address like `ari@agentline.nz`. You can choose the name at signup. Pro includes 5 inboxes. - Inbound mail is unlimited and scanned for one-time codes. - Outbound mail comes from the agent's own address, up to 5 recipients per message. - The original message is available as an .eml for anything that needs headers. #### Replying in the same thread To answer an email, the agent calls `send_email` with `reply_to_id` set to the message it's replying to. Agentline adds the In-Reply-To and References headers, so the reply lands in the same conversation in the other person's mail app instead of starting a new one. #### Email allowances | Plan | Inboxes | Outbound emails a month | | --- | --- | --- | | Free | 1 | 100 | | Starter | 1 | 500 | | Pro | 5 | 2,000 | Allowances reset on the 1st of each month (NZ time). If the agent reaches one, sending pauses; nothing is charged as overage. #### Free plan and trials On the Free plan and during a trial, the agent can send only to the account owner's verified email (and verified mobile, if any). That stops a new account being used to spam strangers. Paid plans can email anyone, within the [acceptable use rules](https://agentline.nz/compliance#acceptable-use). #### Getting started [Create a free account](https://agentline.nz/signup), then connect your client from the [install page](https://agentline.nz/install). #### Common questions ### Is the Free plan really free? Yes. The Free plan is NZ$0 with no card: 1 @agentline.nz inbox, unlimited inbound email and 100 outbound emails a month, sent only to your own verified address. It has no phone number. ### Can the agent read codes sent by email? Yes. Every inbound email is scanned for a one-time code, and wait_for_code returns it (outside ChatGPT, where codes are hidden by default). ### Can I pick the inbox address? Yes. Choose a name of 3 to 30 lowercase letters, numbers, dots or hyphens at signup, or leave it blank for a random one. ### What the NZ Unsolicited Electronic Messages Act means for AI agents > The Unsolicited Electronic Messages Act 2007 applies to commercial texts and emails with a New Zealand link, whether a person or an AI agent sends them. Commercial messages need consent, must identify the sender, and must include a working unsubscribe that's honoured within 5 working days. Agentline goes further for SMS: it allows only transactional, one-to-one messages and blocks marketing outright. Updated 2026-10-17 · https://agentline.nz/guides/nz-uema-ai-agents #### Who it applies to The Act covers commercial electronic messages (email, SMS, MMS and instant messages) with a New Zealand link. It doesn't matter that software wrote or sent the message: the person or business behind the agent is responsible. The Department of Internal Affairs (DIA) enforces it. #### What counts as commercial A message is commercial if it markets or promotes goods, services, land, or a business or investment opportunity. Some messages aren't treated as commercial even when a business sends them, such as a quote or estimate the person asked for, or a message that confirms or completes a transaction they've already agreed to. Most of what a well-behaved assistant sends (replies, booking confirmations, reminders someone requested, codes) falls on the non-commercial side, but the content decides, not the sender. #### The three rules for commercial messages 1. **Consent.** Express consent, consent that can reasonably be inferred from an existing relationship, or an address published for business contact where the message is relevant. 2. **Identify the sender.** Say who the message is from and how to contact them. 3. **Working unsubscribe.** Every commercial message needs a free way to opt out, honoured within 5 working days. #### How Agentline applies it - **SMS:** transactional and assistant messages only (replies, bookings, confirmations, reminders people asked for, codes). Promotional texts are blocked automatically, even with consent. - **STOP:** a reply of STOP (or UNSUBSCRIBE, CANCEL, QUIT and similar) opts the person out immediately, and further texts to them are refused. START opts them back in, and HELP gets a reply saying the number is operated by an AI agent through Agentline, with how to opt out and report abuse. - **Content checks:** link shorteners, phishing patterns and impersonation are refused before a text leaves. - **Email:** marketing email is allowed only to people who opted in, with sender details and an unsubscribe. - **New accounts:** Free and trial accounts can message only the owner, so nobody can sign up and start texting strangers. #### Practical rules for your agent - Tell it to text only people who contacted you or asked to hear from you. - Have it introduce itself as your assistant and say who it's acting for. - Don't ask it to send promotions by SMS at all; Agentline will refuse them. This is a summary, not legal advice. See our [compliance page](https://agentline.nz/compliance) and the [Act itself](https://www.legislation.govt.nz/act/public/2007/0007/latest/whole.html). #### Common questions ### Does the UEMA apply to messages an AI agent writes? Yes. The Act looks at the message, not who or what wrote it. The person or business the agent acts for is responsible for its commercial messages. ### Can my agent send promotional texts through Agentline? No. Agentline SMS is for transactional and assistant messages only, and promotional texts are blocked even if the recipient consented. Marketing email is allowed only to people who opted in, with an unsubscribe. ### What happens when someone replies STOP? They're opted out immediately and Agentline refuses further texts to them from that account. If they reply START, they're opted back in. ### Add SMS and email tools to Cursor, VS Code and Claude Code > Agentline is a remote MCP server at https://agentline.nz/mcp using Streamable HTTP and OAuth 2.1. In Cursor and VS Code, click the install button on agentline.nz/install. In Claude Code, run claude mcp add --transport http agentline https://agentline.nz/mcp; in Codex CLI, codex mcp add agentline --url https://agentline.nz/mcp; in Gemini CLI, gemini mcp add --transport http agentline https://agentline.nz/mcp. Sign in when prompted, or use an API key header. Updated 2026-10-17 · https://agentline.nz/guides/add-sms-to-cursor-vscode-claude-code #### Install buttons - **Cursor:** the `cursor://` install link adds `{"url": "https://agentline.nz/mcp"}` to your MCP config. - **VS Code (Copilot):** the `vscode:mcp/install` link, a vscode.dev fallback link, or `code --add-mcp '{"name":"agentline","type":"http","url":"https://agentline.nz/mcp"}'`. - **Goose:** a `goose://extension` link for Goose Desktop. #### Command-line clients ``` claude mcp add --transport http agentline https://agentline.nz/mcp codex mcp add agentline --url https://agentline.nz/mcp && codex mcp login agentline gemini mcp add --transport http agentline https://agentline.nz/mcp ``` #### API keys for CI and headless agents OAuth is best for people. For scripts and CI, create an API key in the dashboard and send `Authorization: Bearer al_live_…`. Each key is one connected agent (1 on Free, up to 10 on Starter and Pro); revoke it from the dashboard, the CLI or `revoke_api_key`. #### Using it from code The same features are on the REST API, so you can test without an MCP client: ``` curl -X POST https://agentline.nz/api/v1/wait-for-code \ -H "Authorization: Bearer $AGENTLINE_KEY" -H "Content-Type: application/json" \ -d '{"channel":"sms","from_contains":"Acme","timeout_seconds":45}' ``` `wait_for_code` waits up to 55 seconds (45 by default) and looks back 10 minutes by default. If it returns `found: false`, call it again. The [OpenAPI spec](https://agentline.nz/openapi.json) covers every endpoint, and `cli/agentline.mjs` wraps them. #### Troubleshooting - **401 on every call:** the client hasn't finished OAuth. Run its sign-in step: `/mcp` in Claude Code, `codex mcp login agentline`, or `/mcp auth agentline` in Gemini CLI. - **403 recipient_not_allowed:** Free and trial accounts can message only the owner's verified email and mobile. - **409 number_pending:** the 028 number is still being set up. Email works meanwhile. - **429 rate_limited:** wait for the number of seconds in `Retry-After`. #### Testing without an account The keyless server at `https://agentline.nz/public/mcp` needs no credentials. It offers pricing, availability, docs and install instructions, and `signup`. Nothing on it can send a message for you. All clients, including Windsurf, Cline, Zed and n8n, are on the [install page](https://agentline.nz/install). #### Common questions ### Which MCP transport does Agentline use? Streamable HTTP at https://agentline.nz/mcp, with OAuth 2.1 (Client ID Metadata Documents and Dynamic Client Registration) or an API key in the Authorization header. ### Can I use Agentline in CI without a browser sign-in? Yes. Create an API key in the dashboard and send it as Authorization: Bearer al_live_… on /mcp or /api/v1. ### Is there a way to try it before signing up? Yes. The keyless MCP server at https://agentline.nz/public/mcp needs no credentials. It can describe pricing, availability and installs, and create an account, but it can't send anything. ### How an AI agent can sign itself up for Agentline > An agent can create its own Agentline account in one call: signup on the keyless MCP server (https://agentline.nz/public/mcp), POST /api/v1/signup, or agentline signup, with its human's email and optionally an NZ mobile. It gets an API key, an @agentline.nz inbox and an MCP config straight away, with no human step. We email the human a verification link. Opening it gives the agent's key full use of the account; until then the agent can't message anyone. Updated 2026-10-17 · https://agentline.nz/guides/agent-self-signup #### Why sending is limited at first An account that can message strangers without a person behind it would be a spam tool. So a self-signed-up account works straight away but can message only the human it names, until that human confirms they're the owner. #### What you get back `POST /api/v1/signup` with `{"owner_email": "you@example.co.nz"}` returns `201` with JSON like this (the keyless `signup` tool returns the same data in camelCase): ``` { "account_id": "acct_…", "api_key": "al_live_…", "inbox": "jolly-kauri-4374@agentline.nz", "plan": "free", "owner": { "email": "you@example.co.nz", "mobile": null, "verified": false }, "verification": { "email": "sent", "sms": "not_requested", "expires_at": "…" }, "restrictions": "Until your owner verifies …", "mcp_url": "https://agentline.nz/mcp", "mcp": { "url": "https://agentline.nz/mcp", "headers": { "Authorization": "Bearer al_live_…" }, "config": { "mcpServers": { "agentline": { … } } } }, "timings_ms": { "total": 180 } } ``` Save `api_key` straight away: it isn't shown again. #### Restrictions by state | State | Can receive | Can send to | | --- | --- | --- | | Owner not verified yet | Email | The owner's email and mobile from signup, 5 messages a day | | Verified, Free plan | Email | Owner's verified email and mobile | | Trial | Email and SMS | Owner's verified email and mobile | | Paid plan | Email and SMS | Anyone (within the SMS rules) | #### Limits 3 signups per IP address per hour and 3 per owner email per day. An email that already owns an Agentline account can't be used again: the owner signs in and creates an API key for the new agent instead. The verification link lasts 7 days and works once. The keyless server allows 60 requests a minute per IP. #### Explaining it to your human If they ask what it costs, the keyless `get_pricing` tool returns `pitchForHuman`, a short plain-English summary with current prices, the 7-day trial and the number timing. It's also on the [agents page](https://agentline.nz/agents#human). #### Upgrading A Free account has no phone number. Call `get_checkout_link` (or `POST /api/v1/billing/checkout`) and we email your human a Stripe Checkout link; you get the link back too. The number is then set up within a few days of signup. #### Steps 1. **Call signup.** On https://agentline.nz/public/mcp (or POST /api/v1/signup), with owner_email and, optionally, owner_mobile and agent_name. 2. **Store the API key.** The response includes an al_live_ key, shown once. Use it as a Bearer token on /mcp and /api/v1, or paste the returned MCP config. 3. **Say hello to your human.** You can email them straight away. Ask them to click the verification link we sent and to keep your API key when they sign in. 4. **Submit the SMS code (if they have one).** Call verify_owner with the 6-digit code, or POST /api/v1/owner/verify. It confirms their mobile; only the emailed link verifies the account. #### Common questions ### Does a person have to approve the signup? No. The account works as soon as signup returns. When the owner opens the verification link we email them, the agent's key gets full use of the account; until then the agent can't message anyone. ### Does signup email anyone? Yes, only the owner: a verification link, plus an SMS code if a mobile was given and SMS codes are on. If it wasn't them, they can ignore it and the account stays limited to messaging them. ### How long does the verification link last? 7 days, and it works once. The owner can also sign in at https://agentline.nz/login with the same email, which verifies them too.