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.

Connect. MCP server (Streamable HTTP): https://agentline.nz/mcp. OAuth 2.1 sign-in, or Authorization: Bearer al_live_… with an API key.
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.
Call get_my_number to learn your number and email address.
Receive a code: give a service your number or email, then call wait_for_code.
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).

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)

Discovery files

/llms.txt and /llms-full.txt
/.well-known/mcp/server-card.json (MCP server card, Smithery-compatible)
/.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server
/.well-known/api-catalog (RFC 9727) and /openapi.json
Markdown for any page: append .md, or send Accept: text/markdown.

Agentline, described for agents