Mail

The Mail namespace provides access to the in-game email system. Send emails to the player, attach custom metadata for programmatic detection, and read their inbox.

Required permission: mail

Import

import { Mail } from "@hotbunny/hackhub-content-sdk";

Methods

Mail.send(mail)

Send an email to the player's inbox.

Parameter	Type	Description
mail.subject	string	Email subject line
mail.content	string	Email body (supports HTML)
mail.from	string?	Sender email address
mail.to	string?	Recipient (defaults to player)
mail.metadata	Record<string, any>?	Custom data (not visible to player, available in events)
mail.attachments	MailAttachment[]?	File attachments

Mail.send({
    from: "[email protected]",
    subject: "New assignment",
    content: "Your target is 192.168.1.50. Good luck.",
});

Mail.send({
    from: "[email protected]",
    subject: "Password Reset",
    content: "<p>Click <a href='#'>here</a> to reset your password.</p>",
    metadata: { campaignId: "phish-01", targetType: "admin" },
    attachments: [
        { name: "credentials", extension: "txt", data: "admin:password123" },
    ],
});

Mail.sendBounce(failedRecipient, options?)

Send a realistic "undeliverable" bounce to the player, as if it came from a mailer-daemon at their own mail provider. Useful for phishing scenarios: when the player emails an address that doesn't exist, reply with a bounce so they learn the address was wrong instead of failing silently.

Parameter	Type	Description
failedRecipient	string	The address that could not be reached (shown in the bounce body)
options.to	string?	Recipient of the bounce (defaults to the player)

Events.on("Mail.Sent", (mail) => {
    const validTargets = ["[email protected]", "[email protected]"];
    if (!validTargets.includes(mail.to)) {
        // Player emailed an address that doesn't exist -> bounce it back
        Mail.sendBounce(mail.to);
    }
});

The bounce subject and body are fully localized to the player's language.

Mail.registerTemplate(template)

Register a custom mail template in GoMail's compose dropdown. Players can select this template when writing emails.

Parameter	Type	Description
template.id	string	Unique template identifier
template.label	string	Label shown in the dropdown
template.title	string	Email subject line when selected
template.content	string	Email body with placeholders
template.fields	string[]?	Editable field names

Mail.registerTemplate({
    id: "fake_security_alert",
    label: "Security Alert",
    title: "Security Alert: Unusual Login",
    content: "Dear {{name}}, we detected a login from {{ip}}. If this wasn't you, reset your password immediately.",
    fields: ["name", "ip"],
});

Mail.unregisterTemplate(id)

Remove a previously registered mail template from GoMail.

Mail.unregisterTemplate("fake_security_alert");

Mail.getInbox()

Get all emails in the player's inbox.

Returns: MailInfo[]

const inbox = Mail.getInbox();
const unread = inbox.filter((m) => !m.read);
console.log(`${unread.length} unread emails`);

Mail.markAsRead(id)

Mark an email as read.

const inbox = Mail.getInbox();
Mail.markAsRead(inbox[0].id);

Mail.getPlayerEmail()

Get the player's email address.

Returns: string

const email = Mail.getPlayerEmail();
// e.g. "[email protected]"

Events

Mail.Received

Fires when any email is sent or received (including mails sent by the player via GoMail).

import { Events, Mail } from "@hotbunny/hackhub-content-sdk";

Events.on("Mail.Received", (mail) => {
    console.log(mail.from, mail.to, mail.subject, mail.content);

    // Detect a mail you sent via metadata
    if (mail.metadata?.campaignId === "phish-01") {
        // This is the phishing mail we sent earlier
    }

    // Detect player sending mail via GoMail
    if (mail.from === Mail.getPlayerEmail()) {
        // Player just sent an email - auto-reply
        Mail.send({
            from: mail.to,
            to: mail.from,
            subject: "Re: " + mail.subject,
            content: "Thank you for contacting us.",
        });
    }
});

Mail.Sent

Fires only when the player sends an email via GoMail. Convenient alternative to filtering Mail.Received by sender.

Events.on("Mail.Sent", (mail) => {
    if (mail.to === "[email protected]") {
        // Player sent mail to Binance - generate reply
        Mail.send({
            from: "[email protected]",
            to: mail.from,
            subject: "Re: " + mail.subject,
            content: "Your request has been processed.",
        });
    }
});

Types

MailDefinition

interface MailDefinition {
    subject: string;
    content: string;
    from?: string;
    to?: string;
    metadata?: Record<string, any>;
    attachments?: MailAttachment[];
}

MailTemplateDefinition

interface MailTemplateDefinition {
    id: string;
    label: string;
    title: string;
    content: string;
    fields?: string[];
}

MailAttachment

interface MailAttachment {
    name: string;
    extension: string;
    data?: string;
}

MailInfo

interface MailInfo {
    id: string;
    from: string;
    to: string;
    subject: string;
    read: boolean;
    sentAt: number;
}

MailEvent

Event payload received via Events.on("Mail.Received") or Events.on("Mail.Sent").

interface MailEvent {
    id: string;
    from: string;
    to: string;
    subject: string;
    content: string;
    sentAt: number;
    metadata?: Record<string, any>;
}