npm package: @lobstercom/agent-phone
Description: OpenClaw skill plugin — give your AI agent a real phone number, email, SMS, MMS, and voice via Lobstercom
Latest version: 2026.2.24

# @lobstercom/agent-phone

OpenClaw **skill plugin** for **Lobstercom** — give your AI agent a real phone number and email address with SMS, MMS, voice calling, and email capabilities.

## What is Lobstercom?

[Lobstercom](https://lobstercom.ai) is the phone carrier for AI agents. It provides real US phone numbers and @lobstercom.ai email addresses with enterprise-grade infrastructure. Your agent can send SMS, MMS, make voice calls, and send/receive email through dedicated addresses that are not tied to your personal accounts.

This plugin registers Lobstercom as a **skill** in [OpenClaw](https://github.com/openclaw/openclaw), exposing tools that your agent can use from any channel (Slack, Discord, web chat, etc.) to interact with the phone network and email system.

## Features

| Feature | Status |
|---------|--------|
| Outbound SMS | Supported |
| Outbound MMS (images, video, etc.) | Supported |
| Outbound voice calls | Supported |
| Number status & health check | Supported |
| Inbound SMS/MMS (via webhook) | Supported (see Webhook Setup) |
| Multiple phone numbers per agent | Supported |
| Outbound email | Supported |
| Email inbox checking | Supported |
| Email contact management | Supported |

## Installation

```bash
openclaw plugins install @lobstercom/agent-phone
```

Or copy/symlink the `openclaw-plugin/` directory into your OpenClaw `extensions/` folder:

```bash
cp -r openclaw-plugin/ /path/to/openclaw/extensions/agent-phone/
```

OpenClaw will auto-discover the skill plugin on next startup via the `openclaw.plugin.json` manifest.

## Configuration

### Step 1: Get a Lobstercom account

1. Go to [lobstercom.ai](https://lobstercom.ai) and sign up.
2. Purchase or provision a phone number from the dashboard.
3. Generate an API key for the number (Dashboard > Your Number > API Key). The key starts with `ap_`.
4. Note the **Phone Number ID** (a UUID) shown in the dashboard.

### Step 2: Set environment variables

The plugin reads configuration from environment variables:

**Phone (required for SMS/MMS/voice tools):**

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `LOBSTERCOM_API_KEY` | Yes | -- | Your Lobstercom API key (starts with `ap_`) |
| `LOBSTERCOM_NUMBER_ID` | Yes | -- | UUID of the phone number from Lobstercom |
| `LOBSTERCOM_URL` | No | `https://lobstercom.ai` | Lobstercom API base URL |

**Email (required for email tools):**

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `LOBSTERCOM_MAIL_API_KEY` | Yes (for email) | -- | Your Lobstercom Mail API key |
| `LOBSTERCOM_MAIL_URL` | No | `https://api.primary.net` | Mail API base URL |

Example:

```bash
# Phone
export LOBSTERCOM_API_KEY="ap_your_api_key_here"
export LOBSTERCOM_NUMBER_ID="550e8400-e29b-41d4-a716-446655440000"

# Email
export LOBSTERCOM_MAIL_API_KEY="your_mail_api_key_here"
```

Alternatively, these can be provided via the plugin's `configSchema` in your OpenClaw configuration file.

## Available Tools

Once installed, the following tools are available to your agent from any channel:

### `send_sms`

Send an SMS text message to a phone number.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `to` | Yes | Recipient phone number in E.164 format (e.g. `+15551234567`) |
| `body` | Yes | The text message body (max 1600 characters) |

### `send_mms`

Send a multimedia message (image, video, etc.) to a phone number.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `to` | Yes | Recipient phone number in E.164 format |
| `mediaUrl` | Yes | Publicly accessible URL of the media to send |
| `body` | No | Optional text caption for the media |

### `make_call`

Initiate a voice call to a phone number. The call uses your number's configured voice mode (STT/TTS or stream).

| Parameter | Required | Description |
|-----------|----------|-------------|
| `to` | Yes | Phone number to call in E.164 format |
| `greeting` | No | Optional greeting message to play when the call connects |

### `get_number_info`

Check your Lobstercom number's status, configuration, and health. Takes no parameters.

Returns: phone number, friendly name, status, voice mode, and webhook health.

### `send_email`

Send an email from your agent's @lobstercom.ai email address.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `to` | Yes | Recipient email address |
| `subject` | Yes | Email subject line |
| `body_text` | Yes | Plain text body of the email |
| `body_html` | No | Optional HTML body. If provided, email clients that support HTML will render this instead of the plain text body. |

### `check_inbox`

Check your agent's @lobstercom.ai email inbox.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `limit` | No | Maximum number of messages to return (default: 20) |
| `unread_only` | No | If true, only return unread messages (default: false) |

Returns: list of messages with count.

### `manage_email_contacts`

Add, remove, or list allowed email contacts for your agent's @lobstercom.ai address. Contacts must be added before you can email them.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `action` | Yes | Action to perform: `"add"`, `"remove"`, or `"list"` |
| `contact_email` | For add/remove | Email address of the contact |

## How It Works

```
Your Agent --> OpenClaw --> Lobstercom Skill --> Lobstercom API --> Carrier --> Phone
                                             --> Mail API      --> SMTP    --> Email
```

1. Your agent decides to send a message, make a call, or send an email (via tool call from any channel).
2. OpenClaw invokes the appropriate Lobstercom skill tool.
3. For phone tools, the tool calls the Lobstercom REST API with Bearer token authentication.
4. For email tools, the tool calls the Mail API (`https://api.primary.net/mail/v1/`) with a separate Bearer token.
5. Lobstercom validates the request, checks usage, and routes through the carrier network or SMTP.
6. The message is delivered, the call is initiated, or the email is sent.

Because this is a **skill plugin** (not a channel plugin), the agent can use these tools regardless of which channel it is currently conversing on. An agent talking to a user on Slack can send an SMS, or an agent in a web chat can initiate a phone call or send an email.

## Webhook Setup (Inbound Messages)

For **inbound** messages (someone texting your Lobstercom number), configure a webhook in the Lobstercom dashboard that points to your agent's inbound message handler.

1. In the Lobstercom dashboard, go to your phone number's settings.
2. Set the webhook URL to your OpenClaw instance's inbound endpoint.
3. Lobstercom will POST inbound SMS/MMS payloads to that URL.
4. Your agent's primary channel (whichever channel plugin handles inbound delivery) will receive and process the message.

The skill plugin handles **outbound** actions (sending messages, making calls). Inbound delivery is handled by your agent's channel configuration and webhook setup.

## Troubleshooting

### "LOBSTERCOM_API_KEY environment variable is required"

Set the `LOBSTERCOM_API_KEY` environment variable with your API key from the Lobstercom dashboard. The key starts with `ap_`.

### "LOBSTERCOM_NUMBER_ID environment variable is required"

Set the `LOBSTERCOM_NUMBER_ID` environment variable with the UUID of your phone number. Find it in the Lobstercom dashboard.

### API returns 401 Unauthorized

Your API key is incorrect or expired. Generate a new one from the Lobstercom dashboard under your phone number's settings.

### API returns 404 Not Found

The phone number ID does not match any number in your account. Verify the UUID in the Lobstercom dashboard.

### Rate limiting (HTTP 429)

Lobstercom enforces a rate limit of 60 outbound messages per minute per phone number. If you hit this limit, wait and retry.

### Media not sending

Ensure the media URL is publicly accessible. Lobstercom needs to fetch the media from the URL you provide. Private or localhost URLs will not work.

### Voice calls not connecting

Verify that your phone number has a voice mode configured in the Lobstercom dashboard (either STT/TTS or stream). The number must be set up for voice before calls can be initiated.

### "LOBSTERCOM_MAIL_API_KEY environment variable is required for email tools"

Set the `LOBSTERCOM_MAIL_API_KEY` environment variable with your Mail API key from the Lobstercom dashboard. This is a separate key from the phone API key (`LOBSTERCOM_API_KEY`).

### Email tools return 401 Unauthorized

Your Mail API key is incorrect or expired. Generate a new one from the Lobstercom dashboard. Note that the Mail API key is separate from the phone API key.

### Email not being sent (contact not allowed)

Contacts must be added to your allowed list before you can email them. Use the `manage_email_contacts` tool with the `"add"` action to add a contact before sending them an email.

## License

MIT