# How to run the Email to Ticket API

## 1. Use the right file in Postman

- **Do not** use the old reference JSON (the one with `_comment`, `variables`, `endpoints`). That format cannot be imported.
- **Do** import one of these (they are valid Postman collections):
  - `docs/Email_To_Ticket_API_Collection.json`
  - `docs/Email_To_Ticket_API.postman_collection.json`

In Postman: **Import** → **Upload Files** → select the file above.

---

## 2. Set collection variables

After importing, open the collection → **Variables** and set:

| Variable | Example | When |
|----------|---------|------|
| **web_url** | `https://your-domain.com/api/v1/web` | Your backend base URL (must match server). |
| **auth_token** | (paste token after login) | For GET/PUT/POST/DELETE setup endpoints. |
| **support_email_id** | `1` | For Update/Delete/Toggle email requests. |
| **email_to_ticket_secret** | e.g. `roms-email-to-ticket-8f3a2b1c4d5e6f7a9b0c1d2e3f4a5b6c` (same as `EMAIL_TO_TICKET_PROCESS_SECRET` in `.env`) | For **Process Incoming Email** only. |

---

## 3. Backend requirements

1. **`.env`** must have:
   ```env
   # Example – use your own long random string in production
   EMAIL_TO_TICKET_PROCESS_SECRET=roms-email-to-ticket-8f3a2b1c4d5e6f7a9b0c1d2e3f4a5b6c
   ```
   **Where does the secret come from?** The application does **not** generate it. You (the developer/admin) create it yourself:
   - Either choose a long random string (e.g. `roms-email-to-ticket-8f3a2b1c4d5e6f7a9b0c1d2e3f4a5b6c`),
   - Or generate one: run `openssl rand -hex 32` in terminal and use the output.
   Then put that value in `.env` as `EMAIL_TO_TICKET_PROCESS_SECRET`, and in Postman / Email Listener with the same value.

   **Example values (change in production):**
   - `roms-email-to-ticket-8f3a2b1c4d5e6f7a9b0c1d2e3f4a5b6c`
   - `MySecureSecretKey_ChangeInProduction_2024`
   - Or: `openssl rand -hex 32` → use the printed string

   Use the **exact same value** in Postman variable `email_to_ticket_secret` and in the header `X-Email-To-Ticket-Secret` for the Process Incoming request.

2. **Process Incoming Email** (first request):
   - Auth: **no Bearer**. Only header: `X-Email-To-Ticket-Secret: <same as env>`.
   - If you get **403** or “Incorrect format”: the secret is missing or wrong, or not set in `.env`.

3. **All other requests** (GET Page Data, Save Settings, Add/Update/Delete Email, Toggle):
   - Auth: **Bearer token**.
   - First call **Login** (e.g. your main API login), copy the token, and set collection variable `auth_token`.
   - User must have permission `setup-email-to-ticket`.

---

## 4. Correct URLs

Base URL is **`{{web_url}}`** = `https://your-domain.com/api/v1/web`. So:

- Process Incoming: `POST {{web_url}}/email-to-ticket/process-incoming`
- Page Data: `GET {{web_url}}/email-to-ticket`
- Settings: `PUT {{web_url}}/email-to-ticket/settings`
- Emails: `POST {{web_url}}/email-to-ticket/emails` and similar with `{{support_email_id}}`

Ensure there is no double `web` in the path (e.g. `.../web/web/email-to-ticket/...`).

---

## 5. "This action is unauthorized" (Process Incoming)

This means the **secret check failed**:

1. **Add to `.env`** (if missing):
   ```env
   EMAIL_TO_TICKET_PROCESS_SECRET=roms-email-to-ticket-8f3a2b1c4d5e6f7a9b0c1d2e3f4a5b6c
   ```
   (Use your own value; this is an example.)

2. **Restart the app** after changing `.env` (e.g. `php artisan config:clear` or restart PHP-FPM).

3. **In Postman**: set collection variable **`email_to_ticket_secret`** to the **exact same** value as in `.env`. The request sends it in the header `X-Email-To-Ticket-Secret`. No spaces, same case.

4. The API response body will now indicate whether the secret is "not configured" (missing in .env) or "Invalid or missing" (header wrong or not sent).

---

## 6. Quick checklist if “not working”

- [ ] Imported **Email_To_Ticket_API_Collection.json** or **Email_To_Ticket_API.postman_collection.json** (not the old reference JSON).
- [ ] **web_url** = your real backend URL (e.g. `https://sys.roms.roqay.dev/api/v1/web`).
- [ ] For **Process Incoming**: `EMAIL_TO_TICKET_PROCESS_SECRET` set in `.env` and **email_to_ticket_secret** = same value in Postman; header `X-Email-To-Ticket-Secret` present; **no** Bearer token.
- [ ] For **other endpoints**: logged in, token copied into **auth_token**; user has `setup-email-to-ticket`.
- [ ] Backend is running and reachable at **web_url**.