Events & Jobs walkthrough

This guide takes you from a single HTTP request to a real HTML email in your inbox. It exercises every layer of the event / job pipeline in the starter — event dispatcher, listener chain, job dispatcher, sync driver, and libcurl SMTP transport.

The full flow

GET /api/events/user-registered?email=...&name=...&id=...
  → EventDispatcher::fire(AppEvents::UserRegistered)
      → LogRegistrationListener::handle()      (writes a log line)
      → SendWelcomeEmailListener::handle()
           → JobDispatcher::dispatch(SendTestMail)
                → SyncDriver (inline in this HTTP thread)
                     → SendTestMail::handle()  (libcurl SMTP send)

Nothing is queued to a background worker in Phase A — every step runs in the request thread and the HTTP response only returns once the mail has been handed off to the SMTP server. That means: if you get an HTTP 200, the mail was accepted by the mail server; if the mail was rejected, the request finishes with the error visible in the server log.

Trigger with curl

With ./bin/app.bin running and MAIL_* configured (see Mail (SMTP)):

curl "http://localhost:9090/api/events/user-registered?email=you@x.com&name=You&id=1"

Expected response:

{
  "status": "fired",
  "event": "UserRegistered",
  "listeners": 2,
  "payload": {"user_id": 1, "email": "you@x.com", "name": "You"}
}

Reading the server log

In the terminal where ./bin/app.bin runs you should see, in order:

[LogRegistrationListener] user #1 You <you@x.com> registered
[SendTestMail] dispatch driver=smtp host=smtp.example.com:465 enc=tls from=<...> -> to=<you@x.com> subject="Welcome ..." body_len=...
[SendTestMail] SMTP send OK via smtps://smtp.example.com:465 -> <you@x.com>
(YYYY-MM-DD HH:MM:SS) [INFO    ] Response: ... /api/events/user-registered?... 200 0

If you see SMTP send FAILED instead, the last line contains the libcurl error string — that is the actionable message.

Troubleshooting

• 404 HTML instead of JSON — the running binary does not have the routes registered. Rebuild with ./make.sh and restart.
• 404 JSON "no factory for '...'" — the job or event name in the URL / payload does not match any registered entry. Use ./kalpasan job:list and ./kalpasan event:list to see what is bound; check app/providers/JobServiceProvider.cpp and EventServiceProvider.cpp.
• SMTP send OK but no mail in inbox — check spam folder first. If empty, flip CURLOPT_VERBOSE=1L in app/jobs/SendTestMail.cpp, rebuild, retry and read the full SMTP dialog (details).
• Silent hang — the SMTP server is probably not answering. Try openssl s_client -connect <host>:465 from the same box; if it fails, network / firewall.
• SPF / DKIM issues — first-time mail from a fresh domain to gmail.com, abv.bg, etc. is commonly filtered into spam. Configure SPF / DKIM / DMARC for your domain.