Quickstart

Signup is open and every new account starts with $5 of credit. Numbers can receive texts the moment they are provisioned; outbound sending unlocks once your campaign clears carrier review. Compliance guardrails are on by default: consent gating, opt-out suppression, and quiet hours tooling.

This guide goes receive-first: get a number, text it from your phone, then register a campaign and send.

1. Create an API key

Create a key in the dashboard under Settings, then API keys. The secret is shown once and looks like am_live_....

export AGENTMESSAGE_API_KEY="am_live_..."

The API is served from https://api.agentmsg.io. Every /v1/* request takes the key as a bearer token and is automatically scoped to the organization that owns it.

2. Provision a number

Search for available numbers, then order one. Search is a preview, not a reservation:

curl https://api.agentmsg.io/v1/phone-numbers/search \
  -H "Authorization: Bearer $AGENTMESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "area_code": "415", "quantity": 5 }'

Pick a number from the results and order it:

curl https://api.agentmsg.io/v1/phone-numbers/orders \
  -H "Authorization: Bearer $AGENTMESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "numbers": ["+14155550123"] }'

The number is yours as soon as the call returns, and it can receive texts immediately. No campaign is required for inbound.

3. Receive your first text

Text your new number from your own phone, then fetch it:

curl "https://api.agentmsg.io/v1/inbound-messages?limit=5" \
  -H "Authorization: Bearer $AGENTMESSAGE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "5a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "from": "+15551234567",
      "to": "+14155550123",
      "body": "hello agentmessage",
      "channel": "sms",
      "received_at": "2026-06-11T12:01:00.123Z"
    }
  ],
  "meta": { "next_cursor": null }
}

Prefer push over polling? Set an HTTPS inbound_url on the number (PATCH /v1/phone-numbers/{id}) and AgentMessage will POST each inbound message to it, signed with an X-AmCore-Signature header so you can verify it came from AgentMessage.

4. Register your campaign to unlock sending

Outbound SMS in the US runs on 10DLC, which requires a registered brand and campaign. Register your brand (POST /v1/brands), then your campaign (POST /v1/campaigns), or do both from the dashboard. Sending unlocks when your campaign clears carrier review; carriers control review timelines.

The 10DLC help center covers how to write a registration that passes review.

5. Send your first message

Sends require the recipient's consent on file; without it, POST /v1/messages returns 453 CONSENT_REQUIRED. Fastest path for your own phone: trigger a double opt-in and reply to confirm. phone_number_id is the id from your order response in step 2.

curl https://api.agentmsg.io/v1/consent/double-opt-in \
  -H "Authorization: Bearer $AGENTMESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e",
    "contact_number": "+15551234567",
    "confirmation_text": "Reply YES to confirm you want these messages. Reply STOP to opt out, HELP for help."
  }'

After you reply YES, send:

curl https://api.agentmsg.io/v1/messages \
  -H "Authorization: Bearer $AGENTMESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155550123",
    "to": "+15551234567",
    "text": "hello from agentmessage"
  }'

A successful call returns 202 Accepted with the message resource. status starts as queued and moves to a terminal state (delivered, failed, undelivered) as carrier delivery receipts arrive:

{
  "success": true,
  "data": {
    "id": "8f3a2b1c-1c2d-4e5f-9a8b-0c1d2e3f4a5b",
    "from": "+14155550123",
    "to": "+15551234567",
    "text": "hello from agentmessage",
    "status": "queued",
    "created_at": "2026-06-11T12:00:00Z"
  }
}

Next steps

• Errors: every error code, with envelopes and handling.
• Rate limits and throughput: API limits and what governs carrier-side send speed.
• Consent endpoints: double opt-in, hosted forms, and attested capture.
• Webhooks: subscribe to delivery receipts and account events.
• Browse the full API reference for every endpoint and field.