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

1. 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.

2. Open Mailer Configuration

   Go to Config > Mailer Configuration

3. Enter SMTP details

   Fill in the configuration fields according to your SMTP provider’s details (see table below)

4. Test and save

   Click Send test email to verify the configuration, then click Save

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)

If an environment already has a custom MAILER_URL configured, it won’t be overwritten.

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

Gmail

Host: smtp.gmail.com
Port: 587
Note: Use app password if 2FA is enabled

SendGrid

Host: smtp.sendgrid.net
Port: 587
Username: apikey

Mailgun

Host: smtp.mailgun.org
Port: 587
Check: Mailgun dashboard for credentials

Amazon SES

Host: email-smtp.region.amazonaws.com
Port: 587
Note: Use SMTP credentials, not AWS keys

Example: Gmail Configuration

Setting	Value
SMTP Host	smtp.gmail.com
SMTP Port	587
Username	[e-mail]
Password	Your Gmail app password (if using 2FA, generate an app-specific password)

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.

Sending Emails Programmatically

Generate API Key

1. Navigate to API Keys

   Go to Environment > Config > API Keys

2. Create API key

   Generate a new API key for your environment

3. Use the API

   Refer to our API documentation for sending emails

Example API Usage

curl -X POST \
  -H 'Authorization: <api_key>' \
  -H 'Content-Type: application/json' \
  'https://api.stormkit.io/v1/mailer/send' \
  -d '{
    "to": "[e-mail]",
    "subject": "Welcome to Stormkit",
    "text": "Thank you for signing up!",
    "html": "<h1>Thank you for signing up!</h1>"
  }'

Using in Your Application

// 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: '[e-mail]',
    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

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

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

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

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

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
• Contact Stormkit support