Skip to main content

​
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. Add a sender under Settings → Email → Senders for that domain.
In the API you can specify the sender in either way (not both):
  • fromEmail — full address string; must match a configured sender for the org. If the domain is missing, unverified, or the address is not registered as a sender, you get a 400 with a specific error.
  • fromSenderId — UUID of a sender row in Settings → Email → Senders (or from your integration with the email-senders API).
If you omit both, email is sent from the platform default sender (when allowed).

​
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