# Mailjet setup (Mpact form reports)

Mpact job form submissions can email a **Technician Service Record** PDF via Mailjet. PDFs are generated in memory on the server and are not stored on disk.

## Environment variables

Set these on the VPS (never commit them to git). Easiest: create a `.env` file in the project folder (see [MAILJET-VPS-SETUP.md](./MAILJET-VPS-SETUP.md) for full SSH steps).

Copy from [`.env.example`](../.env.example):

```env
MAILJET_API_KEY=...
MAILJET_SECRET_KEY=...
MAILJET_FROM_EMAIL=verified@yourdomain.com
MAILJET_FROM_NAME=AnythingIot
```

The API loads `.env` automatically on startup (`dotenv`). Admins can also edit Mailjet values from **Email clients → Mailjet server settings (.env)** without SSH.

You can also set the same variables in the `tank-api` systemd unit.

| Variable | Required | Description |
|----------|----------|-------------|
| `MAILJET_API_KEY` | Yes | Mailjet API key (public) |
| `MAILJET_SECRET_KEY` | Yes | Mailjet secret key |
| `MAILJET_FROM_EMAIL` | Yes | Verified sender address |
| `MAILJET_FROM_NAME` | No | Display name (default: `AnythingIot`) |

Install dependencies (required for PDF + Mailjet; the API will start without them but email will not send):

```bash
npm install
```

Restart the API after changing env vars:

```bash
npm start
```

## Mailjet account checklist

1. Create or sign in to a [Mailjet](https://www.mailjet.com/) account.
2. **API keys**: Account → API keys. Create a key pair and copy into `MAILJET_API_KEY` / `MAILJET_SECRET_KEY`.
3. **Sender verification** (required before mail delivers):
   - **Domain**: Add your domain and complete SPF/DKIM DNS records in Mailjet, **or**
   - **Single address**: Verify one sender email under Senders & domains.
4. Set `MAILJET_FROM_EMAIL` to that verified address (e.g. `reports@yourdomain.com`).
5. Ensure the account is not limited to sandbox-only sending for production use.

## Configure recipients (admin UI)

1. Log in as **admin**.
2. Open **Email clients** (`email-clients.html`).
3. Select the Mpact client (or any client).
4. Set **Recipient email** (comma-separated for multiple).
5. Set **Subject** (default: `AnythingIot Report`).
6. Enable **Mpact job form (PDF)** under Attachments.
7. Save.

Emails are sent on **every** Mpact form submission (including **On hold**).

## Testing

1. Confirm the Email clients page shows “Mailjet is configured on the server.”
2. Submit a test form on the Mpact portal (`mpact.html`).
3. Check the recipient inbox for the PDF attachment.
4. On Email clients, verify **Last send** shows `sent` and a timestamp.
5. In Mailjet: Statistics → check the message was accepted.

If sending fails, the **Last send** column shows `failed` with an error hint. Common causes:

| Error | Fix |
|-------|-----|
| `mailjet_not_configured` | Set all required `MAILJET_*` env vars and restart API |
| `no_recipient` | Add recipient email and save in Email clients |
| `email_disabled` | Enable “Email enabled” for the client |
| Mailjet 401 | Invalid API key/secret |
| Mailjet sender error | `MAILJET_FROM_EMAIL` not verified in Mailjet |

## Event API (optional)

Mailjet’s [Event API](https://dev.mailjet.com/email/guides/#event-api-real-time-notifications) sends webhooks for delivered, opened, bounced, etc. It is **not required** for sending reports. Use it later if you want in-app delivery tracking.

## Database tables

- `mpact_form_email_config` — per-client recipient, subject, attachments, enabled flag
- `email_send_log` — send attempts (`sent`, `failed`, `skipped`) for monitoring in the admin UI