Sending Email from the Wiki

This guide explains how to configure Wikantik to send transactional emails (account verification, password reset, notifications) from a self-hosted installation.

Why You Need an Email Relay Service

Sending email directly from a home server will fail because:

You need a transactional email relay service.

1. Brevo (formerly Sendinblue) — Best Free Tier

2. SendGrid (Twilio) — Most Popular

3. Mailjet

4. Amazon SES — Cheapest at Scale

5. Resend — Modern Option

For low volume (few hundred emails per week), Brevo or SendGrid free tiers are more than sufficient.

Step-by-Step Setup

This example uses Brevo, but the process is similar for other providers.

Step 1: Sign Up for Email Service

  1. Go to https://www.brevo.com
  2. Create a free account
  3. Verify your email address

Step 2: Add and Verify Your Sending Domain

  1. In Brevo dashboard, go to Senders & IP → Domains
  2. Add your domain (e.g., jakefear.com or wiki.jakefear.com)
  3. Brevo will provide DNS records to add

Step 3: Configure DNS Records

Add the DNS records provided by your email service. Typical records include:

TypeHostValuePurpose
TXT@v=spf1 include:sendinblue.com ~allSPF - authorizes service to send
TXTmail._domainkeyk=rsa; p=MIGf...DKIM - email signing
TXT_dmarcv=DMARC1; p=quarantine; rua=mailto:...DMARC - policy

Note: If you already have an SPF record, merge them:

v=spf1 include:existing.com include:sendinblue.com ~all

Step 4: Get SMTP Credentials

In your email service dashboard:

  1. Navigate to SMTP settings
  2. Note down:
    • SMTP Server (e.g., smtp-relay.brevo.com)
    • Port: 587 (TLS) or 465 (SSL)
    • Login/Username
    • Password or API Key

Step 5: Configure Wikantik

Add to your wikantik-custom.properties:

# Email configuration
mail.from = Wikantik <wiki@yourdomain.com>
mail.smtp.host = smtp-relay.brevo.com
mail.smtp.port = 587
mail.smtp.account = your-login@email.com
mail.smtp.password = your-smtp-key-here
mail.smtp.starttls.enable = true
mail.smtp.timeout = 5000
mail.smtp.connectiontimeout = 5000

Step 6: Test Email

  1. Restart Tomcat
  2. Create a new user account in Wikantik
  3. Check if verification email arrives
  4. Check your email service dashboard for delivery logs

Alternative: JNDI Configuration (More Secure)

To keep credentials out of properties files, configure the mail session in Tomcat's context file.

Add to your Wikantik.xml (in conf/Catalina/localhost/):

<Resource name="mail/Session"
          auth="Container"
          type="jakarta.mail.Session"
          mail.smtp.host="smtp-relay.brevo.com"
          mail.smtp.port="587"
          mail.smtp.auth="true"
          mail.smtp.starttls.enable="true"
          mail.smtp.user="your-login@email.com"
          password="your-smtp-key-here"
          mail.from="wiki@yourdomain.com"/>

Wikantik will automatically use the JNDI session mail/Session when available.

SMTP Settings by Provider

Brevo (Sendinblue)

mail.smtp.host = smtp-relay.brevo.com
mail.smtp.port = 587
mail.smtp.starttls.enable = true

SendGrid

mail.smtp.host = smtp.sendgrid.net
mail.smtp.port = 587
mail.smtp.account = apikey
mail.smtp.password = SG.your-api-key-here
mail.smtp.starttls.enable = true

Mailjet

mail.smtp.host = in-v3.mailjet.com
mail.smtp.port = 587
mail.smtp.starttls.enable = true

Amazon SES

mail.smtp.host = email-smtp.us-east-1.amazonaws.com
mail.smtp.port = 587
mail.smtp.starttls.enable = true

Wikantik Mail Properties Reference

PropertyDefaultDescription
mail.from${user.name}@${mail.smtp.host}The sender email address
mail.smtp.host127.0.0.1SMTP server hostname
mail.smtp.port25SMTP server port
mail.smtp.account(not set)SMTP username for authentication
mail.smtp.password(not set)SMTP password for authentication
mail.smtp.starttls.enabletrueEnable TLS encryption
mail.smtp.timeout5000Socket I/O timeout (ms)
mail.smtp.connectiontimeout5000Connection timeout (ms)
jspwiki.mail.jndinamemail/SessionJNDI name for container-managed session

Troubleshooting

Emails Not Sending

  1. Check Tomcat logs for mail-related errors
  2. Verify SMTP credentials are correct
  3. Ensure port 587 outbound is not blocked by firewall
  4. Check email service dashboard for rejected/bounced messages

Emails Going to Spam

  1. Verify SPF, DKIM, and DMARC records are properly configured
  2. Use a "from" address that matches your verified domain
  3. Allow 24-48 hours for DNS changes to propagate
  4. Check your domain's reputation at https://mxtoolbox.com

Authentication Errors

  1. Some services require API keys instead of passwords
  2. SendGrid uses apikey as the username with API key as password
  3. Ensure special characters in passwords are properly escaped

Connection Timeouts

  1. Try port 465 (SSL) instead of 587 (TLS)
  2. Check if your ISP blocks outbound SMTP ports
  3. Increase timeout values in configuration