The contacts endpoints let you identify recipients by email or userId, manage lightweight audience metadata, and check suppression state.

​
Common patterns

  • POST /v1/contacts/create requires email.
  • PUT /v1/contacts/update accepts either email or userId.
  • GET /v1/contacts/find can query by email, userId, or both.
  • POST /v1/contacts/delete deletes by email or userId.
  • Suppression endpoints work by email.

​
Create a contact

curl -X POST https://api.mailkatana.com/v1/contacts/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "avery@example.com",
    "firstName": "Avery",
    "lastName": "Stone",
    "source": "signup-form",
    "userId": "usr_123",
    "mailingLists": {
      "list_public_id": true
    },
    "properties": {
      "plan": "pro"
    }
  }'

​
Find a contact

curl "https://api.mailkatana.com/v1/contacts/find?email=avery@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Suppression workflow

  • GET /v1/contacts/suppression-status returns 200 for both known and unknown emails to avoid enumeration.
  • DELETE /v1/contacts/suppression removes an existing suppression by email.
Use the generated reference pages for full request and response schemas.