66 lines
2.0 KiB
Markdown
66 lines
2.0 KiB
Markdown
---
|
|
title: 'Test Email'
|
|
template: api-endpoint
|
|
taxonomy:
|
|
category: docs
|
|
api:
|
|
method: POST
|
|
path: /email/test
|
|
description: 'Send a test email to verify that the email plugin is correctly configured. Sends a simple HTML email with a timestamp. Useful for validating SMTP settings, DNS, and deliverability.'
|
|
parameters:
|
|
-
|
|
name: to
|
|
type: string
|
|
required: false
|
|
description: 'Recipient email address. Defaults to the email plugin''s configured "to" address.'
|
|
request_example: "{\n \"to\": \"admin@example.com\"\n}"
|
|
response_example: "{\n \"data\": {\n \"message\": \"Test email sent successfully.\",\n \"to\": \"admin@example.com\"\n }\n}"
|
|
response_codes:
|
|
-
|
|
code: '200'
|
|
description: 'Test email sent successfully'
|
|
-
|
|
code: '401'
|
|
description: 'Unauthorized - missing or invalid API key'
|
|
-
|
|
code: '403'
|
|
description: 'Forbidden - missing api.system.write permission'
|
|
-
|
|
code: '422'
|
|
description: 'No recipient - no "to" provided and no default configured'
|
|
-
|
|
code: '500'
|
|
description: 'Send failed - mailer transport error'
|
|
-
|
|
code: '503'
|
|
description: 'Email plugin not enabled or configured'
|
|
---
|
|
|
|
## Usage Notes
|
|
|
|
### Quick Configuration Check
|
|
|
|
The simplest way to verify your email setup works end-to-end:
|
|
|
|
```bash
|
|
curl -X POST "https://yoursite.com/api/v1/email/test" \
|
|
-H "X-API-Key: grav_your_key" \
|
|
-H "X-Grav-Environment: localhost" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"to": "your@email.com"}'
|
|
```
|
|
|
|
### Default Recipient
|
|
|
|
If you omit the `to` field, the test email is sent to the default recipient configured in the email plugin settings (`plugins.email.to`). If neither is set, the endpoint returns a 422 error.
|
|
|
|
### Test Email Content
|
|
|
|
The test email contains:
|
|
|
|
- **Subject**: "Grav API - Test Email"
|
|
- **Body**: A simple HTML message with the send timestamp
|
|
- **From**: The configured sender address from email plugin settings
|
|
|
|
This is intentionally simple to isolate transport issues from content/template problems.
|