Skip to content
Ordermatic Docs

📧 Email Alias Quick Start

Generate and manage email aliases to receive purchase orders via inbound email.

🚀 Quick Start (3 Steps)

Section titled “🚀 Quick Start (3 Steps)”

1. Select Your ERP Connection

Section titled “1. Select Your ERP Connection”

Open the webapp Settings → Email Intake page (or query erp_connections in Postgres) and select the active ERP connection for your organization.

2. Generate Aliases

Section titled “2. Generate Aliases”

Create aliases from the webapp Settings UI or via the /api/alias/* API routes (apps/webapp/src/pages/api/alias/):

  • POST /api/alias/generate — Generates the organization alias and member aliases for the selected erpConnectionId
  • GET /api/alias — Lists existing aliases for the organization
  • POST /api/alias/verify — Verifies an email alias token

3. Verify Emails

Section titled “3. Verify Emails”

Verification emails are automatically sent to each alias address. Users can click the verification link to activate, or admins can verify an alias directly using the @repo/db CLI script:

Terminal window
pnpm --filter @repo/db verify-email-alias <alias-email-or-id>

📖 What This Creates

Section titled “📖 What This Creates”

For an organization named “GenFit”:

  • Organization alias: orders+genfit@ordermatic.co
    • Receives emails for entire organization
  • Member aliases: orders+genfit_johnsmith@ordermatic.co
    • One for each organization member
    • Format: {org-slug}_{firstname}{lastname}

🔍 Check Alias Status

Section titled “🔍 Check Alias Status”
Terminal window
# View aliases in database
psql "$DATABASE_URL" -c \
  "SELECT email, status, verified_at FROM email_aliases WHERE erp_connection_id = 'your-connection-id';"

🧪 Test

Section titled “🧪 Test”
  1. Send email to an alias (e.g., orders+genfit@ordermatic.co)
  2. Watch logs: webapp / Temporal logs will show email processing
  3. Verify: Order should be created in your system

📚 Full Documentation

Section titled “📚 Full Documentation”

🛠️ Database Scripts & API Routes

Section titled “🛠️ Database Scripts & API Routes”
Terminal window
# Manually verify an email alias via @repo/db script
pnpm --filter @repo/db verify-email-alias


# Migrate email alias domains (e.g. legacy domain -> ordermatic.co)
pnpm --filter @repo/db migrate-email-aliases-domain

Webapp API routes (apps/webapp/src/pages/api/alias/):

  • POST /api/alias/generate
  • GET /api/alias
  • POST /api/alias/verify
  • DELETE /api/alias/[id]

🆘 Common Issues

Section titled “🆘 Common Issues”

“Unauthorized” Error

Section titled ““Unauthorized” Error”
  • Sign in to the webapp with an active Clerk organization selected
  • Make sure CLERK_SECRET_KEY is set in your local environment

Emails Not Sending

Section titled “Emails Not Sending”
  • Check RESEND_API_KEY in your local environment
  • Verify WEBAPP_URL / APP_URL is set if you need generated verification links to use a public URL

No Aliases Created

Section titled “No Aliases Created”
  • Check DATABASE_URL is correct
  • Verify webapp is running: curl http://localhost:4321/api/health

Database Auth Failed

Section titled “Database Auth Failed”

Update DATABASE_URL in .env with valid PostgreSQL credentials.

📋 How It Works

Section titled “📋 How It Works”

The alias generation flow:

  1. Authenticates the caller and organization context via Clerk
  2. Calls the webapp /api/alias/* routes for the organization’s erpConnectionId
  3. Generates aliases for the organization and members in email_aliases
  4. Sends verification emails (or activates via pnpm --filter @repo/db verify-email-alias)

✅ Next Steps After Alias Generation

Section titled “✅ Next Steps After Alias Generation”
  1. Send test email to an alias to verify the end-to-end flow
  2. Monitor processing in webapp / Temporal logs