Skip to main content

Contacts API Overview

The Contacts API provides comprehensive contact management capabilities for your email marketing and automation needs. Manage contact profiles, custom data, segmentation, and integrations with your existing systems.

Key Features​

🔑 Flexible ID Management​

  • Auto-generated UUIDs - System creates unique IDs when not provided
  • External ID support - Use your own ID schemes (CRM IDs, user IDs, etc.)
  • Uniqueness guarantees - Email and external_id are unique per account

📊 Rich Profile Data​

  • Standard fields - Name, email, tags, active status
  • Custom fields - Unlimited structured data for your business needs
  • Metadata tracking - Source attribution, UTM parameters, system data

🔍 Advanced Search & Filtering​

  • Tag-based filtering - Segment contacts by multiple tags
  • Status filtering - Active/inactive, subscribed/unsubscribed
  • Full-text search - Search across name, email, and external_id
  • Date range filtering - Filter by creation or update dates

🔗 System Integration​

  • API-first design - Built for CRM and e-commerce integrations
  • Webhook support - Real-time notifications for contact events
  • Bulk operations - Efficient handling of large contact lists

Base URL​

https://api.sendmator.com/api/v1/contacts

Authentication​

All requests require the X-API-Key header:

X-API-Key: sk_live_your_api_key

Available Endpoints​

Contact Management​

MethodEndpointDescription
POST /contactsAdd ContactCreate a new contact with full profile data
GET /contacts/{id}Get ContactRetrieve detailed contact information
GET /contactsList ContactsGet paginated contacts with filtering
PUT /contacts/{id}Update ContactModify existing contact data
DELETE /contacts/{id}Delete ContactPermanently remove a contact

Data Model​

Core Contact Fields​

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "external_id": "CRM-001",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "tags": ["customer", "vip"],
  "is_active": true,
  "is_unsubscribed": false,
  "unsubscribed_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Custom Fields Structure​

Store any business-specific data:

{
  "custom_fields": {
    "company": "Acme Corp",
    "job_title": "Engineering Manager",
    "phone": "+1-555-0123",
    "annual_revenue": 150000,
    "lead_score": 85,
    "subscription_tier": "premium",
    "last_login": "2024-01-14T15:30:00Z"
  }
}

Metadata for Tracking​

Perfect for analytics and attribution:

{
  "metadata": {
    "source": "website",
    "utm_campaign": "winter_sale",
    "utm_source": "google",
    "utm_medium": "cpc",
    "referrer": "https://google.com",
    "ip_address": "192.168.1.1",
    "browser": "Chrome",
    "signup_flow": "free_trial"
  }
}

Quick Start Example​

1. Add a New Contact​

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\": \"USER_12345\",
    \"email\": \"customer@example.com\",
    \"first_name\": \"Sarah\",
    \"last_name\": \"Johnson\",
    \"tags\": [\"customer\", \"premium\"],
    \"custom_fields\": {
      \"company\": \"TechStart Inc\",
      \"plan\": \"pro\"
    },
    \"metadata\": {
      \"source\": \"signup_form\",
      \"campaign\": \"launch_week\"
    }
  }'

2. List Contacts with Filtering​

curl -H \"X-API-Key: sk_live_your_api_key\" \\
     \"https://api.sendmator.com/api/v1/contacts?tag=premium&limit=50\"

3. Update Contact Information​

curl -X PUT https://api.sendmator.com/api/v1/contacts/USER_12345 \\
  -H \"X-API-Key: sk_live_your_api_key\" \\
  -H \"Content-Type: application/json\" \\
  -d '{
    \"custom_fields\": {
      \"plan\": \"enterprise\",
      \"upgrade_date\": \"2024-01-20\"
    }
  }'

Common Use Cases​

🛒 E-commerce Integration​

Track customer data, purchase history, and preferences:

{
  \"external_id\": \"CUSTOMER_67890\",
  \"email\": \"buyer@example.com\",
  \"tags\": [\"customer\", \"repeat_buyer\"],
  \"custom_fields\": {
    \"total_orders\": 12,
    \"lifetime_value\": 2450.00,
    \"favorite_category\": \"electronics\",
    \"last_order_date\": \"2024-01-18\"
  }
}

💼 CRM Synchronization​

Sync leads and contacts from your CRM:

{
  \"external_id\": \"LEAD_SF_001\",
  \"email\": \"prospect@startup.com\",
  \"tags\": [\"lead\", \"qualified\"],
  \"custom_fields\": {
    \"lead_source\": \"inbound\",
    \"deal_stage\": \"proposal\",
    \"deal_value\": 75000,
    \"account_executive\": \"jane.smith@company.com\"
  }
}

📱 SaaS User Management​

Track app users and their engagement:

{
  \"external_id\": \"APP_USER_456\",
  \"email\": \"user@saas-company.com\",
  \"tags\": [\"free_trial\", \"active\"],
  \"custom_fields\": {
    \"trial_end_date\": \"2024-02-01\",
    \"features_used\": [\"dashboard\", \"reports\"],
    \"login_count\": 15,
    \"last_activity\": \"2024-01-19T14:30:00Z\"
  }
}

Error Handling​

The API returns standard HTTP status codes:

  • 200 OK - Successful retrieval
  • 201 Created - Contact created successfully
  • 400 Bad Request - Invalid request data
  • 404 Not Found - Contact not found
  • 409 Conflict - Duplicate email or external_id

Example error response:

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

Rate Limits​

Contact API endpoints share the same rate limits as other Sendmator APIs:

  • Free Plan: 100 requests/hour
  • Pro Plan: 10,000 requests/hour
  • Enterprise: Custom limits

Next Steps​

  1. Add your first contact - Start with the create endpoint
  2. Set up webhooks - Get real-time notifications
  3. Integrate with emails - Send targeted campaigns
  4. Explore filtering - Advanced contact segmentation

Need Help?​