Skip to main content

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.

​
What these endpoints do

Use transactional messaging to send email or SMS from your backend or integrations—outside of Workflows. 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. 
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:
X-Organization-ID: <organization-uuid>

​
Marketplace integrations (required)

Before calling these endpoints, the organization must have the corresponding integration enabled in Applications (Marketplace):
ChannelIntegration code (reference)
Emailglobal_sender_email
SMSglobal_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).
  • 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: 
{ "success": true, "messageId": "..." }
On failure: 
{ "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. 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

Send email

POST .../send-email — body reference and examples

Send SMS

POST .../send-sms — body reference and examples