API Reference

Contacts API

Endpoints for managing email contacts.

POST/api/v1/contacts

Create a new contact or update an existing one (upsert by email).

Request Body

Field	Type	Required	Description
`email`	string	Yes	Contact email address
`name`	string	No	Contact name
`data`	object	No	Custom data fields
`lists`	string[]	No	List slugs to add contact to

Example Request

Terminal

curl -X POST https://artamail.artatol.com/api/v1/contacts \
  -H "Authorization: Bearer am_live_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "data": { "company": "Acme Inc", "plan": "premium" },
    "lists": ["newsletter", "updates"]
  }'

Response

json

{
  "id": "contact-uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "data": { "company": "Acme Inc", "plan": "premium" },
  "subscribed": true,
  "validation_status": "pending",
  "lists": ["newsletter", "updates"],
  "created_at": "2024-01-15T10:30:00Z",
  "test_mode": false
}

GET/api/v1/contacts/:email

Retrieve a contact by email address.

Example Request

Terminal

curl https://artamail.artatol.com/api/v1/contacts/user%40example.com \
  -H "Authorization: Bearer am_live_sk_xxx"

Response

json

{
  "id": "contact-uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "data": { "company": "Acme Inc", "plan": "premium" },
  "subscribed": true,
  "validation_status": "valid",
  "lists": ["newsletter", "updates"],
  "created_at": "2024-01-15T10:30:00Z"
}

Returns 404 if contact not found.

PATCH/api/v1/contacts/:email

Update an existing contact.

Request Body

Field	Type	Description
`name`	string	Contact name
`data`	object	Custom data fields (merged with existing)
`lists`	string[]	Replace list memberships
`subscribed`	boolean	Subscription status

Example Request

Terminal

curl -X PATCH https://artamail.artatol.com/api/v1/contacts/user%40example.com \
  -H "Authorization: Bearer am_live_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "data": { "plan": "enterprise" } }'

DELETE/api/v1/contacts/:email

Soft delete a contact. The contact can be restored by creating it again.

Example Request

Terminal

curl -X DELETE https://artamail.artatol.com/api/v1/contacts/user%40example.com \
  -H "Authorization: Bearer am_live_sk_xxx"

Returns 204 No Content on success.

Validation Statuses

Contacts are automatically validated after creation:

Status	Description
`pending`	Awaiting validation
`valid`	Email address is valid
`invalid`	Email address is invalid (bounced, bad syntax, etc.)

Test Mode

With test API keys, contacts are not persisted. GET/PATCH/DELETE will return 404, and POST will return a simulated response with test_mode: true.