Send Email

The Artmail API provides two ways to send transactional emails: direct send with raw HTML/text content, or template send using pre-configured transactional templates. Both endpoints support single and batch sending (up to 50 recipients per request).

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer art_live_your_api_key_here

Your API key must have the transactional:send permission. Learn more about authentication →

POST /api/v1/send — Direct Send

Send emails with raw HTML and/or plain text content. Use this when you don't need a template or want full control over the email body.

Request Body

Field	Type	Required	Description
to	string | array	Yes	Recipient(s). String for single, array for batch (max 50 recipients).
from	string	Yes	Sender. Supports "Name <email@domain.com>" or email@domain.com.
subject	string	Yes	Subject line (max 998 characters).
html	string	No*	HTML body. Either html or text is required.
text	string	No*	Plain text body. Either html or text is required.
replyTo	string	No	Reply-to address.
headers	object	No	Custom headers as key-value pairs.
tags	object	No	Custom tags for tracking (e.g. { "campaign": "welcome" }).

Single Recipient Request

Batch Request (up to 50 recipients)

Response — Single Recipient

Response — Batch

The failed array is only present when one or more recipients failed to queue.

---

POST /api/v1/send/[slug] — Template Send

Send emails using a transactional template. Variables are substituted into the template's subject and content.

URL

POST /api/v1/send/welcome-email POST /api/v1/send/order-confirmation

Replace [slug] with your template's slug (from the dashboard).

Request Body

Field	Type	Required	Description
to	string | array	Yes	Recipient(s). String for single, array for batch (max 50).
variables	object	No	Key-value pairs substituted in template ({{ variableName }}).
from	string	No	Override template's sender. Supports "Name <email>" format.
subject	string	No	Override template's subject. Variables supported.
replyTo	string	No	Override template's reply-to.

Example Request

Response

Same format as direct send: { id, status } for single, { ids, status, count, failed? } for batch. Template responses also include "template": "slug".

---

Code Examples

cURL — Direct Send

cURL — Template Send

Node.js — Direct Send

Node.js — Template Send

---

Error Codes

Code	HTTP Status	Description
validation_error	400	Invalid request (missing fields, invalid email, max recipients exceeded).
sender_not_verified	400	Sender email/domain not verified in Settings → Sender Identities.
recipient_suppressed	400	One or more recipients are on your suppression list (unsubscribed/bounced).
template_not_found	404	No template with the given slug, or template is inactive.
missing_variables	400	Template requires variables that were not provided.
template_error	400/500	Template rendering failed (e.g. JSON_BLOCKS not supported).
queue_failed	500	Email could not be queued for sending.

Example Error Response

---

Best Practices

1. Verify sender identity — Add and verify your from address in Settings before sending.
2. Use templates for consistency — Transactional templates ensure brand consistency and faster sends.
3. Include both html and text — Improves deliverability and accessibility.
4. Handle batch failures — Check the failed array when sending to multiple recipients.
5. Use tags — Add tags to segment and filter emails in logs and analytics.

Next Steps