Add Contact

Create a new contact in your Sendmator account. Contacts represent people or entities you want to communicate with via email, SMS, or WhatsApp.

Recommended: Use Publishable Keys

For contact management operations, we recommend using publishable keys instead of secret API keys. Publishable keys have limited permissions and can safely be used in client-side applications.

Endpoint

POST /api/v1/contacts

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json
X-Team-ID: your_team_id

Understanding external_id - IMPORTANT

The external_id field is how you map Sendmator contacts to your system's users/accounts.

Why use external_id?

Sendmator is designed to integrate with your existing application. The external_id field allows you to:

• 🔗 Link contacts to your database - Store your user ID, account ID, or customer ID
• 🔍 Find contacts easily - Query contacts using your own ID scheme
• 🔄 Sync data - Keep Sendmator contacts in sync with your system
• 📊 Track across systems - Maintain consistent identity across platforms

Best Practice: Always Provide external_id

{
  "external_id": "YOUR_USER_ID_123",  // ✅ RECOMMENDED
  "email": "user@example.com"
}

Why this matters:

• Your app has User ID 12345 with email user@example.com
• You create Sendmator contact with external_id: "12345"
• Later, you can reference this contact using your User ID 12345
• No need to store or track Sendmator's internal contact ID

Identity Model

Your System          →    Sendmator
User ID: 12345       →    external_id: "12345" (unique within your team)
Account Email        →    email: "user@example.com"
Phone Number         →    custom_fields: { phone: "+1234567890" }

Behavior

When external_id is provided:

• ✅ Must be unique within your team
• ❌ Duplicate external_id → Returns 409 Conflict
• ✅ You control the ID format (string, number, UUID, etc.)

When external_id is NOT provided:

• 🔄 System auto-generates a UUID
• ⚠️ Not recommended - You lose the ability to easily reference your users

Request Parameters

Required Fields

Field	Type	Description
email	string	Valid email address

Optional Fields

Field	Type	Default	Description
external_id	string	auto-generated UUID	Your system's unique ID
first_name	string	null	Contact's first name
last_name	string	null	Contact's last name
tags	array of strings	[]	Tags for categorization/filtering
is_active	boolean	true	Whether contact is active
custom_fields	object		Additional structured data
metadata	object		System/tracking information

Complete Example Request

curl -X POST https://api.sendmator.com/api/v1/contacts \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CRM-001",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "tags": ["customer", "vip", "premium"],
    "is_active": true,
    "custom_fields": {
      "company": "Acme Corp",
      "department": "Engineering",
      "phone": "+1-555-0123",
      "job_title": "Senior Developer",
      "annual_revenue": 150000,
      "lead_score": 85,
      "preferred_language": "en"
    },
    "metadata": {
      "source": "website",
      "campaign": "newsletter",
      "signup_date": "2024-01-15",
      "utm_source": "google",
      "utm_medium": "cpc",
      "referrer": "https://google.com",
      "ip_address": "192.168.1.1",
      "browser": "Chrome",
      "notes": "Interested in enterprise plan"
    }
  }'

Custom Fields Examples

The custom_fields object accepts any structured data relevant to your business:

{
  "custom_fields": {
    "company": "Acme Corp",
    "department": "Engineering",
    "phone": "+1-555-0123",
    "job_title": "Senior Developer",
    "annual_revenue": 150000,
    "lead_score": 85,
    "preferred_language": "en",
    "subscription_tier": "premium",
    "last_login": "2024-01-14T15:30:00Z",
    "account_manager": "jane.smith@yourcompany.com"
  }
}

Metadata Examples

The metadata object is perfect for tracking and analytics data:

{
  "metadata": {
    "source": "website",
    "campaign": "newsletter",
    "signup_date": "2024-01-15",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "winter_sale",
    "referrer": "https://google.com",
    "ip_address": "192.168.1.1",
    "browser": "Chrome",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "notes": "Interested in enterprise plan",
    "lead_source": "paid_search"
  }
}

Responses

Success Response (201 Created)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "external_id": "CRM-001",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "tags": ["customer", "vip", "premium"],
  "is_active": true,
  "is_unsubscribed": false,
  "unsubscribed_at": null,
  "custom_fields": {
    "company": "Acme Corp",
    "department": "Engineering",
    "phone": "+1-555-0123",
    "job_title": "Senior Developer"
  },
  "metadata": {
    "source": "website",
    "campaign": "newsletter",
    "created_via": "api_key",
    "api_key_id": "api_key_uuid_here"
  },
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Error Response - Duplicate Email (409 Conflict)

{
  "statusCode": 409,
  "message": "You already have a contact with email john.doe@example.com",
  "error": "Conflict"
}

Error Response - Duplicate External ID (409 Conflict)

{
  "statusCode": 409,
  "message": "You already have a contact with external_id CRM-001",
  "error": "Conflict"
}

Error Response - Invalid Email (400 Bad Request)

{
  "statusCode": 400,
  "message": "Invalid email format",
  "error": "Bad Request",
  "details": {
    "field": "email",
    "code": "invalid_format"
  }
}

Error Response - Missing Required Field (400 Bad Request)

{
  "statusCode": 400,
  "message": "Missing required field: email",
  "error": "Bad Request",
  "details": {
    "field": "email",
    "code": "required"
  }
}

Key Behaviors

🔄 Auto-generation

If no external_id is provided, the system generates a UUID automatically:

# Request without external_id
curl -X POST https://api.sendmator.com/api/v1/contacts \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "first_name": "Jane"
  }'

# Response includes auto-generated external_id
{
  "id": "456e7890-e89b-12d3-a456-426614174111",
  "external_id": "auto_gen_789e4567-e89b-12d3-a456-426614174222",
  "email": "jane.doe@example.com",
  "first_name": "Jane",
  ...
}

🔒 Uniqueness Constraints

external_id must be unique within your team:

• ✅ Different teams can have contacts with the same external_id
• ❌ Same team cannot have duplicate external_id values
• 💡 email is also unique per team to prevent accidental duplicates

📊 Metadata Enhancement

API calls automatically add tracking metadata:

{
  "metadata": {
    "your_metadata": "custom_value",
    "created_via": "api_key",
    "api_key_id": "your_api_key_uuid"
  }
}

👤 User Isolation

Contacts are scoped to the authenticated user - you can only access your own contacts.

🔍 Searchable Reference

The external_id is included in search functionality, making it easy to find contacts using your existing ID schemes.

Use Cases

CRM Integration

# Sync from your CRM system
curl -X POST https://api.sendmator.com/api/v1/contacts \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CRM_CONTACT_12345",
    "email": "lead@company.com",
    "custom_fields": {
      "crm_stage": "qualified_lead",
      "deal_value": 50000,
      "expected_close": "2024-03-15"
    }
  }'

E-commerce Integration

# Customer from your store
curl -X POST https://api.sendmator.com/api/v1/contacts \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CUSTOMER_67890",
    "email": "customer@example.com",
    "tags": ["customer", "vip"],
    "custom_fields": {
      "total_orders": 15,
      "lifetime_value": 2500.00,
      "preferred_category": "electronics"
    },
    "metadata": {
      "source": "checkout",
      "first_purchase": "2023-06-15"
    }
  }'

Lead Capture

# Website form submission
curl -X POST https://api.sendmator.com/api/v1/contacts \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "prospect@startup.com",
    "first_name": "Alex",
    "tags": ["lead", "free_trial"],
    "custom_fields": {
      "company_size": "10-50",
      "industry": "saas",
      "trial_started": true
    },
    "metadata": {
      "source": "landing_page",
      "utm_campaign": "product_hunt_launch",
      "form_id": "trial_signup"
    }
  }'

Best Practices

1. Use meaningful external_ids - Make them readable and consistent with your system
2. Structure custom_fields - Use consistent field names across contacts
3. Tag strategically - Use tags for segmentation and filtering
4. Track sources - Always include source information in metadata
5. Handle duplicates - Check for 409 errors and handle appropriately
6. Validate before sending - Ensure email format is valid

Next Steps

• Get Contact - Retrieve a specific contact
• List Contacts - Get all contacts with filtering
• Update Contact - Modify existing contact data
• Delete Contact - Remove a contact