> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailer

> Send transactional emails programmatically using the Stormkit Mailer API

The Mailer API allows you to send transactional emails from your Stormkit environments.

## Prerequisites

Before using the Mailer API:

1. Configure the mailer settings for your environment (see [Mailer documentation](/features/mailer))
2. Generate an Environment-level API Key

## Send Email

<ParamField path="POST /v1/mailer" type="endpoint">
  Send a transactional email.
</ParamField>

### Request Body

<ParamField body="to" type="string" required>
  Recipient email address. For multiple recipients, separate with semicolons (;)
</ParamField>

<ParamField body="from" type="string" required>
  Sender email address (can include name: "Jane Doe \<[jane@example.org](mailto:jane@example.org)>")
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line
</ParamField>

<ParamField body="body" type="string" required>
  Email body content. Supports HTML formatting
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Whether the email was sent successfully
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/mailer' \
    -d '{
      "to": "joe@example.org",
      "from": "Jane Doe <jane@example.org>",
      "subject": "Hello Joe",
      "body": "Hi,<br/>How are you?"
    }'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

***

## Multiple Recipients

To send an email to multiple recipients, separate email addresses with semicolons:

```json theme={null}
{
  "to": "joe@example.org; jane@example.org; admin@example.org",
  "from": "no-reply@example.org",
  "subject": "Team Update",
  "body": "Hello team,<br/><br/>This is an important update."
}
```

## HTML Email Body

The `body` field supports HTML content. The API automatically wraps your content in proper HTML structure:

```json theme={null}
{
  "to": "customer@example.org",
  "from": "support@example.org",
  "subject": "Welcome to Our Service",
  "body": "<h1>Welcome!</h1><p>Thank you for signing up.</p><p><a href='https://example.org/verify'>Click here to verify your email</a></p>"
}
```

## Error Responses

<ResponseField name="400 Bad Request">
  Returned when:

  * Email body is empty
  * Subject is empty
  * Mailer is not configured for the environment
</ResponseField>

<ResponseField name="500 Internal Server Error">
  Returned when the SMTP server fails to send the email. The error message will contain details from the mail server.
</ResponseField>

## Configuration

Before using this API endpoint, you must configure SMTP settings for your environment:

1. Navigate to your environment's configuration
2. Set up your SMTP server details:
   * Host
   * Port (default: 587)
   * Username
   * Password

<Tip>
  For detailed setup instructions, see the [Mailer feature documentation](/features/mailer).
</Tip>

## Email Tracking

All emails sent through the Mailer API are stored in your environment's database for tracking and audit purposes. This includes:

* Sender address
* Recipient address(es)
* Subject line
* Email body
* Timestamp