> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revreply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate an Email Response

> Classifies an incoming email and, when appropriate, generates an AI response based on the selected agent.

<Badge color="blue">POST</Badge> `https://api.revreply.com/v1/response/generate`

<Note>
  This endpoint requires authentication.
</Note>

## Try it

Use the following request to classify an incoming email and generate a response:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.revreply.com/v1/response/generate" \
      -H "Authorization: Bearer <YOUR_JWT>" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{
        "email_body": "Hi John, I would like to learn more about your product.",
        "agent_id": 123,
        "prospect_name": "Jane Smith",
        "available_slots": [
          "2026-08-25 10:00:00",
          "2026-08-26 14:00:00"
        ],
        "generate_calendly_event": 1,
        "thread_id": "abc123xyz"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.revreply.com/v1/response/generate",
      {
        method: "POST",
        headers: {
          "Authorization": "Bearer <YOUR_JWT>",
          "Accept": "application/json",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          email_body: "Hi John, I would like to learn more about your product.",
          agent_id: 123,
          prospect_name: "Jane Smith",
          available_slots: [
            "2026-08-25 10:00:00",
            "2026-08-26 14:00:00"
          ],
          generate_calendly_event: 1,
          thread_id: "abc123xyz"
        })
      }
    );
    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://api.revreply.com/v1/response/generate",
        headers={
            "Authorization": "Bearer <YOUR_JWT>",
            "Accept": "application/json",
            "Content-Type": "application/json",
        },
        json={
            "email_body": "Hi John, I would like to learn more about your product.",
            "agent_id": 123,
            "prospect_name": "Jane Smith",
            "available_slots": [
                "2026-08-25 10:00:00",
                "2026-08-26 14:00:00",
            ],
            "generate_calendly_event": 1,
            "thread_id": "abc123xyz",
        },
    )
    data = response.json()
    print(data)
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $ch = curl_init("https://api.revreply.com/v1/response/generate");

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer <YOUR_JWT>",
            "Accept: application/json",
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            "email_body" => "Hi John, I would like to learn more about your product.",
            "agent_id" => 123,
            "prospect_name" => "Jane Smith",
            "available_slots" => [
                "2026-08-25 10:00:00",
                "2026-08-26 14:00:00",
            ],
            "generate_calendly_event" => 1,
            "thread_id" => "abc123xyz",
        ]),
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $response = curl_exec($ch);
    curl_close($ch);
    echo $response;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "bytes"
        "fmt"
        "net/http"
    )

    func main() {
        body := []byte(`{
          "email_body": "Hi John, I would like to learn more about your product.",
          "agent_id": 123,
          "prospect_name": "Jane Smith",
          "available_slots": [
            "2026-08-25 10:00:00",
            "2026-08-26 14:00:00"
          ],
          "generate_calendly_event": 1,
          "thread_id": "abc123xyz"
        }`)

        req, _ := http.NewRequest(
            "POST",
            "https://api.revreply.com/v1/response/generate",
            bytes.NewBuffer(body),
        )

        req.Header.Set("Authorization", "Bearer <YOUR_JWT>")
        req.Header.Set("Accept", "application/json")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        response, _ := client.Do(req)
        fmt.Println(response.Status)
    }
    ```
  </Tab>
</Tabs>

## Authentication

This endpoint uses Bearer authentication with a JWT.

## Request

### Headers

| Header          | Type     | Required | Description                                                    |
| --------------- | -------- | -------- | -------------------------------------------------------------- |
| `Authorization` | `string` | Yes      | Bearer token used to authenticate the request.                 |
| `Accept`        | `string` | Yes      | Specifies that the client expects the response in JSON format. |
| `Content-Type`  | `string` | Yes      | Specifies that the request body is formatted as JSON.          |

```http theme={null}
Authorization: Bearer <YOUR_JWT>
Accept: application/json
Content-Type: application/json
```

### Body

The request body uses the `GenerateResponseRequest` schema.

| Field                     | Type             | Required    | Description                                                                                                                                    | Example                                                   |
| ------------------------- | ---------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `email_body`              | `string`         | Yes         | Incoming email content. Maximum length: 1000 characters.                                                                                       | `Hi John, I would like to learn more about your product.` |
| `agent_id`                | `integer`        | Yes         | ID of the agent to use when generating the response.                                                                                           | `123`                                                     |
| `prospect_name`           | `string`         | Yes         | Name of the prospect.                                                                                                                          | `Jane Smith`                                              |
| `available_slots`         | `array[string]`  | Conditional | Available meeting slots. Required when the agent objective is `Schedule Meeting`. Dates are interpreted using the agent's configured timezone. | `["2026-08-25 10:00:00"]`                                 |
| `generate_calendly_event` | `integer`        | No          | Whether to generate a Calendly event. Allowed values are `0` or `1`.                                                                           | `1`                                                       |
| `thread_id`               | `string \| null` | No          | Existing email thread identifier.                                                                                                              | `abc123xyz`                                               |

The body requires `email_body`, `agent_id`, and `prospect_name`. When the selected agent's objective is `Schedule Meeting`, `available_slots` is also required.

### Request structure

```json theme={null}
{
  "email_body": "Hi John, I would like to learn more about your product.",
  "agent_id": 123,
  "prospect_name": "Jane Smith",
  "available_slots": [
    "2026-08-25 10:00:00",
    "2026-08-26 14:00:00"
  ],
  "generate_calendly_event": 1,
  "thread_id": "abc123xyz"
}
```

### Request examples

The request is a `POST` request to:

```text theme={null}
https://api.revreply.com/v1/response/generate
```

## Response

### Response structure

A successful request returns an object containing the generated response.

| Field                 | Type      | Required | Description                                                |
| --------------------- | --------- | -------- | ---------------------------------------------------------- |
| `success`             | `integer` | Yes      | Indicates whether the response was generated successfully. |
| `data`                | `object`  | Yes      | Generated response data.                                   |
| `data.thread_id`      | `string`  | Yes      | Email thread identifier.                                   |
| `data.classification` | `string`  | Yes      | Classification assigned to the incoming email.             |
| `data.reply`          | `string`  | Yes      | AI-generated email reply.                                  |

The response schema requires `thread_id`, `classification`, and `reply` inside `data`.

### Response example

```json theme={null}
{
  "success": 1,
  "data": {
    "thread_id": "abc123xyz",
    "classification": "INTERESTED",
    "reply": "Hi Jane, Thanks for getting back to me. I'd be happy to schedule a quick call. Would Tuesday at 10 AM work?"
  }
}
```

## Errors

### 402 — Insufficient credits

Returned when there are not enough credits to generate the response.

```json theme={null}
{
  "success": 0,
  "message": "Insufficient credits"
}
```

### 404 — Agent or thread not found

Returned when the specified agent or email thread cannot be found.

```json theme={null}
{
  "success": 0,
  "message": "Something went wrong"
}
```

### 422 — Validation error

Returned when one or more request fields fail validation.

```json theme={null}
{
  "success": 0,
  "message": "Validation failed",
  "errors": {}
}
```

### 500 — Response generation failed

Returned when response generation fails.

```json theme={null}
{
  "success": 0,
  "message": "Something went wrong"
}
```