# Contact Us API Documentation

Public endpoint for the **Contact Us** form. Each submission is saved to the database and emailed to the site's contact inbox. The email's **Reply-To** is set to the sender, so admins can reply straight from their mail client.

- **Base URL:** `http://localhost:8000/api`
- **Auth:** none (public)
- **Headers:** `Accept: application/json`, `Content-Type: application/json`
- **Rate limit:** 5 requests per minute per IP. Further requests get `429`.

## Endpoint

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/contact` | Submit a contact message |

## Request Body

| Field | Type | Rules |
|-------|------|-------|
| `name` | string | required, max 255 |
| `email` | string | required, valid email, max 255 |
| `subject` | string | required, max 255 |
| `message` | string | required, max 5000 |

```json
{
  "name": "Rahim Uddin",
  "email": "rahim@example.com",
  "subject": "Payment question",
  "message": "My payment went through but I cannot see my prompts."
}
```

## Responses

**201 Created**
```json
{
  "success": true,
  "message": "Thank you for contacting us. We will get back to you soon.",
  "data": {
    "id": 1,
    "name": "Rahim Uddin",
    "email": "rahim@example.com",
    "subject": "Payment question",
    "message": "My payment went through but I cannot see my prompts.",
    "created_at": "2026-10-17T07:01:10+00:00"
  }
}
```

**422 Unprocessable Content**: validation failed
```json
{
  "message": "The name field is required. (and 3 more errors)",
  "errors": {
    "name": ["The name field is required."],
    "email": ["The email field must be a valid email address."],
    "subject": ["The subject field is required."],
    "message": ["The message field is required."]
  }
}
```

**429 Too Many Requests**: more than 5 submissions in a minute
```json
{ "message": "Too Many Attempts." }
```

## Frontend Usage

- On `201`, show the response's `message` and clear the form.
- On `422`, show each `errors[field][0]` under its input.
- On `429`, ask the user to wait a minute before trying again.

```ts
type ContactRequest = {
  name: string;
  email: string;
  subject: string;
  message: string;
};

type ContactResponse = {
  success: true;
  message: string;
  data: ContactRequest & { id: number; created_at: string };
};
```

## cURL

```bash
curl -X POST http://localhost:8000/api/contact \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Rahim Uddin","email":"rahim@example.com","subject":"Payment question","message":"My payment went through but I cannot see my prompts."}'
```

## Email

- Sent to `MAIL_CONTACT_ADDRESS`. If that isn't set, it goes to `MAIL_FROM_ADDRESS`.
- Subject: `New contact message: {subject}`. Reply-To: the sender's name and email.
- With `MAIL_MAILER=log` (local default) the email is written to `storage/logs/laravel.log` instead of being sent.

```dotenv
MAIL_CONTACT_ADDRESS="support@aipathshala.com"
```

## Database

Table `contact_messages`: `name`, `email`, `subject`, `message` (text), `ip_address` (nullable), `read_at` (nullable, set when an admin opens the message), timestamps.

## Viewing Messages (Admin)

Admins read submissions in the dashboard under **Contact messages** (`http://localhost:8000/contact-messages`). The sidebar link shows the number of unread messages.

- **List:** sender, subject, a preview of the message and when it was received. Unread messages are shown in bold with a dot.
- **Search / filter:** search by name, email, subject or message text, and filter by read or unread.
- **View:** click a message to open it in full. Opening it marks it as read. **Reply by email** opens your mail app with the subject `Re: {subject}`.
- **Read status:** mark a single message as read or unread, or use **Mark all as read**.
- **Delete:** asks for confirmation.

## Code

- Model: `app/Models/ContactMessage.php` (`unread()` scope, `isRead()`)
- Migrations: `database/migrations/2026_10_17_070027_create_contact_messages_table.php`, `database/migrations/2026_10_17_070408_add_read_at_to_contact_messages_table.php`
- Admin page: `resources/views/pages/contact-messages/⚡index.blade.php`
- Controller: `app/Http/Controllers/Api/ContactController.php`
- Notification: `app/Notifications/ContactMessageNotification.php`
- Config: `config/mail.php` (`contact_address`)
- Routes: `routes/api.php`, `routes/web.php` · Tests: `tests/Feature/ContactApiTest.php`, `tests/Feature/ContactMessageManagementTest.php`