> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound email addresses

> Email addresses your account receives mail at: who owns them, what they are for, who can manage them, and what an address does and does not prove

## Overview

An inbound email address is an address that Apostra receives mail at on behalf
of your account. You can give one to a partner, a colleague, or a system that
sends you briefs or reports, and every message sent to it is recorded in your
account.

Each address:

* **belongs to your account**, and can optionally belong to one of your
  advertisers;
* **has a purpose**, which says what the address is for;
* **receives mail until you rotate or revoke it.**

<Note>
  Inbound email is in a limited pilot for enrolled accounts. If your account is
  not enrolled, or inbound email is not available where you are calling,
  creating or rotating an address returns `FEATURE_NOT_ENABLED`. You can always
  list and revoke the addresses you already have.
</Note>

## What an address looks like

An address has three parts, for example:

```text theme={null}
coke-reports-k7m2qz4xhd9a@in.apostra.com
└──┬───────┘ └────┬─────┘ └─────┬──────┘
 readable      random     inbound domain
  prefix       suffix
```

* The **readable prefix** is your advertiser's name, or your account's name for
  an account-wide address, followed by the purpose. It helps a person recognise
  the address. It grants nothing.
* The **random suffix** is twelve characters drawn at random, so nobody can
  guess an address from your name.
* The **inbound domain** is a dedicated receiving domain. It is not the domain
  Apostra sends email from.

Apostra chooses every part of the address. You cannot pick your own address or
use your own domain.

## Purposes

| Purpose | Use it for |
| - | - |
| `briefs` | Briefs, RFPs and campaign requests |
| `reports` | Delivery, performance and billing reports |

The purpose is recorded with the address and is part of its readable prefix.
Today, mail for both purposes is handled the same way: each message is recorded
privately in your account as a received-message entry, without its text. The
message and its attachments are retained as evidence, but Apostra does not yet
read, summarise or act on their contents.

## What happens to mail

* **Mail to an active address** is recorded in the account that owns the
  address, and only that account.
* **Mail to an unknown address** is refused. No message content is stored.
* **Mail to a revoked address, or to an address that has been rotated away,** is
  refused in the same way, from the moment it was revoked or rotated.

## An address says where an email belongs, not who sent it

Anyone who knows an address can send mail to it. The address tells Apostra which
account a message belongs to; it never proves who sent the message.

* The sender's address is recorded as an observation. It is not verified and is
  not treated as a member of your account.
* Sending mail to an address does not give the sender access to your account,
  your Sessions, or anything else.
* Treat an address like a private inbox: share it only with the people and
  systems that should send you mail. If it reaches the wrong people, rotate it.

## Who can manage addresses

Account admins can create, list, rotate and revoke their account's addresses.
Other account members cannot. An API key needs the `interchange:admin`
permission. Apostra operators can also manage addresses on your behalf.

An address can only be named after an advertiser that belongs to your account.
Nobody in your account can see, rotate or revoke another account's addresses.

## Rotate or revoke an address

* **Rotate** replaces an address with a new one. The new address keeps the same
  readable prefix, owner and purpose, with a new random suffix. The old address
  stops receiving at once, so tell your senders about the new one.
* **Revoke** stops an address receiving mail. Revocation cannot be undone; create
  a new address if you need one again.

Both keep the record of what the address received.

## API reference

| Action | REST | MCP (`api_call` operation) |
| - | - | - |
| List | `GET /api/v2/inbound-email-addresses` | `list_inbound_email_addresses` |
| Create | `POST /api/v2/inbound-email-addresses` | `create_inbound_email_address` |
| Rotate | `POST /api/v2/inbound-email-addresses/{id}/rotate` | `rotate_inbound_email_address` |
| Revoke | `POST /api/v2/inbound-email-addresses/{id}/revoke` | `revoke_inbound_email_address` |

Create takes a `purpose` (`briefs` or `reports`) and an optional `advertiserId`.
List returns active addresses by default; pass `status=all` to include revoked
ones. It returns up to `take` addresses (default 100, at most 500) after
skipping `skip`, with the matching `total`, so page with `skip` until you have
them all. The same operations are available to buyer and storefront accounts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.