Send email
API Reference
Send email
POST /marketplace/messaging/send-email — transactional email with optional template or inline HTML — through the gu1 messaging API for customer communications.
POST
Send email
Sends a single transactional email for the authenticated organization. Requires the Email marketplace integration and a configured messaging provider. See Messaging overview for prerequisites, billing, and senders.
If you omit both Custom sender (
When you send
Do not send
You must provide at least one of
Exact fields may match your
Endpoint
Headers
Request body
Common
string
required
Recipient email address.
string
Full From address (e.g.
noreply@your-domain.com). The domain must be registered and verified for your organization under Settings → Email → Domains. You do not need a matching row under Senders when the domain is already verified. Mutually exclusive with fromSenderId.string (UUID)
ID of a sender from Settings → Email → Senders. Mutually exclusive with
fromEmail.fromEmail and fromSenderId, the API uses the platform default Gu1 sender. That is expected behavior, not an error.
Custom sender (fromEmail)
When you send fromEmail, for example example@my-domain.com, the API validates the domain (my-domain.com) before attempting delivery. The response is always 400 with { "success": false, "error": "<English message>" }; the email is not sent until the domain is verified.
Example rejection (unverified domain):
object
Key-value map for
{{placeholders}} in subject, htmlBody, textBody, or in a stored template. Values may be strings, numbers, or booleans (coerced for rendering). Default {}.Mode A — Stored template
string (UUID)
required
ID of a message template with channel email (org or system template).
htmlBody or textBody in this mode.
string
Optional fallback if the template has no subject or the subject is empty after placeholder replacement.
Mode B — Inline content
Do not sendtemplateId.
string
required
Email subject. May contain
{{variables}} replaced via templateParams.string
HTML body. Max ~500,000 characters. May include
{{variables}}.string
Plain-text body; used as multipart alternative when both HTML and text are sent, or converted to minimal HTML if HTML is omitted. Max ~500,000 characters. May include
{{variables}}.htmlBody or textBody.
Example — template
Example — inline HTML + placeholders
Example — plain text only
Success response
MessageDeliveryService / provider response.
Errors and HTTP status
Business and validation responses from this route use JSON like{ "success": false, "error": "<English message>" } unless noted. All error strings are in English. Invalid JSON bodies may return a different shape from the validator (e.g. Zod field issues) at 400.
After validation, the MS Provider may still return
{ "success": false, "error": "…" } (e.g. provider rejection) at 200 or an error status depending on implementation—inspect success and error on every response.