APIs
Email Inbox API
Reference

API - Email Inbox - Reference

GET /email-inboxes/

Get all email inboxes associated with the user.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/email-inboxes \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": [
    {
      "id": "d25a64c9-7531-487f-a5ed-02a333cb7775",
      "alias": "support-mycompany",
      "title": "Main Email Inbox",
    },
    {
      "id": "fd023cb9-be89-4a45-a158-eaf977b6235e",
      "alias": "privacy-mycompany",
      "title": "Privacy Inbox",
      "description": "Emails related to privacy concerns",
    }
    ...
  ]
}

GET /email-inbox/:id/

Get a specific email inbox by ID.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/email-inbox/d25a64c9-7531-487f-a5ed-02a333cb7775 \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "id": "d25a64c9-7531-487f-a5ed-02a333cb7775",
    "alias": "support-mycompany",
    "title": "Main Email Inbox",
  },
}

GET /email-inbox/:id/knowledge

Get all knowledge items associated with a email inbox.

ℹ️

Both an id and an alias can be used to identify the email inbox.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/email-inbox/d71efbf4-a37d-4f44-9fc9-a600b8afad29/knowledge \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "24019214-f4ea-417b-9741-e13bc3b6c471",
        "type": "website",
        "base_url": "https://www.mywebsite.com/",
        "trained_at": "2023-12-24T06:05:17.365Z",
        "is_training": false,
        "training_failed_at": null,
        "training_failed_with": null
      },
      ...
    ],
    "total": 40,
    "has_more": true,
    "next_cursor": "MjUuNTA="
  }
}

PUT /email-inbox/:id/knowledge

Add a new knowledge item to a email-inbox.

ℹ️

The knowledge item must have a trained model.
The model can be trained using the /knowledge/:id/train endpoint.

Example request

curl --request PUT \
 --url https://api.aidbase.ai/v1/email-inbox/d71efbf4-a37d-4f44-9fc9-a600b8afad29/knowledge \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --data '{
    "knowledge_id": "24019214-f4ea-417b-9741-e13bc3b6c471"
 }'

Example response

{
  "success": true,
}

DELETE /email-inbox/:id/knowledge

Remove a knowledge item from a email inbox.

ℹ️

The knowledge item will be removed from the email inbox, but the knowledge item itself will not be deleted.

Example request

curl --request DELETE \
 --url https://api.aidbase.ai/v1/email-inbox/d71efbf4-a37d-4f44-9fc9-a600b8afad29/knowledge \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --data '{
    "knowledge_id": "24019214-f4ea-417b-9741-e13bc3b6c471"
 }'

Example response

{
  "success": true,
}

GET /email-inbox/:id/emails

Get all emails associated with an email inbox.

Query Parameters

ParameterTypeDescription
statusstring (optional)Comma-separated list of email statuses to filter by (e.g., open,resolved,closed). Values are trimmed and case-insensitive. Returns HTTP 400 if empty or contains invalid status values.
created_beforestring (optional)Filter emails created before this timestamp. Accepts ISO 8601 date-time strings or any parsable date format (e.g., 2026-02-01T00:00:00Z or 2026-02-01). Returns HTTP 400 if the date format is invalid.
created_afterstring (optional)Filter emails created after this timestamp. Accepts ISO 8601 date-time strings or any parsable date format (e.g., 2026-01-15 or 2026-01-15T00:00:00Z). Returns HTTP 400 if the date format is invalid.
ℹ️

Filters are applied before pagination. The total count in the response reflects the filtered results.

Example request

curl --request GET \
 --url 'https://api.aidbase.ai/v1/email-inbox/d25a64c9-7531-487f-a5ed-02a333cb7775/emails?status=resolved&created_after=2026-01-15' \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h",
        "subject": "Question about pricing",
        "from_email": "customer@example.com",
        "status": "open",
        "created_at": "2024-01-17T11:15:00.000Z",
        "updated_at": "2024-01-17T11:15:00.000Z"
      },
      {
        "id": "h8f2g1d9-4i86-7h6f-1g8i-2d0e1f9g8h7i",
        "subject": "Feature request",
        "from_email": "user@company.com",
        "status": "closed",
        "created_at": "2024-01-16T16:40:00.000Z",
        "updated_at": "2024-01-16T18:20:00.000Z"
      },
      ...
    ],
    "total": 320,
    "has_more": true,
    "next_cursor": "MjUuNTA="
  }
}

GET /email-inbox/:id/emails/:id

Get a specific email by ID.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/email-inbox/d25a64c9-7531-487f-a5ed-02a333cb7775/emails/g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "id": "g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h",
    "subject": "Question about pricing",
    "from_email": "customer@example.com",
    "status": "open",
    "created_at": "2024-01-17T11:15:00.000Z",
    "updated_at": "2024-01-17T11:15:00.000Z",
    "conversation": [
      {
        "role": "user",
        "message": "Hi, I'd like to know more about your pricing plans."
      },
      {
        "role": "assistant",
        "message": "Hello! I'd be happy to help you with pricing information. We offer several plans to fit different needs."
      },
      {
        "role": "user",
        "message": "What's included in the basic plan?"
      },
      {
        "role": "assistant",
        "message": "The basic plan includes up to 1,000 monthly conversations, 1 chatbot, and email support."
      }
    ]
  }
}

PUT /email-inbox/:id/emails/:id/block

Block a specific email, preventing further interaction from the user associated with that email.

ℹ️

This endpoint requires the EMAILINBOXES_WRITE scope.

Example request

curl --request PUT \
 --url https://api.aidbase.ai/v1/email-inbox/d25a64c9-7531-487f-a5ed-02a333cb7775/emails/g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h/block \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "items": [
      {
        "target": "g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h",
        "targetType": "EMAIL",
        "status": "ACTIVE"
      }
    ],
    "failed": []
  }
}

Error cases

StatusErrorDescription
400Bad RequestFailed to block the email.
401UnauthorizedInvalid or missing API key.
403ForbiddenAPI key is missing the `EMAILINBOXES_WRITE` scope, or the email inbox does not belong to the account.
404Not FoundEmail inbox or email not found.

PUT /email-inbox/:id/emails/:id

Update the status and/or priority of a specific email. The change behaves identically to updating an email through the Aidbase app, including full history tracking and any associated side effects.

ℹ️

This endpoint requires the EMAILS_WRITE scope.

Request body

FieldTypeDescription
statusstring (optional)The new status to assign to the email. Must be one of: open, assigned, need_more_info, resolved, closed.
prioritystring (optional)The new priority to assign to the email (e.g., low, medium, high).
⚠️

The request body may only include status and/or priority, and must include at least one of them. Any additional fields will result in an HTTP 400 error. Invalid values for status or priority will also return HTTP 400.

Example request

curl --request PUT \
 --url https://api.aidbase.ai/v1/email-inbox/d25a64c9-7531-487f-a5ed-02a333cb7775/emails/g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --header 'Content-Type: application/json' \
 --data '{
    "status": "resolved"
 }'

Example response

{
  "success": true
}

Error cases

StatusErrorDescription
400Bad RequestMissing or invalid update fields, invalid `status` or `priority`, extra fields in the request body, or invalid/missing path IDs.
401UnauthorizedInvalid or missing API key.
403ForbiddenAPI key is missing the `EMAILS_WRITE` scope, or the email inbox does not belong to the account.
404Not FoundEmail inbox or email not found.

POST /email-inbox/:id/emails/:id/reply

Reply to an email on behalf of the email inbox owner.

ℹ️

This endpoint requires the EMAILS_WRITE scope.

Request body

FieldTypeDescription
messagestring (required)The reply message to send to the email.

Example request

curl --request POST \
 --url https://api.aidbase.ai/v1/email-inbox/d25a64c9-7531-487f-a5ed-02a333cb7775/emails/g7e1f0c8-3h75-6g5e-0f7h-1c9d0e8f7g6h/reply \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --header 'Content-Type: application/json' \
 --data '{
    "message": "Thank you for your inquiry. Our pricing plans start at $29/month."
 }'

Example response

{
  "success": true
}

Error cases

StatusErrorDescription
400Bad RequestMissing `message` or invalid/missing path IDs.
401UnauthorizedInvalid or missing API key.
403ForbiddenAPI key is missing the `EMAILS_WRITE` scope, or the email inbox does not belong to the account.
404Not FoundEmail inbox or email not found.
ReferenceWebhooks
Aidbase Docs © 2026