> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send and Track Events
> Learn how to send events to trigger workflows, with code snippets and examples.
## Send Event
You can send event to Suprsend platform by using the `suprClient.trackEvent` method. When you call `suprClient.trackEvent`, the SDK internally makes an `HTTP` call to SuprSend Platform to register this request, and you'll immediately receive a response indicating the acceptance status. The actual processing/execution of event happens asynchronously.
```java Request theme={"system"}
package suprsend;
import org.json.JSONObject;
import java.io.UnsupportedEncodingException;
import suprsend.Suprsend;
import suprsend.SuprsendException;
import suprsend.Event;
public class Event {
public static void main(String[] args) throws Exception {
trackEvent();
}
private static void trackEvent() throws SuprsendException, UnsupportedEncodingException{
// Initialize SDK
Suprsend suprClient = new Suprsend("_workspace_key_", "_workspace_secret_");
String distinctId = "_distinct_id_";
String eventName = "__event_name__";
// dynamic data to render template and workflow variables
JSONObject eventProps = new JSONObject()
.put("key1", "value1")
.put("key2", "value2");
Event e = new Event(distinctId, eventName, eventProps);
JSONObject response = suprClient.trackEvent(e);
System.out.println(response);
}
}
```
```java Sample Code theme={"system"}
package suprsend;
import org.json.JSONObject;
import java.io.UnsupportedEncodingException;
import suprsend.Suprsend;
import suprsend.SuprsendException;
import suprsend.Event;
public class Event {
public static void main(String[] args) throws Exception {
trackEvent();
}
private static void trackEvent() throws SuprsendException, UnsupportedEncodingException{
// Initialize SDK
Suprsend suprClient = new Suprsend("_workspace_key_", "_workspace_secret_");
String distinctId = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08";
String eventName = "product_purchased";
// dynamic data to render template and workflow variables
JSONObject eventProps = new JSONObject()
.put("first_name", "User")
.put("spend_amount", "$10")
.put("nested_key_example", new JSONObject().put("nested_key1", "some_value_1"));
Event e = new Event(distinctId, eventName, eventProps);
JSONObject response = suprClient.trackEvent(e);
System.out.println(response);
}
}
```
```java Response theme={"system"}
// Response structure
{
"success": True, # if true, request was accepted.
"status": "success",
"status_code": 202, # http status code
"message": "OK",
}
{
"success": False, # error will be present in message
"status": "fail",
"status_code": 500, # http status code
"message": "error message",
}
```
| Parameter | Description | Format | Obligation |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------- |
| `distinct_id` | `distinct_id` of subscriber performing the event | int, bigint, string, UUID | *mandatory* |
| `event_name` | string identifier for the event like `product_purchased` | string | *mandatory* |
| `properties` | a dictionary representing event attributes like `first_name` Event properties can be used to pass template variables in case of event based trigger | Dictionary | *optional* |
**Event naming guidelines:**
When you create an Event or a property, please ensure that the Event Name or Property Name does not start with or , as we have reserved these symbols for our internal events and property names.
### Trigger events for a brand/tenant
If you handle communications to end users on behalf of your customers and want to send custom notifications for each brand/tenant, you can do that with the help of [brands (now called tenants)](/docs/tenants).
Just pass the **brand\_id** of your customer brand as the **fifth parameter in your event instance** like shown below and the properties of that brand will be used to replace brand variables in your template.
```java Request theme={"system"}
Event e = new Event(distinctId, eventName, eventProps, , brandId);
```
### Idempotent requests
SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If Suprsend receives and processes a request with an idempotency\_key, it will skip processing requests with same `idempotency_key` for next 24 hours. You can use this key to track webhooks related to workflow notifications.
To make an idempotent request, pass `idempotency_key` as the **fourth parameter in your event instance** like shown below. Idempotency key should be unique that you generate for each request. You may use any string up to 255 characters in length as an idempotency key. Ensure that you don’t add any space in start and end of the key as it will be trimmed.
```java Request theme={"system"}
Event e = new Event(distinctId, eventName, eventProps, idempotencyKey);
```
Here are some common approaches for assigning idempotency keys:
* **Generate a random UUID** for each request.
* **Construct the idempotency key by combining relevant information about the request**. This can include parameters, identifiers, or specific contextual details that are meaningful within your application. e.g., you could concatenate the user ID, action, and timestamp to form an idempotency key like user147-new-comment-1687437670
* **Request-specific Identifier**: If your request already contains a unique identifier, such as an order ID or a job ID, you can use that identifier directly as the idempotency key.
### Add file attachment (for email)
You can add file attachment by appending the attachment filepath to each event instance.
* Call `event.addAttachment()` for each file with an accessible URL. Ensure that file\_path is a publicly accessible URL.
* Since event API size can't be > 100 KB, local file paths can't be passed in event attachment.
```java Request theme={"system"}
...
Event e1 = new Event(distinctId1, eventName1, eventProps1); //Event 1
// this snippet can be used to add attachment to event
String filePath1 = "https://www.africau.edu/images/default/sample.pdf";
e1.addAttachment(filePath1);
...
```
Please add public accessible URL only as attachment file otherwise it will throw an error `404 not found` and workflow will not be triggered
## Bulk event trigger
You can use Bulk API to send multiple events.
Use `.append()` on bulk\_events instance to add however-many-records to call in bulk.
```java java theme={"system"}
...
BulkEvents bulkIns = suprClient.bulkEvents.newInstance();
Event e1 = new Event(distinctId1, eventName1, eventProps1); //Event 1
Event e2 = new Event(distinctId2, eventName2, eventProps2); //Event 2
// --- use .append on bulk instance to add one or more records
bulkIns.append(e1)
bulkIns.append(e2)
// OR
bulkIns.append(e1, e2)
// Track event
JSONObject response = bulkIns.trigger();
System.out.println(response);
```
Bulk API is supported in SuprSend java-sdk version 0.5.0 and above. If you are using an older version, please upgrade to the latest SDK version.
***