Skip to content
Viresso. Documentation Open Viresso
API reference3 min read

Email API

On this page

The email API sends transactional emails from your workspace. Emails are sent synchronously and count toward the workspace's email usage metrics.

Info: This endpoint sends email through the system's configured mail driver (Resend, SMTP, SES, Mailgun, Postmark, or other). A log mailer records the message without delivering it. Workspace notification toggles do not control this endpoint.

To receive form answers by email, configure the form’s Submit action. Form email does not require an API key or a separate call to this endpoint.

Send an email

POST /api/v1/{workspace}/mail

Sends a transactional email from the workspace.

Authentication

Requires an API key with the mail:send ability. See API Authentication.

Rate limiting

This endpoint is rate-limited to 10 requests per minute per API key.

Request body

Field Required Type Max Description
subject Yes string 255 chars Email subject line
html Yes string 200,000 chars HTML body of the email
to No string (email) 255 chars Recipient email address. Defaults to the workspace's email if omitted.
from No string (email) 255 chars Reply-to address. Must pass DNS verification. The sender remains noreply-{workspace-name}@viresso.com.
attachments No array 5 items File attachments (see below)
headers No object of strings 998 chars per header Custom X-* headers keyed by header name

Attachments

Each attachment in the attachments array requires:

Field Required Type Max Description
name Yes string 255 chars Attachment filename
mime_type Yes string 255 chars MIME type (e.g. application/pdf)
content Yes string (base64) 10 MB decoded Base64-encoded file content

From address

If no from address is provided, the email is sent from:

noreply-{workspace-name}@viresso.com

The optional from value sets the message's reply-to address and must pass DNS verification (valid MX entries for the domain). The sender address always remains the workspace-specific noreply-* address.

Warning: Some email providers require the from address to match a verified domain. If DNS verification fails, the request returns a validation error.

Example request

curl -X POST "https://app.example.com/api/v1/acme/mail" \
  -H "Authorization: Bearer $VIRESSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your order confirmation",
    "html": "<h1>Thank you</h1><p>Your order has been confirmed.</p>",
    "to": "customer@example.com",
    "from": "noreply-acme@viresso.com"
  }'

Example response

Returns 204 No Content after the mail provider accepts the message.

Error responses

Status Meaning
403 Invalid API key, origin mismatch, or workspace suspended
422 Validation failed — check the errors object
429 Rate limit exceeded

Common validation errors

  • html exceeds 200,000 characters.
  • attachments contains more than 5 items.
  • An attachment's decoded content exceeds 10 MB.
  • from or to fails DNS verification (not a valid mailbox domain).
  • A custom header is not an X-* header or contains line breaks.
  • subject exceeds 255 characters.

Limitations

  • Attachments are limited to 5 per email, each up to 10 MB (base64 decoded).
  • The HTML body is limited to 200,000 characters.
  • CC and BCC are not supported.
  • Emails are sent synchronously — the API waits for the configured provider to accept the message, not for final recipient delivery.
  • Email delivery depends on the platform's mail configuration.
  • Rate limit: 10 requests per minute.