API Reference

Emails API

Endpoints for sending transactional emails.

POST/api/v1/emails/send

Send a single transactional email using a template.

Request Body

Field	Type	Required	Description
`to`	string	Yes	Recipient email address
`template`	string	Yes	Template slug
`data`	object	No	Template variables
`from`	string	No	Custom sender email (must be verified)
`from_name`	string	No	Sender display name
`reply_to`	string	No	Reply-to address
`priority`	string	No	high, normal, low (default: normal)
`subtype_slug`	string	No	Operational subtype slug — enforces consent before send (marketing uses campaigns)

Example Request

Terminal

curl -X POST https://artamail.artatol.net/api/v1/emails/send \
  -H "Authorization: Bearer am_live_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "template": "welcome",
    "data": {
      "name": "John",
      "verifyUrl": "https://example.com/verify/abc123"
    }
  }'

Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "queued_at": "2024-01-15T10:30:00Z",
  "test_mode": false
}

Auto-injected identity variables

ArtaMail fills brand, legal_entity, legal_address, and legal_details from Settings → Brand & compliance when omitted in data. Pass values only to override. See Multiple Products and Templates.

Legacy: company

The company field is a legacy alias for brand. It is still auto-injected today but may be removed in a future release — omit it and configure brand in Settings instead.

Subtype consent

For operational subtypes, pass subtype_slug to require confirmed opt-in. See Subscriptions & Consent.

POST/api/v1/emails/batch

Send multiple emails in a single request (max 1000 per batch).

Request Body

Field	Type	Required	Description
`emails`	array	Yes	Array of email objects (same fields as send)

Example Request

Terminal

curl -X POST https://artamail.artatol.net/api/v1/emails/batch \
  -H "Authorization: Bearer am_live_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      { "to": "[email protected]", "template": "notification", "data": { "message": "Hello" } },
      { "to": "[email protected]", "template": "notification", "data": { "message": "Hello" } }
    ]
  }'

Response

json

{
  "queued": 2,
  "failed": 0,
  "results": [
    { "to": "[email protected]", "id": "email-id-1" },
    { "to": "[email protected]", "id": "email-id-2" }
  ],
  "test_mode": false
}

GET/api/v1/emails/:id

Retrieve status and details of a sent email.

Example Request

Terminal

curl https://artamail.artatol.net/api/v1/emails/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer am_live_sk_xxx"

Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "to_email": "[email protected]",
  "subject": "Welcome to Our App",
  "status": "delivered",
  "template_slug": "welcome",
  "sent_at": "2024-01-15T10:30:05Z",
  "delivered_at": "2024-01-15T10:30:10Z",
  "opened_at": "2024-01-15T11:00:00Z",
  "clicked_at": null
}

Email Statuses

Status	Description
`queued`	Email is queued for sending
`sending`	Email is being sent
`sent`	Email was sent to the mail server
`delivered`	Email was delivered to recipient
`bounced`	Email bounced (hard or soft)
`complained`	Recipient marked as spam
`failed`	Email failed to send