# Plus addressing

![](/mermaid-gen/plus-address.mmd.svg)

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](/docs/wait-for/) 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

```bash
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:

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

## Receiving emails

```typescript
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`.

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

```bash
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.

```bash
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:

```typescript
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}`);
```