This document covers security considerations when using the VeilMail SDK in different Unreal Engine deployment scenarios.

Using VeilMail from the Unreal Editor is safe. The editor runs on a developer's machine, and API keys stored in project settings are not accessible to end users.

Typical use cases:

• Sending test emails during development
• Triggering email notifications from editor tools and automation scripts
• Testing email templates and integrations

The VeilMailEditor module provides a built-in "Send Test Email" window accessible from Tools > VeilMail: Send Test Email. This module is only loaded in editor builds and is never included in packaged games.

Running VeilMail on a dedicated game server is safe. Dedicated server builds run on infrastructure you control, and clients never have access to the server binary or its configuration.

Typical use cases:

• Sending transactional emails when players complete actions (registration confirmation, purchase receipts, match summaries)
• Triggering campaign emails based on in-game events
• Webhook verification on your server

Recommendations:

• Store API keys in environment variables or server configuration files, not hardcoded in source
• Use UVeilMailClient::CreateClient() with runtime-loaded credentials rather than project settings
• Restrict API key permissions to only the operations your server needs

Never include your VeilMail API key in a shipped game client. Game clients are distributed to end users, and any secrets embedded in the binary can be extracted through reverse engineering, memory inspection, or network traffic analysis.

Why this is dangerous:

• Players can extract the API key from the game binary
• Extracted keys can be used to send emails on your behalf
• Attackers could exhaust your email quota, send spam, or access your account data
• There is no way to fully protect secrets in a client binary, regardless of obfuscation

Instead, use a proxy architecture:

Game Client  -->  Your Backend Server  -->  Veil Mail API
  (no key)         (has API key)            (processes email)

1. The game client sends a request to your own backend server (e.g., "send welcome email to this player")
2. Your backend server validates the request, applies rate limiting, and calls the Veil Mail API with the API key
3. The response flows back through your server to the game client

Implementation example:

• Create a simple REST endpoint on your game server: POST /api/send-email
• The game client calls your endpoint (authenticated with the player's session token)
• Your server validates the request and forwards it to Veil Mail

The plugin includes a safety setting called Strip API Key in Shipping Builds, enabled by default in project settings (Edit > Project Settings > Plugins > VeilMail).

When this setting is enabled:

• The API key configured in project settings will not be loaded in shipping builds
• Attempts to create a client from settings in a shipping build will result in an empty API key
• This prevents accidental inclusion of API keys in distributed game clients

This setting is a safety net, not a security solution. Even with this setting disabled, you should never rely on client-side API key usage for shipped games. Always use a backend proxy.

1. Use test keys for development. Veil Mail provides test API keys (veil_test_xxx) that do not send real emails. Use these during development and in editor builds.

2. Use live keys only on servers. Live API keys (veil_live_xxx) should only exist on infrastructure you control: dedicated servers, backend APIs, or CI/CD pipelines.

3. Rotate keys regularly. If you suspect a key has been compromised, rotate it immediately in the Veil Mail dashboard.

4. Use scoped keys. Create API keys with the minimum permissions required for each use case. A server that only sends emails does not need access to domain management or analytics.

5. Do not commit keys to version control. Use environment variables, secrets managers, or encrypted configuration files. Never check API keys into your repository.

When receiving webhooks from Veil Mail, always verify the signature to ensure the request is authentic:

#include "VeilMailWebhook.h"

bool bValid = UVeilMailWebhook::VerifySignature(
    RequestBody,      // Raw request body string
    SignatureHeader,  // Value of the X-VeilMail-Signature header
    WebhookSecret     // Your webhook signing secret
);

if (!bValid)
{
    // Reject the request - signature verification failed
    return;
}

This is a BlueprintCallable static function and can also be used from Blueprints.

• All API requests use HTTPS (TLS 1.2+)
• The SDK sets a User-Agent header (veilmail-unreal/0.1.0) for request identification
• HTTP timeouts are configurable to prevent hanging connections (default: 30 seconds)
• No data is cached locally on disk by the SDK

If you discover a security vulnerability in the VeilMail SDK or API, please report it responsibly by emailing security@veilmail.xyz. Do not open a public issue.