Skip to main content

Accounts & Projects

Zyphr uses a two-level organizational model: accounts and projects. This guide covers what they are, how they relate, and how to manage them effectively.

What Are Accounts and Projects?​

Account​

An account is your organization in Zyphr. It is the top-level billing and administrative entity. Your account owns:

  • Subscription & billing — plan, payment methods, invoices
  • Team members — who has access and what role they hold
  • Projects — one or more isolated resource environments

Think of an account as your company or team. One account = one bill.

Project​

A project is an isolated environment within your account. Each project has its own:

  • API keys — live and test keys scoped to this project only
  • Domains — verified sender domains
  • Messages — emails, push notifications, SMS
  • Subscribers — your end-user contact list
  • Webhooks — event notification endpoints
  • Templates — reusable message templates
  • Applications — auth and push app configurations

Projects are how you separate concerns. Most teams create separate projects for Production, Staging, and Development — giving each environment its own API keys, data, and configuration.

How They Relate​

Account (Acme Corp)
├── Billing & Subscription (Pro plan)
├── Team Members (5 people)
├── Project: Production
│   ├── API Keys (zy_live_*, zy_test_*)
│   ├── Domains, Messages, Subscribers, Webhooks...
├── Project: Staging
│   ├── API Keys (zy_live_*, zy_test_*)
│   ├── Domains, Messages, Subscribers, Webhooks...
└── Project: Development
    ├── API Keys (zy_live_*, zy_test_*)
    ├── Domains, Messages, Subscribers, Webhooks...

Usage from all projects rolls up to the account for billing. Plan limits (e.g., 100,000 emails/month) are shared across all projects — not per project.

Creating Your First Account​

When you sign up for Zyphr, an account and a Default project are created automatically. You do not need to configure anything extra to start using Zyphr — your default project is ready to go with API keys, domain verification, and all other features.

You can rename the default project at any time from Project Settings.

Managing Projects​

Creating a Project​

  1. Navigate to Account > Projects in the sidebar
  2. Click New Project
  3. Enter a name and optional description
  4. A URL-friendly slug is auto-generated from the name
  5. Click Create

The new project starts empty — you will need to create API keys, verify domains, and configure resources within it.

Switching Projects​

Use the project switcher dropdown in the dashboard header to switch between projects. Click any project name to switch context. All pages (Messages, Subscribers, Webhooks, Settings, etc.) will immediately show data for the selected project.

The dashboard URL reflects the current account and project:

https://app.zyphr.dev/:accountSlug/:projectSlug/...

For example: https://app.zyphr.dev/acme-corp/production/messages

Project Settings​

Navigate to Project Settings (gear icon in the sidebar) to manage:

  • General tab — Change project name, description, and avatar
  • Tracking tab — Configure open/click tracking for this project
  • Members tab — Add account members to this project and assign project roles

Deleting a Project​

  1. Navigate to Project Settings > General tab
  2. Scroll to the Danger Zone section
  3. Click Delete Project and confirm
warning

Deleting a project permanently removes all its resources — API keys, domains, messages, subscribers, webhooks, and templates. This action cannot be undone.

note

You cannot delete the default project. If you need to start fresh, create a new project and delete the old one, or rename the default project.

Team Members & Roles​

Zyphr uses a two-level role system: account roles control what a user can do across the entire account, and project roles control what they can do within a specific project.

Account Roles​

RoleWhat They Can Do
OwnerFull control. Manage billing, team, all projects, delete account. Multiple owners allowed.
AdminManage team and all projects. Cannot manage billing or delete account.
Billing AdminView and manage billing only. No team or project access.
MemberAccess only projects they are explicitly assigned to.

Project Roles​

RoleWhat They Can Do
AdminFull project control. Manage settings, members, API keys, and all resources.
DeveloperCreate and edit resources. Send messages, manage templates, configure webhooks.
ViewerRead-only access to all project resources.

Role Cascade​

Account Owners and Admins automatically have Admin access to every project in the account. You do not need to assign them to individual projects.

Account Members and Billing Admins must be explicitly added to each project they need access to, with a specific project role.

Inviting Team Members​

  1. Go to Account Settings > Team tab
  2. Click Invite Member
  3. Enter the invitee's email address
  4. Select an account role (Owner, Admin, Billing Admin, or Member)
  5. Click Send Invite

The invitee receives an email with a link to accept the invitation. Once they accept:

  • If their role is Owner or Admin, they automatically have access to all projects
  • If their role is Member, assign them to specific projects from Project Settings > Members tab

Via API​

curl -X POST https://api.zyphr.dev/v1/accounts/ACCOUNT_ID/members/invite \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teammate@company.com",
    "role": "member"
  }'

Assigning Project Access​

  1. Navigate to the project's Settings > Members tab
  2. Click Add Member
  3. Select an existing account member from the dropdown
  4. Choose a project role (Admin, Developer, or Viewer)
  5. Click Add

Via API​

curl -X POST https://api.zyphr.dev/v1/projects/PROJECT_ID/members \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "role": "developer"
  }'

Multiple Accounts​

A single user can belong to multiple accounts. This is useful for freelancers, agencies, or anyone who works across multiple organizations.

  • Use the account switcher dropdown in the dashboard header to switch between accounts
  • Each account has its own billing, plan, team, and projects — completely independent
  • Create a new account from the account switcher dropdown by clicking Create new account

When you switch accounts, the project switcher updates to show that account's projects.

Free Account Limits​

To prevent abuse, Zyphr limits the number of free accounts a single user can own:

  • Each user can own a maximum of 2 free accounts
  • Upgrading an existing account to a paid plan frees up a slot for another free account
  • There is no limit on the number of paid accounts a user can own

If you attempt to create a new account and have already reached the limit, you will be prompted to upgrade an existing account.

Cross-Account Usage Enforcement​

Usage is also enforced at the user level across all accounts you own. If your combined usage across all free accounts exceeds the free-tier limits, you will be blocked from sending until you upgrade.

For example, if you own two free accounts:

AccountEmails Sent
Account A600
Account B500
Total1,100 (exceeds 1,000 free limit)

In this scenario, sending from either account would be blocked until one is upgraded. This prevents circumventing plan limits by spreading usage across multiple free accounts.

Check Cross-Account Usage​

curl https://api.zyphr.dev/v1/usage/user-aggregate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns aggregate usage across all accounts you own, alongside free-tier limits.

API Keys & Project Scoping​

API keys are project-scoped. Each key belongs to exactly one project and can only access resources within that project.

  • A live key (zy_live_*) in Project A cannot access resources in Project B
  • A test key (zy_test_*) operates in test mode for its project only
  • There is no concept of an account-wide API key

When using the SDK or API with an API key, all requests are automatically scoped to the key's project. You do not need to pass a project_id — the API key is the project context.

Creating API Keys​

  1. Ensure you are in the correct project (use the project switcher)
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Select Live or Test
  5. Copy your key — you will only see it once

Via API​

curl -X POST https://api.zyphr.dev/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "type": "live"
  }'

Project Context in the API​

When using JWT authentication (dashboard sessions), include the X-Project-Id header to specify which project you are operating on:

curl https://api.zyphr.dev/v1/emails \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Project-Id: proj_abc123"

When using API key authentication, the project is implicit — no header needed.

Usage & Billing​

How Usage Is Tracked​

  • Each project tracks its own usage independently (emails sent, push notifications, SMS, etc.)
  • All project usage rolls up to the account level for billing enforcement
  • Your plan's limits are shared across all projects

Example​

If your Pro plan includes 100,000 emails/month and you have two projects:

ProjectEmails Sent
Production80,000
Staging5,000
Total85,000 (within the 100,000 limit)

The 100,000 limit is the combined total — not 100,000 per project.

Resource Limits​

Resource limits like max domains, max API keys, max webhooks, and max team members are also account-wide, shared across all projects.

Viewing Per-Project Usage​

  1. Navigate to Usage in the sidebar
  2. Use the project filter to view usage for a specific project or all projects combined
  3. Monitor which projects consume the most resources

Via API​

# Get usage for a specific project
curl https://api.zyphr.dev/v1/usage/current-month?project_id=PROJECT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Account & Project Avatars​

Customize your account and project identities with avatars:

  • Choose from 24 built-in icons or enter a custom image URL
  • Avatars appear in the account/project switcher dropdowns and project listings
  • Set account avatar in Account Settings > General
  • Set project avatar in Project Settings > General

Best Practices​

Separate Environments by Project​

Use separate projects for Production, Staging, and Development. This gives you:

  • Isolated API keys — no risk of a dev key accidentally hitting production resources
  • Clean usage metrics — see production usage without staging noise
  • Independent domains — verify different sender domains per environment
  • Safe testing — test keys in your Development project without affecting production data

Use Project Roles for Access Control​

Give developers full access to staging and development projects, but restrict production:

Team MemberProductionStagingDevelopment
Lead EngineerAdminAdminAdmin
Backend DevViewerDeveloperDeveloper
QA EngineerViewerDeveloperViewer

All resources that serve the same application or environment should live in the same project. Do not split email templates and subscribers across projects — they need to be in the same project to reference each other.

Monitor Per-Project Usage​

Check the Usage page regularly to understand how usage is distributed across projects. If one project is consuming a disproportionate share of your plan limits, consider upgrading your plan or optimizing that project's usage.

Never Share API Keys Across Environments​

Each project should have its own API keys. Never reuse a production key in staging, or vice versa. This prevents accidental cross-environment data access and makes key rotation easier.

Next Steps​