Skip to main content
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.

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.
If you omit both 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).
Do not send 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 send templateId.
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}}.
You must provide at least one of htmlBody or textBody.

Example — template

Example — inline HTML + placeholders

Example — plain text only

Success response

Exact fields may match your 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.