> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging overview

> Send transactional email and SMS via the API: prerequisites, billing, custom senders, and templates — through the gu1 messaging API for customer communications.

## What these endpoints do

Use **transactional messaging** to send **email** or **SMS** from your backend or integrations—outside of [Workflows](/en/workflows/overview). Each successful send is billed like other marketplace usage: **execution-pack quota** (if configured) or **organization token balance**.

These routes are **not** the same as workflow actions such as “Send notification”; they are dedicated HTTP APIs under the marketplace path.

## Base URL and paths

```
POST https://api.gu1.ai/marketplace/messaging/send-email
POST https://api.gu1.ai/marketplace/messaging/send-sms
```

Use your environment’s API host if different (e.g. staging).

## Authentication and organization

Same authentication as the rest of the gu1 API. See [Authentication](/en/api-reference/authentication).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

* **API key:** the key is tied to an organization; no extra header is usually required.
* **User session (e.g. from the dashboard):** if the user belongs to multiple organizations, send the target organization explicitly:

```http theme={null}
X-Organization-ID: <organization-uuid>
```

## Marketplace integrations (required)

Before calling these endpoints, the organization must have the corresponding integration **enabled** in **Applications** (Marketplace):

| Channel | Integration code (reference) |
| ------- | ---------------------------- |
| Email   | `global_sender_email`        |
| SMS     | `global_sender_sms`          |

If the integration is off, the API returns **`400`** with an error explaining that Email or SMS must be enabled.

The platform **messaging provider** (`MS_PROVIDER_URL` on the server) must also be configured; otherwise the request fails with a configuration error.

## Billing and balance

For sends with a **non-zero** price (`base_price_cents` on the integration), the API checks **before** sending that either:

1. There is **at least one execution** left in the integration’s **execution pack**, or
2. The organization has **enough token balance** (credits) for the charge.

If neither applies, the API returns **`400`** with an insufficient-balance message.\
If the provider accepts the message but **recording the charge** fails, the response indicates failure even though the message may have been accepted upstream (rare race or balance change).

Free integrations (`base_price_cents` = 0) skip the balance check.

## Email: verified domains and senders (“From”)

To send from your own address (e.g. `noreply@yourdomain.com`):

1. Add and **verify** the domain under **Settings → Email → Domains** (DNS records).
2. Optional: add a **sender** under **Settings → Email → Senders** if you want a fixed display name or to reuse a UUID.

In the API you can specify the sender in either way (not both):

* **`fromEmail`** — full address; the domain must be **verified** for your org. If the domain is not registered or DNS verification has not succeeded, the API returns **`400`** with `success: false` and an English `error` (see [Send email](/en/api-reference/messaging/send-email#custom-sender-fromemail)).
* **`fromSenderId`** — UUID of a sender row already stored for your org.

If you omit both, email is sent from the **platform default Gu1 sender** (expected behavior, not an error).

## Message content: three patterns

### 1. Stored template by ID

Send `templateId` (UUID) and optional `templateParams` (object). Placeholders in the template use the same `{{variable}}` syntax as elsewhere in gu1 (including dotted keys where supported).

Do **not** send raw `htmlBody` / `textBody` (email) or `body` (SMS) together with `templateId`.

### 2. Inline body with optional placeholders

Send `htmlBody` and/or `textBody` (email) or `body` (SMS). You may still pass **`templateParams`** to replace `{{token}}`, `{{name}}`, etc. inside those strings and in **`subject`** (email).

### 3. Email-only: subject + HTML or plain text

For email without a stored template, **`subject`** is required. Provide **`htmlBody`**, or **`textBody`** (plain text is wrapped in minimal HTML for the provider).

## Template IDs in the dashboard

Under **Organization settings → Applications → Message templates**, each template has a **copy ID** control for use as `templateId`. Templates are scoped to **email** or **sms**; the API returns **`400`** if the template’s channel does not match the endpoint.

## Response shape

Responses are JSON. Typical fields:

```json theme={null}
{ "success": true, "messageId": "..." }
```

On failure:

```json theme={null}
{ "success": false, "error": "..." }
```

Validation errors (e.g. Zod) may return **`400`** with Mintlify/client-specific error formatting when applicable. API error strings for these routes are in **English**.

## Related endpoints (testing only)

Under the same marketplace prefix, **`/marketplace/messaging/sms/test`** and similar **test** routes are intended for quick checks and may not apply the same strict billing gates as **`send-email`** / **`send-sms`**. Prefer **`send-email`** and **`send-sms`** for production transactional traffic.

## Next steps

<CardGroup cols={2}>
  <Card title="Send email" icon="envelope" href="/en/api-reference/messaging/send-email">
    `POST .../send-email` — body reference and examples
  </Card>

  <Card title="Send SMS" icon="message" href="/en/api-reference/messaging/send-sms">
    `POST .../send-sms` — body reference and examples
  </Card>
</CardGroup>