Email proxies and aliases on demand

Please see our updated alias guide for new instructions on creating and managing aliases.

How it works

You can use MailSlurp to create email aliases. An email alias has a masked address and a public address. These are randomly assigned email addresses that forward to a masked email address when they receive a new email.

Creating aliases

You can create aliases in code or the dashboard. See the pricing page for usage.

Verification

You must manually verify an alias before it is active if the email address has not been validated for your account before.

Example code

You can create aliases using the dashboard or in code and tests. This might be useful for automation. MailSlurp works with many languages. Here is an example of how aliases working using the official Javascript library.

Create a client

const MailSlurp = require("mailslurp-client").default;
const api = new MailSlurp({ apiKey: "YOUR_API_KEY" });

Create an alias

const alias = await api.aliasController
  .createAlias({
    emailAddress: "your@email.address",
    name: "test-alias",
    useThreads: true
  })
  .then((res) => res.json());

Receive emails to the masked account

Now when emails are sent to the email alias account they will be forwarded to the original email address.

Here is an Javascript example showing advanced alias usage. Note the use of reply threads and the AliasController. For more examples see the docs page.

test('can create pending email address alias', async () => {
    // setup
    const inboxControllerApi = new InboxControllerApi(config);
    const emailControllerApi = new EmailControllerApi(config);
    const aliasControllerApi = new AliasControllerApi(config);
    const waitForController = new WaitForControllerApi(config);
    const inboxA = await inboxControllerApi.createInbox({});
    const inboxB = await inboxControllerApi.createInbox({});
    const emailAddressA = inboxA.emailAddress!!;
    const emailAddressB = inboxB.emailAddress!!;

    console.log("Create alias")
    const alias: AliasDto = await aliasControllerApi.createAlias({
        createAliasOptions: {
            emailAddress: emailAddressA,
            useThreads: true,
        },
    });
    expect(alias.maskedEmailAddress).toEqual(emailAddressA);
    expect(alias.emailAddress).not.toEqual(emailAddressA);
    expect(alias.emailAddress).toEqual(`${alias.inboxId}@mailslurp.com`);
    expect(alias.isVerified).toEqual(false);

    console.log("Get alias threads")
    const threadPagination = await aliasControllerApi.getAliasThreads({
        aliasId: alias.id,
    });
    expect(threadPagination.totalElements).toEqual(0);

    // if first time using email address with alias must verify by clicking link sent to the address
    await verifyAliasForInbox(inboxA.id!!);

    console.log("Get alias")
    const aliasRes = await aliasControllerApi.getAlias({ aliasId: alias.id });
    expect(aliasRes.isVerified).toEqual(true)
    expect(aliasRes.inboxId).not.toEqual(inboxA.id);
    expect(aliasRes.inboxId).not.toEqual(inboxB.id);
    expect(aliasRes.maskedEmailAddress).toEqual(emailAddressA);
    expect(aliasRes.useThreads).toBeTruthy();

    // can send email from inboxB to alias that should be delivered to inboxA
    console.log("Send email and confirm")
    const sent = await inboxControllerApi.sendEmailAndConfirm({
        inboxId: inboxB.id!!,
        sendEmailOptions: {
            to: [alias.emailAddress!!],
            subject: 'Hello inbox A',
            body: 'From inbox B',
        },
    });
    expect(sent['from']).toContain(inboxB.emailAddress);
    expect(sent.to).toContain(alias.emailAddress);

    // now expect email is forwarded by alias to InboxA
    console.log("Wait for forwarded email")
    const forwardedEmail = await waitForController.waitForLatestEmail({
        inboxId: inboxA.id,
        unreadOnly: true,
        timeout: 30000,
    });
    expect(forwardedEmail.subject).toContain('Hello inbox A');


    console.log("Wait for the original alias email")
    const aliasEmail = await waitForController.waitForLatestEmail({
        inboxId: alias.inboxId,
        unreadOnly: true,
        timeout: 30000,
    });

    // reply to is a thread address
    expect(forwardedEmail.replyTo).not.toEqual(emailAddressA);
    expect(forwardedEmail.replyTo).not.toEqual(emailAddressB);
    expect(forwardedEmail.read).toBeTruthy();

    // thread was created as a reply to
    console.log("Get alias threads again")
    const threads = await aliasControllerApi.getAliasThreads({
        aliasId: alias.id
    });
    expect(threads.totalElements).toEqual(1);
    const thread = threads.content?.[0];
    expect(thread?.subject).toContain('Hello inbox A');
    expect(thread?.aliasId).toContain(alias.id)

    // can respond via thread
    console.log("Send email from inboxA to threadEmailAddress")
    const threadEmailAddress = forwardedEmail.replyTo!!
    await inboxControllerApi.sendEmail({ inboxId: inboxA.id!!, sendEmailOptions: { to: [threadEmailAddress], subject: "Via thread"}});

    console.log("Wait for reply");
    const threadedReply = await waitForController.waitForLatestEmail({ inboxId: inboxA.id!!, unreadOnly: true, timeout: 30000 })

    // maybe new thread is created?
    // expect(threadedReply.replyTo).toEqual(alias.emailAddress)
    expect(threadedReply.subject).toEqual("Via thread")

    // is the masked email hidden?
    expect(threadedReply.replyTo).not.toContain(alias.maskedEmailAddress)
    expect(threadedReply.from).not.toContain(alias.maskedEmailAddress)

    // reply to and from use the alias
    expect(threadedReply.from).toContain(alias.emailAddress)
    expect(threadedReply.from).not.toContain(alias.maskedEmailAddress)
    expect(threadedReply.replyTo).not.toContain(alias.emailAddress)
    expect(threadedReply.replyTo).not.toContain(alias.maskedEmailAddress)

    // then reply again and expect a new thread (note must use the alias email not the forwarded one)
    const sentReply = await aliasControllerApi.replyToAliasEmail({
        aliasId: alias.id,
        emailId: aliasEmail.id!!,
        replyToAliasEmailOptions: { body: 'Thanks inbox B' }
    });
    expect(sentReply.to).not.toContain(aliasRes.emailAddress);
    expect(sentReply.from).not.toContain(emailAddressA);
    expect(sentReply.replyTo).toEqual(aliasRes.emailAddress);
    expect(sentReply.from).toEqual(aliasRes.emailAddress);

    // can receive new email with new thread
    const newThreadEmail = await waitForController.waitForLatestEmail({
        inboxId: inboxB.id,
        unreadOnly: true,
        timeout: 30000,
    });
    expect(newThreadEmail.subject).toContain('Hello inbox A');
    expect(newThreadEmail.body).toContain('Thanks inbox B');
    expect(newThreadEmail['from']).toContain(alias.emailAddress);
    expect(newThreadEmail.replyTo).toContain(alias.emailAddress);
});

Next steps

Create a free MailSlurp account to get started or see the alias guide for more information.