Email & Recovery

Overview

mineLogin provides an email-based account recovery system. Players can link an email address to their account and use it to reset their password if they forget it.

SMTP Configuration

mailing:
  enabled: false
  email-warning: true
  recovery-code-expiration-minutes: 15
  recovery-cooldown-minutes: 1
  server-name: "YourAddress.net"
  sender-email: "[email protected]"
  from: "mineLogin"
  server: "smtp.sendgrid.net"
  port: 587
  username: "apikey"
  password: "securePassword"
  email-title: "Account recovery on YourAddress.net"
  transport-strategy: SMTP

Option	Type	Default	Description
enabled	Boolean	false	Enable email-based recovery
email-warning	Boolean	true	Warn players who have no email linked
recovery-code-expiration-minutes	Integer	15	Recovery code expiration time in minutes
recovery-cooldown-minutes	Integer	1	Cooldown between recovery code requests in minutes
server-name	String	"YourAddress.net"	Server name shown in emails
sender-email	String	"[email protected]"	Sender email address
from	String	"mineLogin"	Sender display name
server	String	"smtp.sendgrid.net"	SMTP server address
port	Integer	587	SMTP server port
username	String	"apikey"	SMTP authentication username
password	String	"securePassword"	SMTP authentication password
email-title	String	"Account recovery on YourAddress.net"	Email subject line
transport-strategy	Enum	SMTP	SMTP transport strategy

Transport Strategies

Strategy	Description
SMTP	Plain SMTP (port 25 or 587)
SMTPS	SMTP over SSL (port 465)
SMTP_TLS	SMTP with STARTTLS (port 587)
SMTP_OAUTH2	SMTP with OAuth2 authentication

Recovery Flow

Linking an Email

1. Player runs /email <email> to link an email address
2. The email is saved to their account
3. Players can change their email with /email <newEmail> <oldEmail>
4. Players can remove their email with /unlink <email>

Recovering an Account

1. Player runs /recovery <email> on the login screen
2. If the email matches, a 6-digit recovery code is sent via email
3. Player enters /code <code> <newPassword> <repeatPassword> to set a new password
4. The recovery code expires after the configured time (default: 15 minutes)

Rate Limiting

• Players must wait for the cooldown to expire between recovery requests (default: 1 minute)
• Failed recovery code attempts count toward the brute force limit
• After exceeding the maximum recovery attempts, the IP is banned (if enabled)

Email Warning

When email-warning is enabled, players who log in without a linked email will see a warning message suggesting they add one for account security.

---

SendGrid Setup

Step 1: Create a SendGrid Account

1. Visit sendgrid.com and sign up
2. Select a plan — the free tier is suitable for small-to-medium servers

Step 2: Generate an API Key

1. Navigate to Settings > API Keys in the SendGrid dashboard
2. Click Create API Key
3. Select Restricted Access and enable Mail Send — Full Access
4. Name the key (e.g. mineLogin Email Service)
5. Save the generated key immediately — it will not be shown again

Step 3: Verify Sender Identity

1. Go to Settings > Sender Authentication
2. Choose Domain Authentication (recommended) or Single Sender Verification
3. Complete the verification steps provided by SendGrid

Step 4: Configure mineLogin

mailing:
  enabled: true
  server-name: "YourServerName"
  sender-email: "[email protected]"
  from: "YourServerName Support"
  server: "smtp.sendgrid.net"
  port: 587
  username: "apikey"
  password: "SG.your-sendgrid-api-key-here"
  email-title: "Account Recovery for YourServerName"
  transport-strategy: SMTP_TLS

Tip: The username must be literally apikey — this is not a placeholder. The password field contains your actual SendGrid API key.

Step 5: Test

1. Restart the server or reload the plugin with /ml reload
2. Test the account recovery feature by running /recovery <email>
3. Check the spam folder if the email does not arrive in the inbox

SendGrid Best Practices

• Use a dedicated subdomain for sending (e.g. mail.yourserver.com)
• Configure SPF and DKIM records for better email deliverability
• Monitor the SendGrid dashboard for delivery rates and bounces
• Never share your API key publicly or commit it to version control

---

Gmail Setup

mailing:
  enabled: true
  server: "smtp.gmail.com"
  port: 465
  username: "[email protected]"
  password: "your-app-password"
  transport-strategy: SMTPS
  sender-email: "[email protected]"
  from: "Your Server"

Tip: For Gmail, you need to generate an App Password in your Google Account security settings.