Environments

Environments provide logical isolation within an organization. They let you separate resources -- inboxes, messages, domains -- into distinct groups with independent access control. Common use cases include separating production from staging, isolating per-customer data, or creating team-specific workspaces.

Key properties

Default environment

Every organization has a default environment created automatically. All resources are scoped to the default environment unless you explicitly create and use additional environments.

If your use case does not require isolation, you can ignore environments entirely -- everything works within the default environment.

Creating environments

// Create a staging environment
const staging = await client.environments.create({
  name: 'Staging',
  slug: 'staging',
});

// Create per-customer environments
const customerEnv = await client.environments.create({
  name: 'AcmeCo',
  slug: 'acmeco',
});

staging = client.environments.create(
    name="Staging",
    slug="staging",
)

customer_env = client.environments.create(
    name="AcmeCo",
    slug="acmeco",
)

curl -X POST https://api.agent-post.dev/api/v1/environments \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging", "slug": "staging"}'

Resource scoping

When environments are active, resources are automatically scoped. API requests include the environment context, and resources are only visible within their environment.

Organization
  |
  +-- Environment: Production (default)
  |     +-- Inbox: [email protected]
  |     +-- Inbox: [email protected]
  |     +-- Domain: acmeco.com
  |
  +-- Environment: Staging
  |     +-- Inbox: [email protected]
  |     +-- Inbox: [email protected]
  |
  +-- Environment: Customer-AcmeCo
        +-- Inbox: [email protected]
        +-- Inbox: [email protected]

Resources in one environment are invisible to requests scoped to another environment.

Environment access control

You can assign organization members to specific environments, restricting which environments they can access.

// Add a member to an environment
await client.environments.addMember('env_staging', {
  member_id: 'mem_abc123',
});

// List members of an environment
const members = await client.environments.listMembers('env_staging');

// Remove a member from an environment
await client.environments.removeMember('env_staging', 'mem_abc123');

# Add a member to an environment
client.environments.add_member(
    environment_id="env_staging",
    member_id="mem_abc123",
)

# List members
members = client.environments.list_members("env_staging")

# Add a member to an environment
curl -X POST https://api.agent-post.dev/api/v1/environments/env_staging/members \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"member_id": "mem_abc123"}'

# List environment members
curl "https://api.agent-post.dev/api/v1/environments/env_staging/members" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Common patterns

Multi-tenant SaaS

Create one environment per tenant to provide complete data isolation:

// When a new customer signs up
const env = await client.environments.create({
  name: customer.company_name,
  slug: customer.slug,
});

// Create the customer's inbox within their environment
const inbox = await client.inboxes.create({
  username: 'support',
  display_name: `${customer.company_name} Support`,
  environment_id: env.id,
});

Development stages

Separate production, staging, and development:

// Production: default environment
// Staging: separate environment with test data
// Dev: local environment for development

Team isolation

Give each team its own environment with dedicated inboxes:

const salesEnv = await client.environments.create({
  name: 'Sales Team',
  slug: 'sales',
});

const supportEnv = await client.environments.create({
  name: 'Support Team',
  slug: 'support',
});

Relationships

• An environment belongs to one organization
• Inboxes, messages, threads, drafts, and domains are scoped to an environment
• Members can be assigned to specific environments
• API keys inherit environment scoping from their access configuration

Tips

• Start with the default environment. Only create additional environments when you need isolation.
• Environment slugs are immutable after creation -- choose them carefully
• Org owners and admins can access all environments by default
• Deleting an environment does not delete its resources -- they become inaccessible until reassigned
• Use environment-scoped API keys for agents that should only access specific tenants