Skip to main content

Alias proxy mailbox

Proxy inboxes allow you to mask email addresses behind an alias. To use +abc style sub-address aliases see the plus address inbox feature.

How it works​

alias

MailSlurp aliases act as an intermediary between your real email address and an external sender. You can create an alias and then use it to receive and reply to emails.

The alias has a unique email address. Give this to external parties. When the alias receives an email it will forward the email to your real email address. If you enable threads your can reply to the forwarded email and it will be passed back to the sender via another inbox to obscure your address.

Threads​

When threads are enabled for an alias each proxied email will have a reply-to header that points to a new inbox. When this thread inbox receives an email it will pass it back to the original external sender. If threads are not enabled you should not reply directly to a forwarded email. In this case you should use the alias controller reply methods (see examples).

Verification​

By default all aliases must be verified before they can be used. This is to prevent abuse. You can disable verification by adding a masked email address as a contact before creating the alias. This will automatically verify the alias.

Examples​

Here are some alias proxy examples:

Simple proxy​

To hide your email address create a proxy and pass your address:

// create an alias that hides your private address
const alias = await mailslurp.aliasController.createAlias({
    createAliasOptions: {
        emailAddress: myPrivateEmail,
        useThreads: true // allows replies to be proxied
    }
})
expect(alias.emailAddress).not.toEqual(myPrivateEmail)
expect(alias.maskedEmailAddress).toEqual(myPrivateEmail)

Then use the returned alias email address with external parties. When they email your proxy address it will be forwarded to your private email address.

// when an external user emails the alias the email is forwarded to your hidden address
await sendEmailToAliasFromExternalSender()
// to demonstrate this we used a mailslurp inbox as our masked email address
expect(myPrivateEmail).toEqual(myPrivateInbox.emailAddress)
// we can use mailslurp to receive the forwarded email and attest that no private details were revealed
const proxiedEmail = await mailslurp.waitForLatestEmail(myPrivateInbox.id, 120_000)
// the forwarded email contains the original email but uses another inbox for replies
expect(proxiedEmail.sender?.emailAddress).toEqual(alias.emailAddress)
expect(proxiedEmail.sender?.name).toEqual('Big Company')
expect(proxiedEmail.subject).toEqual('From intrusive company')
expect(proxiedEmail.body).toEqual('Tell me your name')
// reply-to is set to a mailslurp account so that replies can be passed through the proxy to hide your address
expect(proxiedEmail.replyTo).toContain('@mailslurp')

When threads are enabled we can reply directly to the email and it will be passed back through a secondary inbox to obscure your account:

// when we reply the external sender cannot see our details
await mailslurp.inboxController.sendEmail({
    inboxId: myPrivateInbox.id,
    sendEmailOptions: {
        to: [proxiedEmail.replyTo!!],
        subject: 'I am replying incognito',
        body: 'My details are hidden'
    }
})
const emailReceivedByExternal = await mailslurp.waitForLatestEmail(externalInbox.id, 120_000, true)
const { content: rawReply } = await mailslurp.emailController.getRawEmailJson({
    emailId: emailReceivedByExternal.id
})
// raw email is an SMTP envelope
expect(rawReply).toContain('Content-Type: multipart/mixed')
// here we can see that the reply was proxied through the alias and our address is hidden
expect(rawReply).not.toContain(myPrivateEmail)

Using reply method​

When threads are disabled use the alias controller reply methods to reply.

// if you don't want to use threads then you can use the api reply methods to communicate with original sender
const domains = await mailslurp.domainController.getDomains()
const myDomain = domains.filter(it => it.domainType === 'HTTP_INBOX')[0]!!;

// create an email address to test masking
const myMaskedMailbox = await mailslurp.inboxController.createInbox({
    inboxType: CreateInboxInboxTypeEnum.HTTP_INBOX
})

// create an inbox with custom domain for the alias
const inboxForAlias = await mailslurp.inboxController.createInbox({
    inboxType: CreateInboxInboxTypeEnum.HTTP_INBOX,
    domainName: myDomain.domain
})
expect(inboxForAlias.emailAddress).toContain(`@${myDomain.domain}`)
expect(inboxForAlias.domainId).toEqual(myDomain.id)

// create alias with domain
const alias = await mailslurp.aliasController.createAlias({
    createAliasOptions: {
        emailAddress: myMaskedMailbox.emailAddress,
        inboxId: inboxForAlias.id,
        name: 'Alias test',
        useThreads: false
    }
})
expect(alias.useThreads).toEqual(false)
// now test sending to and from alias
const externalMailbox = await mailslurp.inboxController.createInbox({});

// send email from external to alias
const sent = await mailslurp.sendEmail(externalMailbox.id, {
    to: [alias.emailAddress],
    subject: 'hello alias',
    body: 'test',
});
expect(sent.to).toEqual([alias.emailAddress]);

// now wait for email to arrive in the masked account
const received = await mailslurp.waitForLatestEmail(myMaskedMailbox.id, 120_000, true);

// expect the email received by the masked inbox
expect(received.from).toEqual(alias.emailAddress);
// as no thread is used no reply is set
expect(received.headersMap!!["Reply-To"]).toEqual(["no-reply@mailslurp.com"]);
expect(received.replyTo).toEqual("no-reply@mailslurp.com");

// get the emails belonging to the alias
const aliasEmails = await mailslurp.aliasController.getAliasEmails({
    aliasId: alias.id
})
// because no threads are used we can reply using the alias controller reply method
const sentReply = await mailslurp.aliasController.replyToAliasEmail({
    aliasId: alias.id,
    emailId: aliasEmails.content!![0].id,
    replyToAliasEmailOptions: {
        body: 'This is a reply',
        isHTML: true
    }
})
expect(sentReply.to).toEqual([externalMailbox.emailAddress])
const receivedReply = await mailslurp.waitForLatestEmail(externalMailbox.id, 120_000, true)
expect(receivedReply.from).toEqual(alias.emailAddress)

Custom domains​

Here is an example with custom domains and threads that use those domains:

// using threads allows you to reply directly to an alias and have the reply sent to the original sender
// get domain
const domains = await mailslurp.domainController.getDomains()
const myDomain = domains.filter(it => it.domainType === 'HTTP_INBOX')[0]!!;
// create an email address to test masking
const myMaskedMailbox = await mailslurp.inboxController.createInbox({
    inboxType: CreateInboxInboxTypeEnum.HTTP_INBOX
})
// create an inbox with custom domain for the alias
const inboxForAlias = await mailslurp.inboxController.createInbox({
    inboxType: CreateInboxInboxTypeEnum.HTTP_INBOX,
    domainName: myDomain.domain
})
expect(inboxForAlias.emailAddress).toContain(`@${myDomain.domain}`)
expect(inboxForAlias.domainId).toEqual(myDomain.id)
// create alias with domain
const alias = await mailslurp.aliasController.createAlias({
    createAliasOptions: {
        emailAddress: myMaskedMailbox.emailAddress,
        inboxId: inboxForAlias.id,
        name: 'Alias test',
        useThreads: true
    } as any
})
expect(alias.useThreads).toEqual(true)
expect(alias.isVerified).toEqual(true)
// expect alias to hide our masked mailbox and to use an inbox that has custom domain
expect(alias.maskedEmailAddress).toEqual(myMaskedMailbox.emailAddress)
expect(alias.emailAddress).toContain(`@${myDomain.domain}`)
// now test sending to and from alias
const externalMailbox = await mailslurp.inboxController.createInbox({});

// send email from external to alias
const sent = await mailslurp.sendEmail(externalMailbox.id, {
    to: [alias.emailAddress],
    subject: 'hello alias',
    body: 'test',
});
expect(sent.to).toEqual([alias.emailAddress]);

// now wait for email to arrive in the masked account
const received = await mailslurp.waitForLatestEmail(myMaskedMailbox.id, 120_000, true);

// expect a thread to be created for the alias
const threads = await mailslurp.aliasController.getAliasThreads({
    aliasId: alias.id
})
expect(threads.content?.length).toEqual(1)
const thread = threads.content!![0]
expect(thread.aliasId).toEqual(alias.id)
const threadInbox = await mailslurp.getInbox(thread.inboxId)
expect(threadInbox.emailAddress).toContain(`@${myDomain.domain}`)
expect(threadInbox.domainId).toEqual(myDomain.id)

// expect the email received by the masked
// inbox to be from the alias and have reply to set to the thread address
expect(received.from).toEqual(alias.emailAddress);
expect(received.headersMap!!["Reply-To"]).toEqual([threadInbox.emailAddress]);
expect(received.replyTo).toEqual(threadInbox.emailAddress);

Alias options​

Loading...

Custom domains​

Alias inboxes support custom domains. To enable domains for aliases and replyTo addresses pass an inboxId and domainId when creating the alias. This will ensure that all addresses generated by the alias use your custom domain.