Add an agent

curl --request POST \
  --url https://api.inbox.adraa.ai/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "nickname": "sara",
  "role": "agent"
}
'

import requests

url = "https://api.inbox.adraa.ai/api/v1/agents"

payload = {
    "email": "[email protected]",
    "nickname": "sara",
    "role": "agent"
}
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({email: '[email protected]', nickname: 'sara', role: 'agent'})
};

fetch('https://api.inbox.adraa.ai/api/v1/agents', 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.inbox.adraa.ai/api/v1/agents",
  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([
    'email' => '[email protected]',
    'nickname' => 'sara',
    'role' => 'agent'
  ]),
  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.inbox.adraa.ai/api/v1/agents"

	payload := strings.NewReader("{\n  \"email\": \"[email protected]\",\n  \"nickname\": \"sara\",\n  \"role\": \"agent\"\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.inbox.adraa.ai/api/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"[email protected]\",\n  \"nickname\": \"sara\",\n  \"role\": \"agent\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.inbox.adraa.ai/api/v1/agents")

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  \"email\": \"[email protected]\",\n  \"nickname\": \"sara\",\n  \"role\": \"agent\"\n}"

response = http.request(request)
puts response.read_body

{
  "agent": {
    "id": "cmbxgwq1e0000ph01i0j1k2l3",
    "email": "[email protected]",
    "nickname": "sara",
    "role": "agent",
    "isOnline": true,
    "lastSeen": "2026-06-12T10:25:00.000Z",
    "createdAt": "2026-05-02T08:14:00.000Z"
  }
}

Agents

Add an agent

Adds an agent to the workspace. If no Adraa Inbox account exists for the email, one is created — no invite email is sent; the person signs in at the console with a one-time code sent to that email. If an account already exists, it is added to the workspace with the given role (the existing display name is kept).

Members added with role agent receive the workspace’s default zero-permission “Agent” custom role (own conversations only); an admin can change their role from Settings → Members. Admins are unrestricted.

Rate limit: 30 requests per minute.

POST

api

agents

Add an agent

curl --request POST \
  --url https://api.inbox.adraa.ai/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "nickname": "sara",
  "role": "agent"
}
'

import requests

url = "https://api.inbox.adraa.ai/api/v1/agents"

payload = {
    "email": "[email protected]",
    "nickname": "sara",
    "role": "agent"
}
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({email: '[email protected]', nickname: 'sara', role: 'agent'})
};

fetch('https://api.inbox.adraa.ai/api/v1/agents', 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.inbox.adraa.ai/api/v1/agents",
  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([
    'email' => '[email protected]',
    'nickname' => 'sara',
    'role' => 'agent'
  ]),
  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.inbox.adraa.ai/api/v1/agents"

	payload := strings.NewReader("{\n  \"email\": \"[email protected]\",\n  \"nickname\": \"sara\",\n  \"role\": \"agent\"\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.inbox.adraa.ai/api/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"[email protected]\",\n  \"nickname\": \"sara\",\n  \"role\": \"agent\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.inbox.adraa.ai/api/v1/agents")

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  \"email\": \"[email protected]\",\n  \"nickname\": \"sara\",\n  \"role\": \"agent\"\n}"

response = http.request(request)
puts response.read_body

{
  "agent": {
    "id": "cmbxgwq1e0000ph01i0j1k2l3",
    "email": "[email protected]",
    "nickname": "sara",
    "role": "agent",
    "isOnline": true,
    "lastSeen": "2026-06-12T10:25:00.000Z",
    "createdAt": "2026-05-02T08:14:00.000Z"
  }
}

Authorizations

Authorization

string

header

required

Workspace API token created in Settings → API. Tokens start with adraa_.

Body

application/json

string<email>

required

The agent's sign-in email.

Example:

"[email protected]"

nickname

string

Display name, unique across Adraa Inbox. Generated from the email when omitted. Ignored if the email already has an account.

Maximum string length: 60

Example:

"sara"

role

enum<string>

default:agent

Workspace role. agent members start with the default zero-permission "Agent" custom role (own conversations only).

Available options:

agent,

admin

Response

Agent added to the workspace

agent

object

Show child attributes

API reference

Tokens

Agents

Contacts

Tags

Conversations

Broadcast

WhatsApp

Add an agent

Authorizations

Body

Response