Email Configuration

Postiz sends transactional emails for user activation, notifications, and team invitations. Configure email delivery using Resend (recommended) or NodeMailer.

Email Providers

Postiz supports three email providers:

Resend - Modern email API (recommended)
NodeMailer - SMTP-based email delivery
Empty - No email delivery (auto-activation)

Environment Variables

Required Settings

Add these variables to your .env file:

EMAIL_PROVIDER="resend"  # or "nodemailer"
EMAIL_FROM_ADDRESS="[email protected]"
EMAIL_FROM_NAME="Postiz"

If EMAIL_PROVIDER is not set, Postiz uses the Empty provider and automatically activates users without email verification.

Provider-Specific Configuration

EMAIL_PROVIDER="resend"
RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxx"
EMAIL_FROM_ADDRESS="[email protected]"
EMAIL_FROM_NAME="Postiz"

Setup with Resend (Recommended)

Resend is the recommended email provider for production deployments.

Create Resend Account

Visit resend.com and create an account
Verify your email address
Navigate to the API Keys section

Generate API Key

Click “Create API Key”
Name it “Postiz Production” or similar
Select “Sending access” permission
Copy the API key (starts with re_)

Verify Domain

To send from your own domain:

Go to Domains → Add Domain
Enter your domain (e.g., yourdomain.com)
Add the provided DNS records to your domain:
- SPF record
- DKIM record
- DMARC record (optional but recommended)
Wait for verification (usually 5-15 minutes)

Configure Environment

Add to your .env file:

EMAIL_PROVIDER="resend"
RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxx"
EMAIL_FROM_ADDRESS="[email protected]"
EMAIL_FROM_NAME="Postiz"

Use a subdomain like noreply@ or notifications@ for transactional emails to avoid deliverability issues.

Restart Postiz

Apply the configuration:

docker compose restart backend

Check the logs to verify email service initialization:

docker compose logs backend | grep "Email service"

You should see:

Email service provider: resend

Setup with NodeMailer (SMTP)

Use NodeMailer if you have an existing SMTP server or email service.

Get SMTP Credentials

Obtain SMTP credentials from your email provider:

Gmail: Use App Passwords (requires 2FA enabled)
SendGrid: Get SMTP credentials from Settings
Mailgun: Use SMTP credentials from domain settings
Custom SMTP: Get from your hosting provider

Configure Environment

Add to your .env file:

EMAIL_PROVIDER="nodemailer"
NODEMAILER_HOST="smtp.gmail.com"
NODEMAILER_PORT="587"
NODEMAILER_SECURE="false"  # true for port 465, false for 587
NODEMAILER_USER="[email protected]"
NODEMAILER_PASS="your-app-password"
EMAIL_FROM_ADDRESS="[email protected]"
EMAIL_FROM_NAME="Postiz"

Test Configuration

Restart and test:

docker compose restart backend

Common SMTP Providers

NODEMAILER_HOST="smtp.gmail.com"
NODEMAILER_PORT="587"
NODEMAILER_SECURE="false"
NODEMAILER_USER="[email protected]"
NODEMAILER_PASS="your-app-password"  # Not your regular password!

Email Service Implementation

The email service (email.service.ts) automatically selects the configured provider:

const emailService: EmailInterface;

selectProvider(provider: string) {
  switch (provider) {
    case 'resend':
      return new ResendProvider();
    case 'nodemailer':
      return new NodeMailerProvider();
    default:
      return new EmptyProvider();
  }
}

Provider Validation

Each provider validates required environment variables on initialization:

// From resend.provider.ts:8
validateEnvKeys = ['RESEND_API_KEY'];

Missing variables are logged to the console:

Missing environment variable: RESEND_API_KEY

Email Templates

Postiz sends beautifully formatted HTML emails with automatic styling:

Template Features

Gradient background (#e6f2ff to #f0e6ff)
Responsive card layout with backdrop blur
Automatic subject line as heading
Branded footer with notification preferences link
Links to user settings: {FRONTEND_URL}/settings

Email Workflow

Emails are sent through Temporal workflows for reliability:

// From email.service.ts:44-53
await temporalService.client
  .getRawClient()
  .workflow.signalWithStart('sendEmailWorkflow', {
    taskQueue: 'main',
    workflowId: 'send_email',
    signal: 'sendEmail',
    args: [{ queue: [] }],
    signalArgs: [{ to, subject, html, replyTo, addTo }],
    workflowIdConflictPolicy: 'USE_EXISTING',
  });

Temporal workflows provide automatic retries (up to 3 attempts) with exponential backoff for failed email deliveries.

User Activation Behavior

With Email Provider Configured

User registers
Activation email sent to user’s email
User must click activation link
Account becomes active

Without Email Provider (Empty Provider)

User registers
Account is automatically activated
No email verification required

Disabling email verification (Empty provider) is not recommended for production as it allows anyone to create accounts without email confirmation.

Disabling User Registration

To disable new user registration entirely:

DISABLE_REGISTRATION=true

This prevents new sign-ups regardless of email configuration.

Testing Email Delivery

Create a new user account with a real email address you can access.

Check Email Logs

Monitor backend logs for email sending attempts:

docker compose logs -f backend | grep -i email

Verify Delivery

Check your inbox (and spam folder) for the activation email.

Test Activation Link

Click the activation link in the email to verify the full flow works.

Troubleshooting

Emails not sending (Resend)

Check the following:

API Key Valid: Verify your Resend API key starts with re_ and is active
Domain Verified: Ensure your domain is verified in Resend dashboard
Rate Limits: Check you haven’t exceeded Resend’s rate limits (check dashboard)
Logs: Check backend logs for detailed error messages

docker compose logs backend | grep -i resend

Emails not sending (NodeMailer)

Common issues:

Wrong Port: Use 587 for STARTTLS, 465 for SSL/TLS
Authentication Failed: For Gmail, use App Passwords, not your regular password
Firewall: Ensure your server can make outbound SMTP connections
SMTP Disabled: Some email providers require enabling SMTP access

Test SMTP connection:

telnet smtp.gmail.com 587

Emails going to spam

Improve deliverability:

Verify Domain: Complete SPF, DKIM, and DMARC setup
Warm Up: Start with low volume and gradually increase
Content: Avoid spam trigger words and excessive links
Reply-To: Set a valid reply-to address
Unsubscribe: Include unsubscribe link (automatic in Postiz emails)

Missing environment variables warning

If you see:

Missing environment variable: RESEND_API_KEY

Verify the variable is set in .env
Ensure no extra spaces: RESEND_API_KEY="value" not RESEND_API_KEY = "value"
Restart the backend service
Check the variable is loaded: docker compose exec backend env | grep RESEND

Email service provider shows 'empty'

If logs show:

Email service provider: empty

The EMAIL_PROVIDER variable is not set or invalid. Valid values:

resend
nodemailer

Add to .env and restart:

EMAIL_PROVIDER="resend"

Email Notification Preferences

Users can manage their email notification preferences at:

{FRONTEND_URL}/settings

Each email includes a link to settings:

You can change your notification preferences in your 
<a href="{FRONTEND_URL}/settings">account settings</a>.

Monitoring and Debugging

Enable Debug Logging

Increase log verbosity to debug email issues:

LOG_LEVEL=debug

Check Email Service Initialization

docker compose logs backend | grep "Email service provider"

Expected output:

Email service provider: resend

Monitor Email Queue

Emails are processed asynchronously through Temporal. Check workflow status:

docker compose logs orchestrator | grep sendEmail

Rate Limits

Resend

Free tier: 100 emails/day
Paid tier: Based on your plan
Automatic retry with exponential backoff

NodeMailer

Rate limits depend on your SMTP provider:

Gmail: 500 emails/day (free), 2000/day (Google Workspace)
SendGrid: Based on your plan
Mailgun: Based on your plan

For high-volume deployments, consider using Resend or a dedicated email service provider.

Security Best Practices

Never commit email credentials to version control. Use environment variables and secure secrets management.

Store API keys and passwords in environment variables
Use App Passwords for Gmail, never your main password
Rotate API keys regularly
Monitor email logs for suspicious activity
Implement rate limiting on user registration
Use HTTPS for all email links

Next Steps

After configuring email:

OAuth Apps - Set up social media integrations
AI Integration - Enable AI features
Billing Configuration - Set up Stripe payments

Get Started

Core Features

Social Platforms

Self-Hosting

Configuration

Email Configuration

Email Providers

Environment Variables

Required Settings

Provider-Specific Configuration

Setup with Resend (Recommended)

Setup with NodeMailer (SMTP)

Common SMTP Providers

Email Service Implementation

Provider Validation

Email Templates

Template Features

Email Workflow

User Activation Behavior

With Email Provider Configured

Without Email Provider (Empty Provider)

Disabling User Registration

Testing Email Delivery

Troubleshooting

Email Notification Preferences

Monitoring and Debugging

Enable Debug Logging

Check Email Service Initialization

Monitor Email Queue

Rate Limits

Resend

NodeMailer

Security Best Practices

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Features

Social Platforms

Self-Hosting

Configuration

​Email Providers

​Environment Variables

​Required Settings

​Provider-Specific Configuration

​Setup with Resend (Recommended)

​Setup with NodeMailer (SMTP)

​Common SMTP Providers

​Email Service Implementation

​Provider Validation

​Email Templates

​Template Features

​Email Workflow

​User Activation Behavior

​With Email Provider Configured

​Without Email Provider (Empty Provider)

​Disabling User Registration

​Testing Email Delivery

​Troubleshooting

​Email Notification Preferences

​Monitoring and Debugging

​Enable Debug Logging

​Check Email Service Initialization

​Monitor Email Queue

​Rate Limits

​Resend

​NodeMailer

​Security Best Practices

​Next Steps

Build docs developers (and LLMs) love

Email Providers

Environment Variables

Required Settings

Provider-Specific Configuration

Setup with Resend (Recommended)

Setup with NodeMailer (SMTP)

Common SMTP Providers

Email Service Implementation

Provider Validation

Email Templates

Template Features

Email Workflow

User Activation Behavior

With Email Provider Configured

Without Email Provider (Empty Provider)

Disabling User Registration

Testing Email Delivery

Troubleshooting

Email Notification Preferences

Monitoring and Debugging

Enable Debug Logging

Check Email Service Initialization

Monitor Email Queue

Rate Limits

Resend

NodeMailer

Security Best Practices

Next Steps