> ## Documentation Index > Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent email alias > Reserve a short, globally unique alias for an agent in an existing Project. Requires effective Tenant Admin credentials and a live Project in that workspace. projectId accepts only the Project UUID, and agentName must be the exact registered preset name. Tenant ownership comes from the authenticated workspace. Each request creates one alias; create multiple aliases with separate requests. Sends no email and starts no agent. Retrying an occupied alias returns 409; inspect it with GET after an uncertain response. ## OpenAPI ````yaml /openapi.json post /agent-email/aliases openapi: 3.0.3 info: title: Effective API version: 2.0.0 description: The public Effective REST API. Authenticate using an Effective API key. servers: - url: https://api.canary.effectiveai.app/api/v2 description: Canary security: - bearerAuth: [] paths: /agent-email/aliases: post: tags: - Agent email aliases summary: Create an agent email alias description: >- Reserve a short, globally unique alias for an agent in an existing Project. Requires effective Tenant Admin credentials and a live Project in that workspace. projectId accepts only the Project UUID, and agentName must be the exact registered preset name. Tenant ownership comes from the authenticated workspace. Each request creates one alias; create multiple aliases with separate requests. Sends no email and starts no agent. Retrying an occupied alias returns 409; inspect it with GET after an uncertain response. operationId: createAgentEmailAlias requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2CreateAgentEmailAlias' responses: '201': description: The created alias. content: application/json: schema: $ref: '#/components/schemas/V2AgentEmailAlias' '400': description: Invalid alias, config, query, or cursor. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: >- Tenant administrator access and a valid routing destination are required. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '409': description: Alias unavailable. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: Use application/json. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2CreateAgentEmailAlias: type: object properties: alias: type: string minLength: 1 maxLength: 20 pattern: ^[a-z0-9]+(-[a-z0-9]+)*$ description: >- Globally unique short alias: 1–20 lowercase letters or digits with optional internal hyphens. config: $ref: '#/components/schemas/V2AgentEmailAliasConfigInput' required: - alias - config additionalProperties: false V2AgentEmailAlias: type: object properties: alias: type: string minLength: 1 maxLength: 20 pattern: ^[a-z0-9]+(-[a-z0-9]+)*$ description: >- Globally unique short alias: 1–20 lowercase letters or digits with optional internal hyphens. address: type: string format: email description: Email address for this alias in the current environment. config: $ref: '#/components/schemas/V2AgentEmailAliasConfig' createdAt: type: string format: date-time description: >- UTC ISO 8601 timestamp when the alias was created. Generated by the server and unchanged by config updates. updatedAt: type: string format: date-time description: >- UTC ISO 8601 timestamp when the alias config was last written. Generated by the server; initially equal to createdAt. required: - alias - address - config - createdAt - updatedAt additionalProperties: false V2CodedError: allOf: - $ref: '#/components/schemas/V2Error' - type: object properties: code: type: string minLength: 1 description: Stable error code. Clients must tolerate unknown future codes. details: type: array items: type: object properties: location: type: string enum: - path - query - header - body path: type: array items: type: string maxLength: 64 maxItems: 12 code: type: string enum: - required - invalid_type - invalid_value - unknown_field message: type: string minLength: 1 maxLength: 200 required: - location - path - code - message minItems: 1 maxItems: 20 description: Bounded safe validation issues; may omit some invalid fields. requestId: type: string minLength: 1 maxLength: 128 description: >- Existing server correlation for this HTTP attempt, when available. dataset: type: string enum: - naic - osha description: Dataset needed for dataset_not_enabled. businessCode: type: string description: The rater’s own refusal code, for business_rejection. violations: type: array items: type: object properties: code: type: string description: Authored or built-in constraint code message: type: string description: Authored message for the failed constraint path: type: string description: Input path of the offending value; empty for the request value: nullable: true description: Offending input value, size-bounded by the runtime constraint: type: string description: The constraint the value failed, as text cite: type: string nullable: true description: >- Filing citation of the constraint, when the source cites one required: - code - message - path - value - constraint - cite additionalProperties: false maxItems: 256 description: >- Each input constraint the submission failed, for invalid_inputs and business_rejection. violationsTruncated: type: boolean description: >- True when the rater reported more violations than violations holds. executionId: type: string description: >- The recorded execution of a failed rating, for rater rating failures. accessUrl: type: string nullable: true format: uri description: >- Where to add the product to your account, for product_access_required. required: - code V2AgentEmailAliasConfigInput: type: object properties: projectId: type: string format: uuid description: >- Immutable UUID of an existing Project in the authenticated workspace. agentName: type: string minLength: 1 description: >- Exact registered agent preset name, such as general-agent. Agent IDs are not accepted. required: - projectId - agentName additionalProperties: false description: >- Routing configuration for new email conversations: the destination Project UUID and exact registered agent name. Existing conversations retain their bound session. V2AgentEmailAliasConfig: type: object properties: projectId: type: string format: uuid description: Immutable UUID of the configured Project. agentName: type: string minLength: 1 description: >- Exact registered agent preset name, such as general-agent. Agent IDs are not accepted. required: - projectId - agentName additionalProperties: false description: >- Routing configuration for new email conversations: the destination Project UUID and exact registered agent name. Existing conversations retain their bound session. V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: 'Effective API key. Send Authorization: Bearer sk-eai-...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.