Create an agent email alias
curl --request POST \
--url https://api.canary.effectiveai.app/api/v2/agent-email/aliases \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"alias": "<string>",
"config": {
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agentName": "<string>"
}
}
'import requests
url = "https://api.canary.effectiveai.app/api/v2/agent-email/aliases"
payload = {
"alias": "<string>",
"config": {
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agentName": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
alias: '<string>',
config: {projectId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', agentName: '<string>'}
})
};
fetch('https://api.canary.effectiveai.app/api/v2/agent-email/aliases', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.canary.effectiveai.app/api/v2/agent-email/aliases",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'alias' => '<string>',
'config' => [
'projectId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'agentName' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.canary.effectiveai.app/api/v2/agent-email/aliases"
payload := strings.NewReader("{\n \"alias\": \"<string>\",\n \"config\": {\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"agentName\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.canary.effectiveai.app/api/v2/agent-email/aliases")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"alias\": \"<string>\",\n \"config\": {\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"agentName\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.canary.effectiveai.app/api/v2/agent-email/aliases")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"alias\": \"<string>\",\n \"config\": {\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"agentName\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"alias": "<string>",
"address": "[email protected]",
"config": {
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agentName": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}Agent email aliases
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.
POST
/
agent-email
/
aliases
Create an agent email alias
curl --request POST \
--url https://api.canary.effectiveai.app/api/v2/agent-email/aliases \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"alias": "<string>",
"config": {
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agentName": "<string>"
}
}
'import requests
url = "https://api.canary.effectiveai.app/api/v2/agent-email/aliases"
payload = {
"alias": "<string>",
"config": {
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agentName": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
alias: '<string>',
config: {projectId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', agentName: '<string>'}
})
};
fetch('https://api.canary.effectiveai.app/api/v2/agent-email/aliases', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.canary.effectiveai.app/api/v2/agent-email/aliases",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'alias' => '<string>',
'config' => [
'projectId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'agentName' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.canary.effectiveai.app/api/v2/agent-email/aliases"
payload := strings.NewReader("{\n \"alias\": \"<string>\",\n \"config\": {\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"agentName\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.canary.effectiveai.app/api/v2/agent-email/aliases")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"alias\": \"<string>\",\n \"config\": {\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"agentName\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.canary.effectiveai.app/api/v2/agent-email/aliases")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"alias\": \"<string>\",\n \"config\": {\n \"projectId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"agentName\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"alias": "<string>",
"address": "[email protected]",
"config": {
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agentName": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}{
"error": "<string>",
"code": "<string>",
"details": [
{
"location": "path",
"path": [
"<string>"
],
"code": "required",
"message": "<string>"
}
],
"requestId": "<string>",
"dataset": "naic",
"businessCode": "<string>",
"violations": [
{
"code": "<string>",
"message": "<string>",
"path": "<string>",
"value": "<unknown>",
"constraint": "<string>",
"cite": "<string>"
}
],
"violationsTruncated": true,
"executionId": "<string>",
"accessUrl": "<string>"
}Authorizations
Effective API key. Send Authorization: Bearer sk-eai-...
Body
application/json
Globally unique short alias: 1–20 lowercase letters or digits with optional internal hyphens.
Required string length:
1 - 20Pattern:
^[a-z0-9]+(-[a-z0-9]+)*$Routing configuration for new email conversations: the destination Project UUID and exact registered agent name. Existing conversations retain their bound session.
Show child attributes
Show child attributes
Response
The created alias.
Globally unique short alias: 1–20 lowercase letters or digits with optional internal hyphens.
Required string length:
1 - 20Pattern:
^[a-z0-9]+(-[a-z0-9]+)*$Email address for this alias in the current environment.
Routing configuration for new email conversations: the destination Project UUID and exact registered agent name. Existing conversations retain their bound session.
Show child attributes
Show child attributes
UTC ISO 8601 timestamp when the alias was created. Generated by the server and unchanged by config updates.
UTC ISO 8601 timestamp when the alias config was last written. Generated by the server; initially equal to createdAt.