Nhances/nhance-enrollment
Nhances/nhance-enrollment
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dev
nhance-enrollment/docs/reminder-mail-api.md

11 KiB
Raw Permalink Blame History

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
  2. Save / Update Configuration
  3. Send Reminder Mail (Manual)
  4. Frequency Reference
  5. Working Days Reference
  6. 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

GET /employeeRest/getReminderMailConfig?client_policy_id=123

Success Response — Config Exists

{
  "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)

{
  "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

{
  "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

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

{
  "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)
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)

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

Sample Payload — Insert (Working Days — weekdays only)

{
  "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)

{
  "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:

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

Sample Payload — Insert (Weekly)

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

Sample Payload — Insert (Monthly)

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

Sample Payload — Insert (Custom)

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

Sample Payload — Update

{
  "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

{
  "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

{
  "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

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

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

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

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

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

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

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

{
  "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)

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

{
  "client_policy_id": 123
}

Sample Request (GET)

GET /employeeRest/sendReminderMail?client_policy_id=123

Success Response

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

Error Responses

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

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

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

{
  "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