Skip to main content

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​

Loading...

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.

Loading...
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:

Loading...