> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendx.io/llms.txt > Use this file to discover all available pages before exploring further. # Get all contacts > Retrieves a paginated list of all contacts in your team with optional filtering capabilities. **🎯 Key Features:** - Pagination support with offset/limit - Search contacts by name or email - All relationships included (lists, tags, custom fields) - Prefixed IDs for easy integration **📊 Pagination:** - Default limit: 10 contacts per page - Maximum limit: 100 contacts per page - Use offset for page navigation **🔍 Search:** - Searches across firstName, lastName, and email fields - Case-insensitive partial matching - Combine with pagination for large datasets ## OpenAPI ````yaml get /contact openapi: 3.1.0 info: title: SendX REST API version: 1.0.0 description: > # SendX REST API Documentation ## 🚀 Introduction The SendX API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. **Key Features:** - 🔒 **Security**: Team-based authentication with optional member-level access - 🎯 **Resource-Oriented**: RESTful design with clear resource boundaries - 📊 **Rich Data Models**: Three-layer model system (Input/Output/Internal) - 🔗 **Relationships**: Automatic prefix handling for resource relationships - 📈 **Scalable**: Built for high-volume email marketing operations ## 🏗️ Architecture Overview SendX uses a three-layer model architecture: 1. **Input Models** (`RestE*`): For API requests 2. **Output Models** (`RestR*`): For API responses with prefixed IDs 3. **Internal Models**: Core business logic (not exposed in API) ## 🔐 Security & Authentication SendX uses API key authentication: ### Team API Key ```http X-Team-ApiKey: YOUR_TEAM_API_KEY ``` - **Required for all requests** - Team-level access to resources - Available in SendX Settings → Team API Key ## 🆔 Encrypted ID System SendX uses encrypted IDs for security and better developer experience: - **Internal IDs**: Sequential integers (not exposed) - **Encrypted IDs**: 22-character alphanumeric strings - **Prefixed IDs**: Resource-type prefixes in API responses (`contact_<22-char-id>`) ### ID Format **All resource IDs follow this pattern:** ``` _<22_character_alphanumeric_string> ``` **Example:** ```json { "id": "contact_BnKjkbBBS500CoBCP0oChQ", "lists": ["list_OcuxJHdiAvujmwQVJfd3ss", "list_0tOFLp5RgV7s3LNiHrjGYs"], "tags": ["tag_UhsDkjL772Qbj5lWtT62VK", "tag_fL7t9lsnZ9swvx2HrtQ9wM"] } ``` ## 📚 Resource Prefixes | Resource | Prefix | Example | |----------|--------|---------| | Contact | `contact_` | `contact_BnKjkbBBS500CoBCP0oChQ` | | Campaign | `campaign_` | `campaign_LUE9BTxmksSmqHWbh96zsn` | | List | `list_` | `list_OcuxJHdiAvujmwQVJfd3ss` | | Tag | `tag_` | `tag_UhsDkjL772Qbj5lWtT62VK` | | Sender | `sender_` | `sender_4vK3WFhMgvOwUNyaL4QxCD` | | Template | `template_` | `template_f3lJvTEhSjKGVb5Lwc5SWS` | | Custom Field | `custom_field_` | `field_MnuqBAG2NPLm7PZMWbjQxt` | | Webhook | `webhook_` | `webhook_9l154iiXlZoPo7vngmamee` | | Post | `post_` | `post_XyZ123aBc456DeF789GhI` | | Post Category | `post_category_` | `post_category_YzS1wOU20yw87UUHKxMzwn` | | Post Tag | `post_tag_` | `post_tag_123XyZ456AbC` | | Member | `member_` | `member_JkL012MnO345PqR678` | | Domain | `domain_` | `domain_504` | ## 🎯 Best Practices ### Error Handling - **Always check status codes**: 2xx = success, 4xx = client error, 5xx = server error - **Read error messages**: Descriptive messages help debug issues - **Handle rate limits**: Respect API rate limits for optimal performance ### Data Validation - **Email format**: Must be valid email addresses - **Required fields**: Check documentation for mandatory fields - **Field lengths**: Respect maximum length constraints ### Performance - **Pagination**: Use offset/limit for large datasets - **Batch operations**: Process multiple items when supported - **Caching**: Cache responses when appropriate ## 🛠️ SDKs & Integration Official SDKs available for: - [Golang](https://github.com/sendx/sendx-go-sdk) - [Python](https://github.com/sendx/sendx-python-sdk) - [Ruby](https://github.com/sendx/sendx-ruby-sdk) - [Java](https://github.com/sendx/sendx-java-sdk) - [PHP](https://github.com/sendx/sendx-php-sdk) - [JavaScript](https://github.com/sendx/sendx-javascript-sdk) ## 📞 Support Need help? Contact us: - 💬 **Website Chat**: Available on sendx.io - 📧 **Email**: hello@sendx.io - 📚 **Documentation**: Full guides at help.sendx.io --- **API Endpoint:** `https://api.sendx.io/api/v1/rest` [Run In Postman](https://god.gw.postman.com/run-collection/33476323-44b198b0-5219-4619-a01f-cfc24d573885?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D33476323-44b198b0-5219-4619-a01f-cfc24d573885%26entityType%3Dcollection%26workspaceId%3D6b1e4f65-96a9-4136-9512-6266c852517e) contact: name: SendX API Support email: hello@sendx.io url: https://sendx.io license: name: Proprietary url: https://sendx.io/terms servers: - url: https://api.sendx.io/api/v1/rest description: Production server security: - TeamApiKey: [] tags: - name: Contact description: > **Contact Management** Contacts are the core of your SendX account. They represent your customers, leads, or any person you wish to communicate with through marketing campaigns. **Key Features:** - ✅ Create, read, update, and delete contacts - 🏷️ Associate with lists and tags - 📝 Store custom field data - 📊 Track engagement metrics - 🔒 Team-based access control **Business Rules:** - Email addresses must be unique within a team - Custom fields are created automatically if they don't exist - Tags are created automatically when assigned - Soft deletes preserve historical data - name: Campaign description: > **Campaign Management** Campaigns allow you to send targeted email marketing messages to your contacts. **Key Features:** - 📧 Create and manage email campaigns - 🎯 Target specific lists and segments - 📊 Track campaign performance - ⏰ Schedule campaigns for future delivery - 🔄 A/B testing support - name: List description: | **List Management** Lists help you organize contacts into groups for targeted messaging. **Key Features:** - 📁 Create and manage contact lists - 👥 Bulk operations on list members - 🔗 Associate with campaigns - 📊 Track list growth metrics - name: Tag description: | **Tag Management** Tags provide flexible contact categorization for advanced segmentation. **Key Features:** - 🏷️ Create and manage tags - 🔍 Advanced contact filtering - 🎯 Behavior-based tagging - 📊 Tag-based analytics - name: Sender description: | **Sender Management** Manage verified sender addresses for your campaigns. **Key Features:** - ✉️ Add and verify sender addresses - 🔐 Domain authentication - 📧 Default sender settings - name: Template description: | **Email Template Management** Create and manage reusable email templates for campaigns. **Key Features:** - 🎨 HTML and text templates - 🔄 Reusable across campaigns - 📱 Mobile-responsive designs - 🏷️ Personalization support - name: Custom Field description: | **Custom Field Management** Define custom data fields for storing additional contact information. **Key Features:** - 📝 Create custom data fields - 🔢 Support for various data types - 📊 Use in segmentation - 🔄 Bulk updates - name: Webhook description: | **Webhook Management** Configure webhooks to receive real-time event notifications. **Key Features:** - 🔔 Real-time event notifications - 🎯 Event filtering - 🔒 Secure payload delivery - 📊 Delivery status tracking - name: Email Sending description: | **Email Sending APIs** Send transactional and marketing emails programmatically. **Key Features:** - 📧 Send individual emails - 🎨 Template-based sending - 📎 Attachment support - 🔄 Personalization variables - name: Events description: | **Event Tracking** Track custom events and revenue data for advanced analytics. **Key Features:** - 📊 Custom event tracking - 💰 Revenue attribution - 🔗 Integration with analytics - 📈 Conversion tracking - name: Tracking description: | **Contact Tracking APIs** Legacy tracking endpoints for backward compatibility. **Key Features:** - 👤 Identify contacts - 🏷️ Track contact behavior - 📊 Update contact properties - ⚠️ Consider using newer endpoints - name: Report description: | **Reporting APIs** Access detailed reports and analytics data. **Key Features:** - 📊 Campaign performance metrics - 📈 Engagement analytics - 💰 Revenue reports - 📉 Trend analysis - name: Post description: | **Blog Post Management** Manage blog posts and content for your marketing efforts. **Key Features:** - 📝 Create and manage posts - 🏷️ Categorize with tags - 📁 Organize by categories - 🔍 SEO optimization - name: Post Category description: | **Post Category Management** Organize blog posts into categories. **Key Features:** - 📁 Create categories - 🔗 Associate posts - 📊 Category analytics - name: Post Tag description: | **Post Tag Management** Tag blog posts for better organization and discovery. **Key Features:** - 🏷️ Create post tags - 🔍 Improve discoverability - 📊 Tag-based filtering - name: Team Member description: | **Team Member Information** Access team member details (read-only). **Key Features:** - 👤 View member profiles - 📧 Access member information - 🔒 Read-only access paths: /contact: get: tags: - Contact summary: Get all contacts description: > Retrieves a paginated list of all contacts in your team with optional filtering capabilities. **🎯 Key Features:** - Pagination support with offset/limit - Search contacts by name or email - All relationships included (lists, tags, custom fields) - Prefixed IDs for easy integration **📊 Pagination:** - Default limit: 10 contacts per page - Maximum limit: 100 contacts per page - Use offset for page navigation **🔍 Search:** - Searches across firstName, lastName, and email fields - Case-insensitive partial matching - Combine with pagination for large datasets operationId: getAllContacts parameters: - name: offset in: query description: | Number of records to skip for pagination. **Examples:** - `0` - First page (default) - `50` - Second page (with limit=50) - `100` - Third page (with limit=50) required: false schema: type: integer minimum: 0 default: 0 examples: first_page: summary: First page value: 0 second_page: summary: Second page (50 records per page) value: 50 - name: limit in: query description: | Maximum number of records to return. **Constraints:** - Minimum: 1 - Maximum: 100 - Default: 10 required: false schema: type: integer minimum: 1 maximum: 30 default: 10 examples: small_batch: summary: Small batch value: 10 standard_batch: summary: Standard batch value: 20 - name: search in: query description: | Search term to filter contacts by name or email. **Search Behavior:** - Searches firstName, lastName, and email fields - Case-insensitive partial matching - Minimum 2 characters for search **Examples:** - `john` - Finds "John Doe", "johnson@example.com" - `@company.com` - Finds all emails from company.com - `smith` - Finds "John Smith", "smith@email.com" required: false schema: type: string minLength: 2 maxLength: 255 examples: name_search: summary: Search by name value: john email_domain_search: summary: Search by email domain value: '@company.com' partial_match: summary: Partial name match value: smith responses: '200': description: ✅ Contacts retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/RestRContact' examples: contact_list: summary: List of contacts with relationships value: - id: contact_BnKjkbBBS500CoBCP0oChQ firstName: John lastName: Doe email: john.doe@example.com company: Example Corp customFields: field_MnuqBAG2NPLm7PZMWbjQxt: Sales field_QqfhckbdcvQinLPlduIbHq: Manager lists: - list_OcuxJHdiAvujmwQVJfd3ss - list_0tOFLp5RgV7s3LNiHrjGYs tags: - tag_6GN4DNyrHNt4KktCNG8PDO - tag_UhsDkjL772Qbj5lWtT62VK unsubscribed: false bounced: false spam: false blocked: false dropped: false created: '2024-01-10T14:20:00Z' updated: '2024-01-15T09:15:00Z' trackData: utm_source=website contactSource: 1 pageSource: https://example.com/signup lastTrackedIp: 203.0.113.42 ltv: 1500 - id: contact_AXCZG3Ii9bjBoUUINcSqo8 firstName: Jane lastName: Smith email: jane.smith@company.com company: Tech Solutions customFields: field_MnuqBAG2NPLm7PZMWbjQxt: Engineering lists: - list_OcuxJHdiAvujmwQVJfd3ss tags: - tag_fL7t9lsnZ9swvx2HrtQ9wM unsubscribed: false bounced: false spam: false blocked: false dropped: false created: '2024-01-12T16:45:00Z' updated: '2024-01-12T16:45:00Z' trackData: '' contactSource: 2 pageSource: '' lastTrackedIp: 198.51.100.25 ltv: 0 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' security: - TeamApiKey: [] components: schemas: RestRContact: type: object properties: id: type: string pattern: ^contact_[a-zA-Z0-9]{22}$ description: | Unique contact identifier with contact_ prefix. **Format:** `contact_` + 22 alphanumeric characters **Usage:** - Use this ID for all subsequent API calls - Unique across the entire SendX platform - Never changes once created example: contact_BnKjkbBBS500CoBCP0oChQ firstName: type: string nullable: true description: First name of the contact example: John lastName: type: string nullable: true description: Last name of the contact example: Doe email: type: string format: email description: Email address of the contact (unique within team) example: john.doe@example.com company: type: string nullable: true description: Company name of the contact example: Example Corp customFields: type: object additionalProperties: type: string description: | Custom fields with custom_field_ prefixed keys. **Format:** All keys have `custom_field_` prefix in responses **Example Structure:** ```json { "field_MnuqBAG2NPLm7PZMWbjQxt": "Engineering", "field_QqfhckbdcvQinLPlduIbHq": "Senior", "field_MnuqBAG2NPLm7PZMWbjQxt": "$75000" } ``` example: field_MnuqBAG2NPLm7PZMWbjQxt: Engineering field_QqfhckbdcvQinLPlduIbHq: Senior lists: type: array items: type: string pattern: ^list_[a-zA-Z0-9]{22}$ description: | Associated lists with list_ prefixed identifiers. **Format:** All IDs have `list_` prefix in responses example: - list_OcuxJHdiAvujmwQVJfd3ss - list_xyz789ghi012 tags: type: array items: type: string pattern: ^tag_[a-zA-Z0-9]{22}$ description: | Associated tags with tag_ prefixed identifiers. **Format:** All IDs have `tag_` prefix in responses example: - tag_UhsDkjL772Qbj5lWtT62VK - tag_UhsDkjL772Qbj5lWtT62VK unsubscribed: type: boolean description: Whether the contact has unsubscribed from emails example: false bounced: type: boolean description: Whether emails to this contact have bounced example: false spam: type: boolean description: Whether the contact has marked emails as spam example: false blocked: type: boolean description: Whether the contact is blocked from receiving emails example: false dropped: type: boolean description: Whether emails to this contact have been dropped example: false created: type: string format: date-time description: Contact creation timestamp (ISO 8601 format) example: '2024-01-10T14:20:00Z' updated: type: string format: date-time description: Contact last update timestamp (ISO 8601 format) example: '2024-01-15T09:15:00Z' trackData: type: string description: | Email tracking data and UTM parameters. **Contains:** - UTM parameters from campaigns - Attribution data - Custom tracking parameters example: utm_source=website&utm_campaign=signup&utm_medium=banner contactSource: type: integer description: | Source type of the contact creation. **Values:** - `1` - API/Manual - `2` - Import - `3` - Form - `4` - Integration example: 1 pageSource: type: string nullable: true description: URL of the page where contact was created example: https://example.com/signup?ref=google-ads lastTrackedIp: type: string format: ipv4 nullable: true description: Last tracked IP address of the contact example: 203.0.113.42 LTV: type: integer description: | Lifetime Value of the contact in cents. **Example:** 7500 = $75.00 example: 7500 ErrorResponse: type: object properties: status: type: string enum: - error example: error message: type: string description: Human-readable error message example: Invalid request format required: - status - message responses: BadRequest: description: ❌ Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_id: summary: Invalid ID format value: status: error message: Invalid identifier format missing_field: summary: Missing required field value: status: error message: Email is required Unauthorized: description: ❌ Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 401 message: The Team ID or API Key specified is not valid InternalServerError: description: ❌ Internal Server Error - System error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error message: Internal server error occurred securitySchemes: TeamApiKey: type: apiKey in: header name: X-Team-ApiKey description: > Team API key for authentication. Find your API key in SendX Settings → Team API Key. **Example:** ``` X-Team-ApiKey: your_team_api_key_here ``` ````