# send_site_message

Source: https://modulify.ai/docs/api/messages/send-site-message

Sends one text from a site to one phone number with one of its templates.

- Title: Send a text
- Scope: `config:write`
- Access: Destructive
- Endpoint: `POST /v1/send_site_message`

It is a real text that reaches a real person, and its template must be approved. Each site's plan includes credits for texts every calendar month, 2 on Free, 20 on Starter, 20 on Pro and 40 on Enterprise. Each text takes its own price from them, so texts to expensive countries use them up sooner, and what they do not cover is charged in credits to the workspace. It is refused while texting is off, to a country the site may not text, to a number that is blocked or replied STOP, to a US number on Free (code `plan-required`), to a US number while the site's own US number is not ready yet (code `sender-not-ready`, which clears on its own), and past 30 texts a minute, 5 texts to one number a day or 20 credits a day on Pro. Pass an `idempotencyKey` so that sending again sends nothing new. The tool tells the client to send only a text you asked for, to a number you gave, and to check both with you first. See [Send a text](https://modulify.ai/docs/built-in/messages#send-a-text).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/send_site_message`, sending the inputs below as a JSON object. The token needs the `config:write` scope.

> **Warning**
>
> This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it.

```bash
curl -X POST https://api.modulify.ai/v1/send_site_message \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","template":"TEMPLATE","to":"TO"}'
```

Over MCP, the same method is the [send_site_message tool](https://modulify.ai/docs/mcp/messages/send-site-message).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |
| `template` | string | Yes | The template key, from `list_site_message_templates`. |
| `to` | string | Yes | The phone number in international format, such as `+14155551234`. |
| `variables` | object | No | The value of each placeholder, keyed by its name. `site` is filled with the site's name on its own. |
| `channel` | string | No | Always `sms`, the default: texts go out as SMS only. |
| `idempotencyKey` | string | No | Any unique string for this text. Sending again with the same key sends nothing new, unless the first text failed before it went out, as with a `provider` error: then it is sent again. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.