> ## 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

> Stormkit Mailer is a simple email service that allows you send transactional emails with ease.

## Overview

Stormkit Mailer is designed to provide a straightforward way to send transactional emails directly from your application. This feature is ideal for sending:

* Automated notifications
* Password resets
* Welcome emails
* Order confirmations
* System alerts
* Other essential email communications

With just a few configuration settings, you can connect Stormkit Mailer to your SMTP provider and start sending emails quickly and reliably.

## Configuration

<Steps>
  <Step title="Navigate to Mailer config">
    Navigate to the Environments tab and select the environment (e.g., production or staging) where you want to set up email functionality.
  </Step>

  <Step title="Open Mailer Configuration">
    Go to **Config** > **Mailer Configuration**
  </Step>

  <Step title="Enter SMTP details">
    Fill in the configuration fields according to your SMTP provider's details (see table below)
  </Step>

  <Step title="Test and save">
    Click **Send test email** to verify the configuration, then click **Save**
  </Step>
</Steps>

## Configuration Fields

| Setting       | Description                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| **SMTP Host** | Enter the hostname of your SMTP server                                                                |
| **SMTP Port** | Set the port for your SMTP server. Common ports are 587 (TLS), 465 (SSL)                              |
| **Username**  | Enter the username for SMTP authentication. Typically the email address associated with your account. |
| **Password**  | Enter the password for SMTP authentication. Ensure this is securely stored and not shared publicly.   |

## Environment Variables

When configured, Stormkit will inject the following environment variable at build time and make it available at runtime:

| Variable     | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `MAILER_URL` | The SMTP connection string (e.g., `smtp://user:pass@host:port`) |

<Info>
  If an environment already has a custom `MAILER_URL` configured, it won't be overwritten.
</Info>

## Testing the Configuration

After entering your SMTP credentials, click the **Send test email** button to verify the configuration.

You should receive a confirmation email if the SMTP settings are correct. If there's an error, double-check your SMTP settings or contact your SMTP provider for assistance.

Once you're satisfied with the settings, click **Save** to store the SMTP configuration for your environment.

## Common SMTP Providers

<CardGroup cols={2}>
  <Card title="Gmail" icon="google">
    **Host:** smtp.gmail.com\
    **Port:** 587\
    **Note:** Use app password if 2FA is enabled
  </Card>

  <Card title="SendGrid" icon="envelope">
    **Host:** smtp.sendgrid.net\
    **Port:** 587\
    **Username:** apikey
  </Card>

  <Card title="Mailgun" icon="mailbox">
    **Host:** smtp.mailgun.org\
    **Port:** 587\
    **Check:** Mailgun dashboard for credentials
  </Card>

  <Card title="Amazon SES" icon="aws">
    **Host:** email-smtp.region.amazonaws.com\
    **Port:** 587\
    **Note:** Use SMTP credentials, not AWS keys
  </Card>
</CardGroup>

## Example: Gmail Configuration

| Setting   | Value                                                                     |
| --------- | ------------------------------------------------------------------------- |
| SMTP Host | smtp.gmail.com                                                            |
| SMTP Port | 587                                                                       |
| Username  | [your-email@example.com](mailto:your-email@example.com)                   |
| Password  | Your Gmail app password (if using 2FA, generate an app-specific password) |

<Warning>
  **Gmail Users with 2FA:**\
  If you have two-factor authentication enabled, you'll need to create an app-specific password in your Google account settings.
</Warning>

## Sending Emails Programmatically

### Generate API Key

<Steps>
  <Step title="Navigate to API Keys">
    Go to **Environment** > **Config** > **API Keys**
  </Step>

  <Step title="Create API key">
    Generate a new API key for your environment
  </Step>

  <Step title="Use the API">
    Refer to our [API documentation](/api/mailer) for sending emails
  </Step>
</Steps>

### Example API Usage

```bash theme={null}
curl -X POST \
  -H 'Authorization: <api_key>' \
  -H 'Content-Type: application/json' \
  'https://api.stormkit.io/v1/mailer/send' \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to Stormkit",
    "text": "Thank you for signing up!",
    "html": "<h1>Thank you for signing up!</h1>"
  }'
```

### Using in Your Application

```javascript theme={null}
// Example: Sending email from your application
const mailerUrl = process.env.MAILER_URL;

async function sendEmail(to, subject, body) {
  const nodemailer = require('nodemailer');
  
  const transporter = nodemailer.createTransport(mailerUrl);
  
  await transporter.sendMail({
    from: 'noreply@example.com',
    to,
    subject,
    html: body,
  });
}
```

## Security Best Practices

* **SMTP Security**: Ensure that your SMTP credentials are kept secure and only accessible by authorized personnel
* **Environment Variables**: Never commit SMTP credentials to version control
* **App Passwords**: For Gmail and similar providers with 2FA, always use app-specific passwords
* **TLS/SSL**: Always use encrypted connections (port 587 with TLS or port 465 with SSL)
* **Rate Limiting**: Be aware of your SMTP provider's rate limits

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test email not received">
    * Verify SMTP host and port are correct
    * Check username and password are accurate
    * Ensure your email provider supports the port you've selected
    * Check spam/junk folders
    * Verify your SMTP provider allows connections from Stormkit's IP addresses
  </Accordion>

  <Accordion title="Authentication failed">
    * Double-check username and password
    * For Gmail with 2FA, ensure you're using an app password
    * Verify your SMTP provider account is active
    * Check if your provider requires additional authentication setup
  </Accordion>

  <Accordion title="Connection timeout">
    * Verify firewall or security settings allow outbound SMTP traffic
    * Check if your network blocks the SMTP port
    * Try alternative ports (587, 465, 2525)
    * Contact your SMTP provider to verify service status
  </Accordion>

  <Accordion title="MAILER_URL not available in application">
    * Redeploy your application after saving SMTP configuration
    * Verify the environment variable is injected (check deployment logs)
    * Ensure you're accessing the correct environment
  </Accordion>
</AccordionGroup>

## Additional Notes

### App Passwords for Gmail

If you're using Gmail as your SMTP provider and have two-factor authentication (2FA) enabled, you'll need to create an app-specific password:

1. Go to your Google Account settings
2. Navigate to Security > 2-Step Verification
3. Scroll down to App passwords
4. Generate a new app password for "Mail"
5. Use this password in the Mailer configuration

### Rate Limits

Be aware of your SMTP provider's rate limits:

* **Gmail**: \~500 emails per day for free accounts
* **SendGrid**: Varies by plan, free tier includes 100 emails/day
* **Mailgun**: 5,000 emails/month on free tier
* **Amazon SES**: 62,000 emails/month on free tier (when sending from EC2)

## Need Help?

For further assistance:

* Refer to your SMTP provider's documentation
* Check the [Mailer API documentation](/api/mailer)
* Contact Stormkit support