# Email API

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](/docs/platform/forms#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](/docs/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

```shell
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.

## Related pages

- [Email Settings](/docs/platform/email-settings) — How Viresso sends email and notification toggles.
- [API Authentication](/docs/api/authentication) — API keys and hosted authentication.
- [API Overview](/docs/api/overview) — Base URL, headers, and error handling.