intotheeast-com-content/plugins/email/api-docs/01.send/api-endpoint.md

title, template, taxonomy, api

title	template	taxonomy	api
Send Email	api-endpoint	category docs	method path description parameters request_example response_example response_codes POST /email/send Send an ad-hoc email. Uses the email plugin's configured mailer transport (SMTP, Sendmail, etc). The "from" address defaults to the plugin's configured sender if not specified. name type required description to string true Recipient email address. Supports: "user@example.com", "Name <user@example.com>", or comma-separated for multiple recipients. name type required description subject string true Email subject line. name type required description body string true Email body content. Interpreted as HTML by default (see content_type). name type required description from string false Sender email address. Defaults to the email plugin's configured "from" address. name type required description cc string false CC recipient(s). Same format as "to". name type required description bcc string false BCC recipient(s). Same format as "to". name type required description reply_to string false Reply-To address. name type required description content_type string false Content type: "text/html" (default) or "text/plain". { "to": "recipient@example.com", "subject": "Hello from Grav API", "body": "<h1>Hello</h1><p>This email was sent via the Grav API.</p>", "from": "sender@example.com", "cc": "copy@example.com", "content_type": "text/html" } { "data": { "message": "Email sent successfully.", "to": "recipient@example.com", "subject": "Hello from Grav API" } } code description 200 Email sent successfully code description 401 Unauthorized - missing or invalid API key code description 403 Forbidden - missing api.system.write permission code description 422 Validation error - missing required fields (to, subject, body) code description 500 Send failed - mailer transport error code description 503 Email plugin not enabled or configured

Usage Notes

Required Headers

X-API-Key: grav_your_api_key
X-Grav-Environment: localhost
Content-Type: application/json

Multiple Recipients

Send to multiple recipients by comma-separating addresses:

{
    "to": "user1@example.com, user2@example.com",
    "subject": "Team Update",
    "body": "<p>Hello team!</p>"
}

Or use named addresses:

{
    "to": "Alice <alice@example.com>, Bob <bob@example.com>"
}

Plain Text Emails

Set content_type to send plain text instead of HTML:

{
    "to": "user@example.com",
    "subject": "Plain text message",
    "body": "This is a plain text email.\n\nNo HTML formatting.",
    "content_type": "text/plain"
}

Example with cURL

curl -X POST "https://yoursite.com/api/v1/email/send" \
  -H "X-API-Key: grav_your_key" \
  -H "X-Grav-Environment: localhost" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from Grav",
    "body": "<h1>Hello</h1><p>Sent via the API</p>"
  }'

Error Handling

If the email transport fails (e.g., SMTP connection error), the API returns a 500 error with details:

{
    "status": 500,
    "title": "Internal Server Error",
    "detail": "Failed to send email: Connection to smtp.example.com:587 timed out"
}