Agentuity Documentation

Send and receive emails with managed addresses and webhook destinations.

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Address Management

Create Address

Create a managed address at the @agentuity.email domain.

POST/email/addresses

https://catalyst-usw.agentuity.cloud/email/addresses

Request Body

Address creation payload.

Field	Type	Description
`local_part`	string	Local part before `@agentuity.email`

Response

Created EmailAddress object.

Status	Description
200	Address created
401	Unauthorized

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/email/addresses' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "local_part": "support"
}'

List Addresses

List managed email addresses.

GET/email/addresses

https://catalyst-usw.agentuity.cloud/email/addresses

Response

Array of EmailAddress objects.

Status	Description
200	Addresses returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/addresses' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Address

Get a managed address by ID (eaddr_...).

GET/email/addresses/{id}

https://catalyst-usw.agentuity.cloud/email/addresses/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Address ID (`eaddr_...`)

Response

EmailAddress object.

Status	Description
200	Address returned
401	Unauthorized
404	Address not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/addresses/eaddr_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Connection Config

Get IMAP/POP3 connection settings and credentials for an address.

GET/email/addresses/{id}/connection

https://catalyst-usw.agentuity.cloud/email/addresses/{id}/connection

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Address ID

Response

Connection configuration including IMAP and POP3 details.

Status	Description
200	Connection config returned
401	Unauthorized
404	Address not found

Response Fields

Field	Type	Description
`email`	string	The full email address these settings are for.
`imap`	object	IMAP protocol connection settings.
`imap.host`	string	The mail server hostname.
`imap.port`	number	The mail server port number.
`imap.tls`	string	TLS mode (e.g., `'starttls'`, `'ssl'`, `'none'`).
`imap.username`	string	The authentication username (typically the address ID).
`imap.password`	string	The authentication password.
`pop3`	object	POP3 protocol connection settings.
`pop3.host`	string	The mail server hostname.
`pop3.port`	number	The mail server port number.
`pop3.tls`	string	TLS mode (e.g., `'starttls'`, `'ssl'`, `'none'`).
`pop3.username`	string	The authentication username (typically the address ID).
`pop3.password`	string	The authentication password.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/addresses/eaddr_abc123/connection' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Address

Delete a managed email address.

DELETE/email/addresses/{id}

https://catalyst-usw.agentuity.cloud/email/addresses/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Address ID

Response

Empty response on success.

Status	Description
200	Address deleted
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/email/addresses/eaddr_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Email Destinations

Create Destination

Create an inbound webhook destination for an address.

POST/email/addresses/{addressId}/destinations

https://catalyst-usw.agentuity.cloud/email/addresses/{addressId}/destinations

Parameters

path

Name	Type	Required	Description
`addressId`	string	Yes	Address ID

Request Body

Destination creation payload.

Field	Type	Description
`type`	string	Destination type (`url`)
`config`	object	Destination config including URL

Response

Created EmailDestination object.

Status	Description
200	Destination created
401	Unauthorized

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/email/addresses/eaddr_abc123/destinations' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "url",
  "config": {
    "url": "https://example.com/email-hook",
    "method": "POST"
  }
}'

List Destinations

List inbound destinations for an address.

GET/email/addresses/{addressId}/destinations

https://catalyst-usw.agentuity.cloud/email/addresses/{addressId}/destinations

Parameters

path

Name	Type	Required	Description
`addressId`	string	Yes	Address ID

Response

Array of EmailDestination objects.

Status	Description
200	Destinations returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/addresses/eaddr_abc123/destinations' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Destination

Delete an inbound destination.

DELETE/email/addresses/{addressId}/destinations/{destinationId}

https://catalyst-usw.agentuity.cloud/email/addresses/{addressId}/destinations/{destinationId}

Parameters

path

Name	Type	Required	Description
`addressId`	string	Yes	Address ID
`destinationId`	string	Yes	Destination ID

Response

Empty response on success.

Status	Description
200	Destination deleted
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/email/addresses/eaddr_abc123/destinations/edst_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Sending Email

Send Email

Send an email from an owned address. Delivery is asynchronous and total payload (including attachments) is capped at 25MB.

POST/email/outbound/send

https://catalyst-usw.agentuity.cloud/email/outbound/send

Request Body

Outbound email payload.

Field	Type	Description
`from`	string	The sender email address (must be owned by the organization)
`to`	string[]	The recipient email addresses
`subject`	string	The email subject
`text`	string	Plain text email body (optional)
`html`	string	HTML email body (optional)
`attachments`	object[]	File attachments (optional)
`attachments[].filename`	string	The filename for the attachment
`attachments[].content`	string	The base64-encoded content of the attachment
`attachments[].contentType`	string	The MIME content type of the attachment (optional)
`headers`	object	Custom email headers (e.g., In-Reply-To, References for threading) (optional)

Response

Created EmailOutbound object with initial pending status.

Status	Description
200	Outbound email accepted
401	Unauthorized

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/email/outbound/send' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "support@agentuity.email",
  "to": [
    "user@example.com"
  ],
  "subject": "Welcome!",
  "text": "Thanks for joining Agentuity."
}'

Inbound Email

List Inbound

List inbound emails, optionally filtered by address.

GET/email/inbound

https://catalyst-usw.agentuity.cloud/email/inbound

Parameters

query

Name	Type	Required	Description
`address_id`	string	No	Filter by address ID

Response

Array of EmailInbound objects.

Status	Description
200	Inbound emails returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/inbound?address_id=eaddr_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Inbound

Get a specific inbound email by ID (einb_...).

GET/email/inbound/{id}

https://catalyst-usw.agentuity.cloud/email/inbound/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Inbound email ID (`einb_...`)

Response

EmailInbound object.

Status	Description
200	Inbound email returned
401	Unauthorized
404	Inbound email not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/inbound/einb_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Inbound

Delete an inbound email record.

DELETE/email/inbound/{id}

https://catalyst-usw.agentuity.cloud/email/inbound/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Inbound email ID

Response

Empty response on success.

Status	Description
200	Inbound email deleted
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/email/inbound/einb_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Outbound Email

List Outbound

List outbound emails, optionally filtered by address.

GET/email/outbound

https://catalyst-usw.agentuity.cloud/email/outbound

Parameters

query

Name	Type	Required	Description
`address_id`	string	No	Filter by address ID

Response

Array of EmailOutbound objects.

Status	Description
200	Outbound emails returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/outbound?address_id=eaddr_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Outbound

Get an outbound email by ID (eout_...).

GET/email/outbound/{id}

https://catalyst-usw.agentuity.cloud/email/outbound/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Outbound email ID (`eout_...`)

Response

EmailOutbound object including delivery status and error details.

Status	Description
200	Outbound email returned
401	Unauthorized
404	Outbound email not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/outbound/eout_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Outbound

Delete an outbound email record.

DELETE/email/outbound/{id}

https://catalyst-usw.agentuity.cloud/email/outbound/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Outbound email ID

Response

Empty response on success.

Status	Description
200	Outbound email deleted
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/email/outbound/eout_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Activity

Get Activity

Get daily inbound/outbound activity over a date window.

GET/email/activity/{date}

https://catalyst-usw.agentuity.cloud/email/activity/{date}

Parameters

path

Name	Type	Required	Description
`date`	string	Yes	Date for activity lookup (YYYY-MM-DD format)

query

Name	Type	Required	Description
`days`	number	No	Range in days (7–365, default: 7)

Response

Activity time series grouped by date.

Status	Description
200	Activity returned
401	Unauthorized

Response Fields

Field	Type	Description
`activity`	object[]	Array of daily activity data points, ordered chronologically.
`activity[].date`	string	The date in `YYYY-MM-DD` format.
`activity[].inbound`	number	Number of inbound emails received on this date.
`activity[].outbound`	number	Number of outbound emails sent on this date.
`days`	number	The number of days of data returned.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/email/activity/2026-02-28?days=30' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'