Mail tenant credentials

mail-tenant-credentials is an admin-only resource that lets the mail system push the credentials it issued (or reissued) for a Voice team back into HelpGenie Voice. It is the inbound counterpart to the outbound tenant-provisioning call made when a genie mailbox is first created. If the owner_email address has no Voice account yet, one is created automatically. If that account has no team, a team is created as well — so the mail system always receives a stable team_id to store on its side.

All actions on this resource require an internal admin API key. Requests from non-admin callers are rejected with 403 Forbidden.

Upsert tenant credentials

Registers or updates the mail tenant credentials for the team that owns owner_email. Creates a Voice account and team for owner_email if neither exists yet.

string

required

Must be "mail-tenant-credentials"

string

required

Must be "upsert"

object

required

Show properties

string

required

Email address of the Voice team owner. Must be a valid email address. Used to look up (or create) the Voice account that owns the tenant.

string

required

The tenant identifier issued by the mail system for this team.

string

required

The API key issued by the mail system for this tenant.

string | null

Display name for the tenant. Pass null to clear an existing value.

string | null

The mail system’s own user identifier for this owner. Pass null if not available.

boolean

Whether the credentials were stored successfully.

object

Show properties

number

The Voice team ID the credentials were stored under. The mail system should persist this to associate future updates with the same team.

string

The Voice user ID for owner_email. Matches the ID of the newly created account if one was provisioned during this call.

const response = await ApiService.invoke<{
  team_id: number;
  owner_user_id: string;
}>({
  resource: "mail-tenant-credentials",
  action: "upsert",
  data: {
    owner_email: "owner@example.com",
    tenant_id: "tenant-abc123",
    api_key: "mk_live_xxxxxxxxxxxxxxxx",
    tenant_name: "Example Team",
    owner_user_id: "mail-usr-456",
  },
});

const { team_id, owner_user_id } = response;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mail-tenant-credentials",
    "action": "upsert",
    "data": {
      "owner_email": "owner@example.com",
      "tenant_id": "tenant-abc123",
      "api_key": "mk_live_xxxxxxxxxxxxxxxx",
      "tenant_name": "Example Team",
      "owner_user_id": "mail-usr-456"
    }
  }'

{
  "success": true,
  "data": {
    "team_id": 42,
    "owner_user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Side effects

If owner_email does not match any existing Voice account, a new account is created with a temporary password. The owner will need to complete account setup before logging in directly.
If the resolved account has no team, a team is created automatically using the local part of owner_email as the team name.
Calling upsert again for the same owner_email with new credentials will overwrite the previously stored values — no duplicate entries are created.

Error codes

Code	Status	Description
`FORBIDDEN`	403	Caller is not an internal admin
`VALIDATION_ERROR`	400	`owner_email` is missing or invalid, `tenant_id` is missing, or `api_key` is missing
`INVALID_ACTION`	400	Unknown action
`INTERNAL_ERROR`	500	Account or team creation failed, or credential storage failed

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Mail tenant credentials

Upsert tenant credentials

Side effects

Error codes

​Upsert tenant credentials

​Side effects

​Error codes

Upsert tenant credentials

Side effects

Error codes