Inboxes

Inboxes are the core concept in VaultSandbox. Each inbox is an isolated, encrypted email destination with its own unique address and encryption keys.

What is an Inbox?

An inbox is a temporary email destination that:

• Has a unique email address (e.g., a1b2c3d4@mail.example.com)
• Supports optional encryption (ML-KEM-768 keypair) based on server policy
• Expires automatically after a configurable time-to-live (TTL)
• Is isolated from other inboxes
• Stores emails in memory on the gateway
• Can optionally skip email authentication checks (SPF/DKIM/DMARC/PTR)

Creating Inboxes

Basic Creation

import com.vaultsandbox.client.VaultSandboxClient;
import com.vaultsandbox.client.ClientConfig;
import com.vaultsandbox.client.Inbox;

ClientConfig config = ClientConfig.builder()
    .apiKey("your-api-key")
    .baseUrl("https://gateway.example.com")
    .build();

VaultSandboxClient client = VaultSandboxClient.create(config);

Inbox inbox = client.createInbox();

System.out.println(inbox.getEmailAddress()); // "a1b2c3d4@mail.example.com"
System.out.println(inbox.getHash());         // "Rr02MLnP7F0pRVC..."
System.out.println(inbox.getExpiresAt());    // Instant

With Options

import com.vaultsandbox.client.CreateInboxOptions;
import java.time.Duration;

Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .ttl(Duration.ofHours(1))
        .emailAddress("test@mail.example.com")
        .build()
);

Note: Requesting a specific email address may fail if it’s already in use. The server will return an error.

With Email Auth Disabled

Disable SPF/DKIM/DMARC/PTR checks for this inbox:

Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .emailAuth(false)
        .build()
);

// All auth results will show "skipped" status
Email email = inbox.waitForEmail();
System.out.println(email.getAuthResults().getSpf().getResult()); // "skipped"

With Encryption Options

Request a specific encryption mode (when server policy allows):

// Request a plain (unencrypted) inbox
Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .encryption("plain")
        .build()
);

// Or use convenience method
Inbox inbox = client.createInbox(CreateInboxOptions.plain());

// Request an encrypted inbox
Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .encryption("encrypted")
        .build()
);

// Or use convenience method
Inbox inbox = client.createInbox(CreateInboxOptions.encrypted());

Note: Encryption options depend on server policy. See Server Info for details.

Inbox Properties

emailAddress

Type: String

The full email address for this inbox.

System.out.println(inbox.getEmailAddress());
// "a1b2c3d4@mail.example.com"

Send emails to this address to have them appear in the inbox.

hash (inboxHash)

Type: String

A unique cryptographic hash identifier for the inbox. Used internally for encryption and identification.

System.out.println(inbox.getHash());
// "Rr02MLnP7F0pRVC6QdcpSIeyklqu3PDkYglvsfN7Oss"

Note: This is not the same as the local part of the email address. The email address local part (e.g., a1b2c3d4 in a1b2c3d4@mail.example.com) is different from the inboxHash.

expiresAt

Type: Instant

When the inbox will automatically expire and be deleted.

System.out.println(inbox.getExpiresAt());
// 2024-01-16T12:00:00Z

// Check if inbox is expiring soon
Duration untilExpiry = Duration.between(Instant.now(), inbox.getExpiresAt());
System.out.printf("Expires in %.1f hours%n", untilExpiry.toHours());

emailAuth

Type: boolean

Whether email authentication checks (SPF/DKIM/DMARC/PTR) are enabled for this inbox.

System.out.println(inbox.isEmailAuth());
// true (default) or false if disabled

When emailAuth is false, all authentication results will have a skipped status.

encrypted

Type: boolean

Whether this inbox uses end-to-end encryption.

System.out.println(inbox.isEncrypted());
// true (encrypted) or false (plain)

Note: When encrypted is true, the inbox will have a serverSigPk property for signature verification. When false, serverSigPk will be null.

Inbox Lifecycle

┌─────────────────────────────────────────────────────────┐
│                  Inbox Lifecycle                        │
└─────────────────────────────────────────────────────────┘

1. Creation
   client.createInbox() → Inbox object
   ↓
   - Keypair generated client-side
   - Public key sent to server
   - Unique email address assigned
   - TTL timer starts

2. Active
   ↓
   - Receive emails
   - List/read emails
   - Wait for emails
   - Monitor for new emails

3. Expiration (TTL reached) or Manual Deletion
   ↓
   inbox.delete() or TTL expires
   - All emails deleted
   - Inbox address freed
   - Keypair destroyed

Working with Inboxes

Listing Emails

List<Email> emails = inbox.listEmails();

System.out.printf("%d emails in inbox%n", emails.size());
for (Email email : emails) {
    System.out.printf("%s: %s%n", email.getFrom(), email.getSubject());
}

Getting a Specific Email

Email email = inbox.getEmail("email-id-123");

System.out.println(email.getSubject());
System.out.println(email.getText());

Waiting for Emails

// Wait for any email (uses default timeout)
Email email = inbox.waitForEmail();

// Wait with custom timeout
Email email = inbox.waitForEmail(EmailFilter.any(), Duration.ofSeconds(30));

// Wait for specific email
Email email = inbox.waitForEmail(
    EmailFilter.subjectContains("Password Reset"),
    Duration.ofSeconds(30)
);

// Wait with filter builder
Email email = inbox.waitForEmail(
    EmailFilter.builder()
        .subject("Welcome")
        .from("noreply@example.com")
        .build(),
    Duration.ofSeconds(30)
);

Wait Methods vs Await Methods

The waitForEmail methods throw TimeoutException if no email arrives:

try {
    Email email = inbox.waitForEmail(Duration.ofSeconds(10));
} catch (TimeoutException e) {
    System.err.println("No email received within timeout");
}

The awaitEmail methods return null on timeout:

Email email = inbox.awaitEmail(Duration.ofSeconds(10));
if (email == null) {
    System.err.println("No email received within timeout");
}

Waiting for Multiple Emails

// Wait for exactly 3 emails
List<Email> emails = inbox.waitForEmailCount(3, Duration.ofSeconds(30));

System.out.printf("Received %d emails%n", emails.size());

Subscribing to New Emails

Subscription subscription = inbox.onNewEmail(email -> {
    System.out.println("New email: " + email.getSubject());
});

// Later, unsubscribe
subscription.unsubscribe();

Deleting Emails

// Delete specific email by ID
inbox.deleteEmail("email-id-123");

// Or via email object
email.delete();

Deleting Inbox

// Delete inbox and all its emails
inbox.delete();

Inbox Isolation

Each inbox is completely isolated:

Inbox inbox1 = client.createInbox();
Inbox inbox2 = client.createInbox();

// inbox1 cannot access inbox2's emails
// inbox2 cannot access inbox1's emails

// Each has its own:
// - Email address
// - Encryption keys
// - Email storage
// - Expiration time

Time-to-Live (TTL)

Inboxes automatically expire after their TTL.

Default TTL

// Uses server's default TTL (typically 24 hours)
Inbox inbox = client.createInbox();

Custom TTL

// Expire after 1 hour
Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .ttl(Duration.ofHours(1))
        .build()
);

// Expire after 10 minutes (useful for quick tests)
Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .ttl(Duration.ofMinutes(10))
        .build()
);

// Expire after 7 days
Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .ttl(Duration.ofDays(7))
        .build()
);

Checking Expiration

Duration timeLeft = Duration.between(Instant.now(), inbox.getExpiresAt());
long minutesLeft = timeLeft.toMinutes();

if (minutesLeft < 5) {
    System.err.println("Inbox expiring soon!");
}

Import and Export

Inboxes can be exported and imported for:

• Test reproducibility
• Sharing between environments
• Backup and restore

Export

// Export via inbox
ExportedInbox exported = inbox.export();

// Or via client
ExportedInbox exported = client.exportInbox(inbox);

// Export to file
client.exportInboxToFile(inbox, Path.of("inbox.json"));

Import

// Import from ExportedInbox object
Inbox inbox = client.importInbox(exported);

// Import from file
Inbox inbox = client.importInboxFromFile(Path.of("inbox.json"));

// Inbox restored with all encryption keys
System.out.println(inbox.getEmailAddress());

Security Warning: Exported data contains private keys. Treat as sensitive and handle securely.

Best Practices

CI/CD Pipelines

Short TTL for fast cleanup:

Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .ttl(Duration.ofHours(1))
        .build()
);

Always clean up:

Inbox inbox = null;
try {
    inbox = client.createInbox();
    // Run tests
} finally {
    if (inbox != null) {
        inbox.delete();
    }
}

Manual Testing

Longer TTL for convenience:

Inbox inbox = client.createInbox(
    CreateInboxOptions.builder()
        .ttl(Duration.ofHours(24))
        .build()
);

Export for reuse:

// Export after creating
client.exportInboxToFile(inbox, Path.of("test-inbox.json"));

// Reuse in later sessions
Inbox inbox = client.importInboxFromFile(Path.of("test-inbox.json"));

Common Patterns

Dedicated Test Inbox (JUnit 5)

class EmailTest {
    private static VaultSandboxClient client;
    private Inbox inbox;

    @BeforeAll
    static void initClient() {
        ClientConfig config = ClientConfig.builder()
            .apiKey(System.getenv("VAULTSANDBOX_API_KEY"))
            .baseUrl(System.getenv("VAULTSANDBOX_URL"))
            .build();
        client = VaultSandboxClient.create(config);
    }

    @BeforeEach
    void setUp() {
        inbox = client.createInbox();
    }

    @AfterEach
    void tearDown() {
        if (inbox != null) {
            inbox.delete();
        }
    }

    @Test
    void shouldReceivePasswordResetEmail() {
        triggerPasswordReset(inbox.getEmailAddress());

        Email email = inbox.waitForEmail(
            EmailFilter.subjectContains("Password Reset"),
            Duration.ofSeconds(10)
        );

        assertThat(email.getSubject()).contains("Password Reset");
    }
}

Multiple Inboxes

Inbox user1Inbox = client.createInbox();
Inbox user2Inbox = client.createInbox();
Inbox adminInbox = client.createInbox();

// Each inbox receives emails independently
sendWelcomeEmail(user1Inbox.getEmailAddress());
sendWelcomeEmail(user2Inbox.getEmailAddress());
sendAdminReport(adminInbox.getEmailAddress());

Creating Multiple Inboxes

List<Inbox> inboxes = IntStream.range(0, 5)
    .mapToObj(i -> client.createInbox())
    .collect(Collectors.toList());

// Clean up all
inboxes.forEach(Inbox::delete);

Inbox Pool

class InboxPool implements Closeable {
    private final VaultSandboxClient client;
    private final Queue<Inbox> pool = new ConcurrentLinkedQueue<>();
    private final int size;

    public InboxPool(VaultSandboxClient client, int size) {
        this.client = client;
        this.size = size;
    }

    public void initialize() {
        for (int i = 0; i < size; i++) {
            pool.add(client.createInbox());
        }
    }

    public Inbox acquire() {
        Inbox inbox = pool.poll();
        if (inbox == null) {
            return client.createInbox();
        }
        return inbox;
    }

    public void release(Inbox inbox) {
        pool.add(inbox);
    }

    @Override
    public void close() {
        pool.forEach(Inbox::delete);
    }
}

Troubleshooting

Inbox Not Receiving Emails

Check:

1. Email is sent to correct address
2. Inbox hasn’t expired
3. DNS/MX records configured correctly
4. SMTP connection successful

// Verify inbox still exists
try {
    List<Email> emails = inbox.listEmails(); // Will error if inbox expired
    System.out.println("Inbox is active");
} catch (InboxNotFoundException e) {
    System.err.println("Inbox has expired");
}

Inbox Already Exists Error

When requesting a specific email address:

try {
    Inbox inbox = client.createInbox(
        CreateInboxOptions.builder()
            .emailAddress("test@mail.example.com")
            .build()
    );
} catch (InboxAlreadyExistsException e) {
    // Address already in use, generate random instead
    Inbox inbox = client.createInbox();
}

Inbox Expired

try {
    List<Email> emails = inbox.listEmails();
} catch (InboxNotFoundException e) {
    System.err.println("Inbox has expired");
    // Create new inbox
    Inbox newInbox = client.createInbox();
}

Invalid Import Data

try {
    Inbox inbox = client.importInboxFromFile(Path.of("old-inbox.json"));
} catch (InvalidImportDataException e) {
    System.err.println("Import failed: " + e.getMessage());
    // Common causes:
    // - Inbox has expired
    // - Invalid key format
    // - Missing required fields
}

Checking Server Encryption Policy

The server’s encryption policy determines how inbox encryption can be configured:

ServerInfo info = client.getServerInfo();
String policy = info.getEncryptionPolicy();

System.out.println("Encryption policy: " + policy);
System.out.println("Can override: " + info.canOverrideEncryption());
System.out.println("Default encrypted: " + info.isDefaultEncrypted());

Encryption Policies

Policy	Default Behavior	Can Override?
always	Encrypted	No - all inboxes are always encrypted
enabled	Encrypted	Yes - can request plain
disabled	Plain	Yes - can request encrypted
never	Plain	No - all inboxes are always plain

Example: Conditional Inbox Creation

ServerInfo info = client.getServerInfo();

CreateInboxOptions.Builder options = CreateInboxOptions.builder();

if (info.canOverrideEncryption() && !info.isDefaultEncrypted()) {
    // Server allows overrides and default is plain - request encrypted
    options.encryption("encrypted");
}

Inbox inbox = client.createInbox(options.build());
System.out.println("Inbox encrypted: " + inbox.isEncrypted());

Next Steps

• Email Objects - Learn about email structure
• Managing Inboxes - Common inbox operations
• Import/Export - Advanced inbox persistence
• API Reference: Inbox - Complete API documentation