SendX JAVA SDK

🚀 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

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:

<resource_prefix>_<22_character_alphanumeric_string>

Example:

{
  "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	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

🎯 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
• Python
• Ruby
• Java
• PHP
• JavaScript

📞 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

For more information, please visit https://sendx.io

Requirements

Building the API client library requires:

1. Java 1.8+
2. Maven (3.8.3+)/Gradle (7.2+)

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>io.sendx</groupId>
  <artifactId>sendx-java-sdk</artifactId>
  <version>2.0.0</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

  repositories {
    mavenCentral()     // Needed if the 'sendx-java-sdk' jar has been published to maven central.
    mavenLocal()       // Needed if the 'sendx-java-sdk' jar has been published to the local maven repo.
  }

  dependencies {
     implementation "io.sendx:sendx-java-sdk:2.0.0"
  }

Getting Started

Please follow the installation instruction and execute the following Java code:

// Import classes:
import sendx_java_sdk.ApiClient;
import sendx_java_sdk.ApiException;
import sendx_java_sdk.Configuration;
import sendx_java_sdk.auth.*;
import sendx_java_sdk.*;
import sendx_java_sdk.CampaignApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("https://api.sendx.io/api/v1/rest");
    
    // Configure API key authorization: TeamApiKey
    ApiKeyAuth TeamApiKey = (ApiKeyAuth) defaultClient.getAuthentication("TeamApiKey");
    TeamApiKey.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //TeamApiKey.setApiKeyPrefix("Token");

    ContactApi apiInstance = new ContactApi(defaultClient);
    ContactRequest contactRequest = new ContactRequest(); // ContactRequest | 
    contactRequest.setFirstName("John")
    contactRequest.setLastName("Doe")
    contactRequest.setEmail("john.doe@sendx.io")
    contactRequest.setCompany("SendX")
    contactRequest.setLastTrackedIp("32.342.12.322")

    // Set tags as a list of strings
    List<String> tags = Arrays.asList("sner1jin3ij34b4", "234bjk2n42ednj32";
    contactRequest.setTags(tags)

    try {
      OperationResponse result = apiInstance.createContact(contactRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling CampaignApi#createCampaign");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Documentation for API Endpoints

All URIs are relative to https://api.sendx.io/api/v1/rest

Class	Method	HTTP request	Description
CampaignApi	createCampaign	POST /campaign	Create campaign
CampaignApi	deleteCampaign	DELETE /campaign/{identifier}	Delete campaign
CampaignApi	getAllCampaigns	GET /campaign	Get all campaigns
CampaignApi	getCampaign	GET /campaign/{identifier}	Get campaign by ID
ContactApi	createContact	POST /contact	Create a new contact
ContactApi	deleteContact	DELETE /contact/{identifier}	Delete contact
ContactApi	getAllContacts	GET /contact	Get all contacts
ContactApi	getContact	GET /contact/{identifier}	Get contact by ID
ContactApi	unsubscribeContact	POST /contact/unsubscribe/{identifier}	Unsubscribe contact
ContactApi	updateContact	PUT /contact/{identifier}	Update contact
CustomFieldApi	createCustomField	POST /customfield	Create custom field
CustomFieldApi	deleteCustomField	DELETE /customfield/{identifier}	Delete custom field
CustomFieldApi	getAllCustomFields	GET /customfield	Get all custom fields
CustomFieldApi	getCustomField	GET /customfield/{identifier}	Get custom field by ID
CustomFieldApi	updateCustomField	PUT /customfield/{identifier}	Update custom field
EmailSendingApi	sendEmail	POST /send/email	Send transactional email
EmailSendingApi	sendEmailWithTemplate	POST /send/template	Send email using template
EventApi	eventsCustomPostbackGet	GET /events/custom/postback	Custom Event Postback URL
EventApi	eventsRevenuePostbackGet	GET /events/revenue/postback	Revenue Event Postback URL
EventsApi	trackCustomEvent	POST /events/custom	Track custom event
EventsApi	trackRevenueEvent	POST /events/revenue	Track revenue event
ListApi	createList	POST /list	Create list
ListApi	deleteList	DELETE /list/{identifier}	Delete list
ListApi	getAllLists	GET /list	Get all lists
ListApi	getList	GET /list/{identifier}	Get list by ID
ListApi	updateList	PUT /list/{identifier}	Update list
PostApi	createPost	POST /post	Create blog post
PostApi	deletePost	DELETE /post/{identifier}	Delete post
PostApi	getAllPosts	GET /post	Get all posts
PostApi	getPost	GET /post/{identifier}	Get post by ID
PostApi	updatePost	PUT /post/{identifier}	Update post
PostCategoryApi	createPostCategory	POST /post/category	Create post category
PostCategoryApi	deletePostCategory	DELETE /post/category/{identifier}	Delete post category
PostCategoryApi	getAllPostCategories	GET /post/category	Get all post categories
PostCategoryApi	getPostCategory	GET /post/category/{identifier}	Get post category by ID
PostCategoryApi	updatePostCategory	PUT /post/category/{identifier}	Update post category
PostTagApi	createPostTag	POST /post/tag	Create post tag
PostTagApi	deletePostTag	DELETE /post/tag/{identifier}	Delete post tag
PostTagApi	getAllPostTags	GET /post/tag	Get all post tags
PostTagApi	getPostTag	GET /post/tag/{identifier}	Get post tag by ID
PostTagApi	updatePostTag	PUT /post/tag/{identifier}	Update post tag
ReportApi	getCampaignReport	GET /report/campaign/{identifier}	Get campaign report
SenderApi	createSender	POST /sender	Create sender
SenderApi	getAllSenders	GET /sender	Get all senders
TagApi	createTag	POST /tag	Create tag
TagApi	deleteTag	DELETE /tag/{identifier}	Delete tag
TagApi	getAllTags	GET /tag	Get all tags
TagApi	getTag	GET /tag/{identifier}	Get tag by ID
TagApi	updateTag	PUT /tag/{identifier}	Update tag
TeamMemberApi	getAllTeamMembers	GET /team/member	Get all team members
TeamMemberApi	getTeamMember	GET /team/member/{identifier}	Get a team member by ID
TemplateApi	createEmailTemplate	POST /template/email	Create email template
TemplateApi	deleteEmailTemplate	DELETE /template/email/{identifier}	Delete template
TemplateApi	getAllEmailTemplates	GET /template/email	Get all templates
TemplateApi	getEmailTemplate	GET /template/email/{identifier}	Get template by ID
TemplateApi	updateEmailTemplate	PUT /template/email/{identifier}	Update template
TrackingApi	identifyContact	POST /contact/identify	Identify contact
TrackingApi	trackContact	POST /contact/track	Track contact
WebhookApi	createWebhook	POST /webhook	Create webhook
WebhookApi	deleteWebhook	DELETE /webhook/{identifier}	Delete webhook
WebhookApi	getAllWebhooks	GET /webhook	Get all webhooks
WebhookApi	getWebhook	GET /webhook/{identifier}	Get webhook by ID
WebhookApi	updateWebhook	PUT /webhook/{identifier}	Update webhook

Documentation for Models

• CustomEventRequest
• DeleteResponse
• ErrorResponse
• EventResponse
• EventsRevenuePostbackGet200Response
• EventsRevenuePostbackGet400Response
• EventsRevenuePostbackGet500Response
• IdentifyRequest
• IdentifyResponse
• LinkStat
• MessageResponse
• PostbackResponse
• RestECampaign
• RestEContact
• RestECustomField
• RestEList
• RestEPost
• RestEPostCategory
• RestEPostTag
• RestESender
• RestETag
• RestETemplate
• RestEWebhook
• RestRCampaign
• RestRContact
• RestRCustomField
• RestRList
• RestRMember
• RestRPost
• RestRPostCategory
• RestRPostTag
• RestRSender
• RestRTag
• RestRTemplate
• RestRWebhook
• RestReportData
• RevenueEventRequest
• TemplateEmailMessage
• TrackRequest
• TrackResponse
• WebhookObject
• XAttachment
• XEmailMessage
• XEmailResponse
• XFrom
• XReplyTo
• XTo

Documentation for Authorization

Authentication schemes defined for the API:

TeamApiKey

• Type: API key
• API key parameter name: X-Team-ApiKey
• Location: HTTP header

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

hello@sendx.io