nhance-enrollment/docs/reminder-mail-api.md

# Reminder Mail API Documentation

Base path for all endpoints: `/employeeRest`

**Authentication:** JWT + app signature (same filters as other `employeeRest` routes)

**Content types:** JSON body or form-urlencoded (where noted)

**HTTP status:** All responses return HTTP `200`. Check the JSON `status` and `code` fields for success or failure.

---

## Table of Contents

1. [Get Configuration](#1-get-configuration)
2. [Save / Update Configuration](#2-save--update-configuration)
3. [Send Reminder Mail (Manual)](#3-send-reminder-mail-manual)
4. [Frequency Reference](#frequency-reference)
5. [Working Days Reference](#working-days-reference)
6. [Quick Reference](#quick-reference)

---

## 1. Get Configuration

Fetch reminder mail configuration for a client policy.

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `/employeeRest/getReminderMailConfig` |

### Request Parameters

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `client_policy_id` | Yes | integer | Client policy ID |

### Sample Request

```http
GET /employeeRest/getReminderMailConfig?client_policy_id=123
```

### Success Response — Config Exists

```json
{
  "status": true,
  "code": 200,
  "data": {
    "id": 10,
    "client_policy_id": 123,
    "frequency": "working_days",
    "reminder_days": "1,3,5",
    "working_day_labels": ["Mon", "Wed", "Fri"],
    "is_enabled": 1,
    "is_active": 1,
    "created_by": 45,
    "updated_by": 45,
    "created_at": "2026-06-23 10:00:00",
    "updated_at": "2026-06-23 11:30:00"
  },
  "working_day_options": [
    { "value": 1, "label": "Mon", "key": "mon" },
    { "value": 2, "label": "Tue", "key": "tue" },
    { "value": 3, "label": "Wed", "key": "wed" },
    { "value": 4, "label": "Thu", "key": "thu" },
    { "value": 5, "label": "Fri", "key": "fri" },
    { "value": 6, "label": "Sat", "key": "sat" },
    { "value": 7, "label": "Sun", "key": "sun" }
  ]
}
```

### Success Response — Legacy Fallback (no config row, legacy `reminder_date` on policy)

```json
{
  "status": true,
  "code": 200,
  "data": {
    "client_policy_id": 123,
    "frequency": "custom",
    "reminder_days": "1,15,28",
    "is_enabled": 1,
    "is_active": 1,
    "source": "legacy_client_policy"
  },
  "working_day_options": [
    { "value": 1, "label": "Mon", "key": "mon" },
    { "value": 2, "label": "Tue", "key": "tue" },
    { "value": 3, "label": "Wed", "key": "wed" },
    { "value": 4, "label": "Thu", "key": "thu" },
    { "value": 5, "label": "Fri", "key": "fri" },
    { "value": 6, "label": "Sat", "key": "sat" },
    { "value": 7, "label": "Sun", "key": "sun" }
  ]
}
```

### Success Response — No Config

```json
{
  "status": true,
  "code": 200,
  "data": null,
  "working_day_options": [
    { "value": 1, "label": "Mon", "key": "mon" },
    { "value": 2, "label": "Tue", "key": "tue" },
    { "value": 3, "label": "Wed", "key": "wed" },
    { "value": 4, "label": "Thu", "key": "thu" },
    { "value": 5, "label": "Fri", "key": "fri" },
    { "value": 6, "label": "Sat", "key": "sat" },
    { "value": 7, "label": "Sun", "key": "sun" }
  ]
}
```

### Error Responses

```json
{
  "status": false,
  "code": 400,
  "message": "client_policy_id is required"
}
```

```json
{
  "status": false,
  "code": 404,
  "message": "Client policy not found"
}
```

---

## 2. Save / Update Configuration

Create or update reminder mail configuration.

| | |
|---|---|
| **Method** | `POST` |
| **URL** | `/employeeRest/saveReminderMailConfig` |

### Insert vs Update

| Condition | Action |
|-----------|--------|
| `id` **not** sent | **Insert** new record |
| `id` **sent** | **Update** existing record by primary key |

### Request Parameters

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `client_policy_id` | Yes | integer | Client policy ID |
| `frequency` | Yes | string | `daily`, `weekly`, `monthly`, `custom`, `working_days` |
| `reminder_days` | Depends | string | Comma-separated days (see [Frequency Reference](#frequency-reference)) |
| `working_days` | No | string | Alias for `reminder_days` when `frequency` is `working_days` |
| `is_enabled` | No | integer | `1` (enabled) or `0` (disabled). Default: `1` |
| `hr_id` | No | integer | Stored as `created_by` / `updated_by`. Null if omitted |
| `id` | No | integer | Primary key — required for update |

### Sample Payload — Insert (Daily)

```json
{
  "client_policy_id": 123,
  "frequency": "daily",
  "is_enabled": 1,
  "hr_id": 45
}
```

### Sample Payload — Insert (Working Days — weekdays only)

```json
{
  "client_policy_id": 123,
  "frequency": "working_days",
  "reminder_days": "Mon,Wed,Fri",
  "is_enabled": 1,
  "hr_id": 45
}
```

### Sample Payload — Insert (Working Days — including Sat/Sun)

```json
{
  "client_policy_id": 123,
  "frequency": "working_days",
  "reminder_days": "Mon,Wed,Fri,Sat,Sun",
  "is_enabled": 1,
  "hr_id": 45
}
```

Or numeric: `"1,3,5,6,7"` (Sat=6, Sun=7; `0` is also accepted for Sunday).

Alternative using `working_days` alias:

```json
{
  "client_policy_id": 123,
  "frequency": "working_days",
  "working_days": "Mon,Tue,Thu",
  "hr_id": 45
}
```

### Sample Payload — Insert (Weekly)

```json
{
  "client_policy_id": 123,
  "frequency": "weekly",
  "reminder_days": "1,3,5",
  "hr_id": 45
}
```

### Sample Payload — Insert (Monthly)

```json
{
  "client_policy_id": 123,
  "frequency": "monthly",
  "reminder_days": "1,15",
  "hr_id": 45
}
```

### Sample Payload — Insert (Custom)

```json
{
  "client_policy_id": 123,
  "frequency": "custom",
  "reminder_days": "5,10,20",
  "hr_id": 45
}
```

### Sample Payload — Update

```json
{
  "id": 10,
  "client_policy_id": 123,
  "frequency": "working_days",
  "reminder_days": "Mon,Tue,Wed,Thu,Fri",
  "is_enabled": 1,
  "hr_id": 45
}
```

### Success Response — Created

```json
{
  "status": true,
  "code": 200,
  "action": "created",
  "message": "Reminder mail configuration saved successfully",
  "data": {
    "id": 10,
    "client_policy_id": 123,
    "frequency": "working_days",
    "reminder_days": "1,3,5",
    "working_day_labels": ["Mon", "Wed", "Fri"],
    "is_enabled": 1,
    "is_active": 1,
    "created_by": 45,
    "updated_by": 45,
    "created_at": "2026-06-23 10:00:00",
    "updated_at": "2026-06-23 10:00:00"
  }
}
```

### Success Response — Updated

```json
{
  "status": true,
  "code": 200,
  "action": "updated",
  "message": "Reminder mail configuration saved successfully",
  "data": {
    "id": 10,
    "client_policy_id": 123,
    "frequency": "working_days",
    "reminder_days": "1,2,3,4,5",
    "working_day_labels": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "is_enabled": 1,
    "is_active": 1,
    "created_by": 45,
    "updated_by": 45,
    "created_at": "2026-06-23 10:00:00",
    "updated_at": "2026-06-23 12:00:00"
  }
}
```

### Error Responses

```json
{
  "status": false,
  "code": 400,
  "message": "client_policy_id is required"
}
```

```json
{
  "status": false,
  "code": 400,
  "message": "frequency is required"
}
```

```json
{
  "status": false,
  "code": 404,
  "message": "Client policy not found"
}
```

```json
{
  "status": false,
  "code": 400,
  "message": "Reminder mail configuration not found"
}
```

```json
{
  "status": false,
  "code": 400,
  "message": "client_policy_id does not match the configuration record"
}
```

```json
{
  "status": false,
  "code": 400,
  "message": "Invalid frequency. Allowed values: daily, weekly, monthly, custom, working_days."
}
```

```json
{
  "status": false,
  "code": 400,
  "message": "reminder_days is required. Use Mon-Sun or 1-7 (0 also accepted for Sunday)."
}
```

```json
{
  "status": false,
  "code": 400,
  "message": "Working day reminder_days must be between 1 (Mon) and 7 (Sun)."
}
```

### Audit Fields (`hr_id`)

| Action | `created_by` | `updated_by` |
|--------|--------------|--------------|
| Insert + `hr_id` sent | `hr_id` | `hr_id` |
| Insert + `hr_id` omitted | `null` | `null` |
| Update + `hr_id` sent | unchanged | `hr_id` |
| Update + `hr_id` omitted | unchanged | `null` |

---

## 3. Send Reminder Mail (Manual)

Manually trigger reminder mail for a policy. Sends immediately regardless of schedule configuration.

| | |
|---|---|
| **Method** | `GET` or `POST` |
| **URL** | `/employeeRest/sendReminderMail` |

### Request Parameters

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `client_policy_id` | Yes | integer | Client policy ID |

### Sample Request (POST)

```http
POST /employeeRest/sendReminderMail
Content-Type: application/json

{
  "client_policy_id": 123
}
```

### Sample Request (GET)

```http
GET /employeeRest/sendReminderMail?client_policy_id=123
```

### Success Response

```json
{
  "status": true,
  "code": 200,
  "message": "Mail sent successfully"
}
```

### Error Responses

```json
{
  "status": false,
  "code": 400,
  "message": "client_policy_id is required"
}
```

```json
{
  "status": false,
  "code": 404,
  "message": "Client policy not found"
}
```

```json
{
  "status": false,
  "code": 200,
  "message": "There is no data to send",
  "message2": "Failed"
}
```

```json
{
  "status": false,
  "code": 200,
  "message": "There is no data to send",
  "message2": "No policy data found to send"
}
```

---

## Frequency Reference

| `frequency` | `reminder_days` required? | Format | Example |
|-------------|---------------------------|--------|---------|
| `daily` | No | — | — |
| `weekly` | Yes | Weekday `0–6` (Sun–Sat) | `"1,3,5"` |
| `monthly` | Yes | Day of month `1–31` | `"1,15,28"` |
| `custom` | Yes | Day of month `1–31` | `"5,10,20"` |
| `working_days` | Yes | Weekday `1–7` (Mon–Sun) or day names | `"Mon,Wed,Fri,Sat"` or `"1,3,5,6"` |

---

## Working Days Reference

Used when `frequency = working_days`. Select any combination of weekdays including Saturday and Sunday.

| Label | Numeric Value |
|-------|---------------|
| Mon | 1 |
| Tue | 2 |
| Wed | 3 |
| Thu | 4 |
| Fri | 5 |
| Sat | 6 |
| Sun | 7 |

Accepted input formats:

- Day names: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun` (case-insensitive)
- Numeric: `1`–`7` (ISO-8601, matches PHP `date('N')`)
- Sunday alias: `0` is normalized to `7`
- Comma-separated combinations: `"Mon,Wed,Sat"` or `"1,3,6"`

Stored in DB as normalized numeric string (e.g. `"1,3,6,7"`).

---

## Quick Reference

| API | Method | Purpose |
|-----|--------|---------|
| `/employeeRest/getReminderMailConfig` | GET | Fetch config by `client_policy_id` |
| `/employeeRest/saveReminderMailConfig` | POST | Create (no `id`) or update (with `id`) |
| `/employeeRest/sendReminderMail` | GET / POST | Manually send reminder mail |

---

## Notes

1. **Scheduled sends (cron)** use the saved configuration from the `reminder_mail_config` table.
2. **Manual send** via `/sendReminderMail` ignores the schedule and sends immediately.
3. **`working_day_options`** is returned on every get-config response for UI dropdown/checkbox rendering.
4. **Legacy policies** without a config row may still expose `client_policy.reminder_date` as `frequency: custom` with `source: legacy_client_policy`.

---

## Database

Configuration is stored in the `reminder_mail_config` table.

| Column | Description |
|--------|-------------|
| `id` | Primary key |
| `client_policy_id` | Unique per policy |
| `frequency` | Schedule type |
| `reminder_days` | Comma-separated day values |
| `is_enabled` | Enable/disable reminders |
| `created_by` / `updated_by` | Set from `hr_id` in API payload |
| `created_at` / `updated_at` | Timestamps |

SQL migration:

- `app/Database/reminder_mail_config.sql`