Plus addressing

MailSlurp inboxes can receive emails sent to their address or to their local part with a plus style suffix added. For example if your inbox address is abc@mailslurp.net you can also receive emails sent to abc+123@mailslurp.net. Each sub-address is stored as a plus address entity. In this case the sub-address is 123.

Deterministic plus-address flow

When you know the full inbound plus address (including +suffix), use that full address to get or create a plus-address entity and persist the returned IDs. This avoids broad inbox searches and makes retrieval more predictable.

1. Get or create the plus address by full address and store plusAddressId and inboxId.
2. Use waitFor matching with a TO match to block until the message arrives.
3. List emails by plusAddressId for deterministic read paths.

Get or create by full plus address

BASE_URL="https://api.mailslurp.com"
API_KEY="REPLACE_WITH_API_KEY"
FULL_PLUS_ADDRESS="app-user+signup-9f3a@example.test"

curl -sS -X POST \
  -G "$BASE_URL/inboxes/get-or-create-plus-address" \
  --data-urlencode "fullAddress=$FULL_PLUS_ADDRESS" \
  -H "x-api-key: $API_KEY" \
  -H "accept: application/json"

Example response:

{
  "id": "11111111-2222-3333-4444-555555555555",
  "inboxId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "fullAddress": "app-user+signup-9f3a@example.test",
  "plusAddress": "signup-9f3a"
}

Receiving emails

const inbox = await inboxController.createInbox(opts);
await inboxController.sendEmailAndConfirm({
  inboxId: inbox.id!,
  sendEmailOptions: {
    // send with a "abc" plus address
    to: [`${inbox.localPart}+abc@${inbox.domain}`],
    body: `This message is for alias`
  }
});

Listing emails

Use the plus address string or ID to list emails received to that sub-address. For deterministic retrieval, prefer using plusAddressId with inboxId.

const emailsForPlusAddress = await inboxController.getInboxPlusAddressEmails({
  inboxId: inbox.id,
  plusAddress: 'abc'
});
expect(emailsForPlusAddress.numberOfElements).toEqual(1);
expect(emailsForPlusAddress.content!![0].inboxId).toEqual(inbox.id);

INBOX_ID="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
PLUS_ADDRESS_ID="11111111-2222-3333-4444-555555555555"

curl -sS \
  "$BASE_URL/inboxes/$INBOX_ID/plus-addresses/$PLUS_ADDRESS_ID/emails?page=0&size=20&sort=DESC" \
  -H "x-api-key: $API_KEY" \
  -H "accept: application/json"

Wait for a specific plus address

To wait in real time for an email sent to one alias, use /waitFor with a TO match on the full plus address.

curl -sS -X POST "$BASE_URL/waitFor" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json" \
  --data "{
    \"inboxId\": \"$INBOX_ID\",
    \"count\": 1,
    \"countType\": \"EXACTLY\",
    \"timeout\": 180000,
    \"unreadOnly\": true,
    \"sortDirection\": \"DESC\",
    \"matches\": [
      {
        \"field\": \"TO\",
        \"should\": \"CONTAIN\",
        \"value\": \"$FULL_PLUS_ADDRESS\"
      }
    ]
  }"

List plus addresses for inbox

You can view the plus addresses for an inbox like so:

const plusAddresses = await inboxController.getInboxPlusAddresses({
  inboxId: inbox.id,
})
const plusAddressEntity = plusAddresses.content!![0]
expect(plusAddressEntity.inboxId).toEqual(inbox.id);
expect(plusAddressEntity.plusAddress).toEqual('abc');
expect(plusAddressEntity.fullAddress).toEqual(`${inbox.localPart}+abc@${inbox.domain}`);