REST API

API Reference

The ArtaMail API is organized around REST. All requests should be made over HTTPS.

Base URL

BASEhttps://artamail.artatol.net/api/v1

Authentication

All API requests require authentication using an API key in the Authorization header.

Terminal
curl -X GET https://artamail.artatol.net/api/v1/templates \
  -H "Authorization: Bearer am_live_sk_your_key_here"

Request Format

  • Use Content-Type: application/json
  • Request bodies should be JSON encoded
  • All timestamps are in ISO 8601 format

Response Format

All responses are JSON. Successful responses return the requested data with appropriate HTTP status codes.

Success Response

json
{
  "id": "email-uuid",
  "status": "queued",
  "queued_at": "2024-01-15T10:30:00Z",
  "test_mode": false
}

Error Response

json
{
  "message": "Invalid email address",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "to",
    "reason": "invalid_format"
  }
}

Status Codes

CodeDescription
200Success
201Created
204No Content (successful deletion)
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Test Mode

Test API Keys
When using test API keys (am_test_sk_*), requests are processed but no side effects occur: emails are not sent, contacts are not persisted, and responses include test_mode: true.

Endpoints

Emails

Send transactional emails, batch emails, get status

Learn more

Contacts

Create contacts, manage list membership, opt-in to subtypes

Learn more

Contact Lists

List segments, static lists, smart list metadata

Learn more

Subscription Types

List types, subtypes, and contact consent preferences

Learn more

Templates

List and retrieve email templates

Learn more

Sender Addresses

List verified sender addresses

Learn more

Domains

List verified domains for sender addresses

Learn more

Preferences Data

Load custom preference UI data by unsubscribe token

Learn more

Rate Limits

API requests are rate limited per organization:

100
requests/second for emails
10
requests/second for batch
1000
max emails per batch

Rate Limit Headers

bash
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800