Getting started overview

Getting started with Postmon involves creating an account, obtaining necessary credentials, and implementing one of the available SDKs or making direct HTTP API calls to send event data. The process focuses on enabling real-time user behavior tracking and integrating this data into your analytics workflows.

Postmon is designed for tracking user interactions across web and mobile applications, providing tools for conversion funnel analysis and A/B testing analytics. The platform supports integration with existing data warehouses, which can be a key consideration for developers managing larger data ecosystems. A foundational understanding of API keys and event-driven architectures will facilitate a smoother integration process. For general information on API keys as an authentication method, refer to Cloudflare's API key security guide.

This guide outlines the initial steps required to send your first event to Postmon, covering account setup, credential retrieval, and example code for common programming environments. A quick-reference table summarizes the workflow:

Step What to Do Where
1. Account Creation Sign up for a Postmon account. Postmon homepage
2. Project Setup Create a new project in your Postmon dashboard. Postmon dashboard
3. Credentials Retrieval Locate your Project ID and API Key. Project Settings in Postmon dashboard
4. SDK/API Integration Choose an SDK or use the HTTP API to send an event. Application code or API client
5. Verify Data Check the Postmon dashboard for the received event. Postmon dashboard's Live Events view

Create an account and get keys

To begin using Postmon, the first step is to create an account. Postmon offers a free tier that supports up to 10,000 events per month, which allows for initial testing and development without immediate cost. You can initiate the signup process directly from the Postmon homepage.

  1. Sign Up: Navigate to the Postmon website and select the 'Sign Up' or 'Get Started' option. You will typically be prompted to provide an email address and create a password.
  2. Create a Project: After logging in for the first time, you will usually be guided to create a new project. A project acts as a container for your application's data. Give your project a descriptive name, such as 'My Web App' or 'iOS Mobile App'.
  3. Locate Credentials: Once your project is created, Postmon will generate a unique Project ID and an API Key for that project. These are your primary credentials for sending data to Postmon. Access these keys from your project's settings or API settings page within the Postmon dashboard. The Postmon documentation provides detailed instructions on locating these specific values.

It is important to keep your API Key secure, as it grants write access to your Postmon project. Best practices for API key security include never hardcoding keys directly into publicly accessible client-side code and using environment variables or secure configuration management where appropriate. For server-side integrations, secure storage of API keys is critical. For instance, Google Cloud's API key best practices recommend restricting API keys by IP address and API, and using service accounts where possible.

Your first request

After obtaining your Project ID and API Key, you can send your first event to Postmon. Postmon provides SDKs for various programming languages, as well as a direct HTTP API. This section demonstrates sending a simple 'page_view' event using the JavaScript SDK, Python SDK, and a direct HTTP POST request.

Using the JavaScript SDK (Web)

For web applications, the JavaScript SDK is typically the most straightforward method. Include the Postmon SDK in your HTML and initialize it with your Project ID.

<!-- Add this script to your HTML <head> or before </body> -->
<script type="text/javascript">
  (function(p,o,s,t,m,o,n){p['PostmonObject']=m;p[m]=p[m]||function(){
  (p[m].q=p[m].q||[]).push(arguments)},p[m].l=1*new Date();o=s.createElement(t),
  n=s.getElementsByTagName(t)[0];o.async=1;o.src='https://cdn.postmon.com/sdk.js';n.parentNode.insertBefore(o,n)
  })(window,document,'script','https://cdn.postmon.com/sdk.js','postmon');

  // Initialize Postmon with your Project ID
  postmon('init', 'YOUR_PROJECT_ID');

  // Track a page view event
  postmon('track', 'page_view', {
    page_path: window.location.pathname,
    page_title: document.title
  });
</script>

Replace 'YOUR_PROJECT_ID' with your actual Postmon Project ID. This code snippet initializes the SDK and then immediately tracks a page_view event, sending the current page's path and title as properties.

Using the Python SDK (Server-side)

For server-side applications or scripts, the Python SDK simplifies event tracking. First, install the SDK:

pip install postmon-python

Then, use the following Python code:

import postmon

# Initialize the Postmon client with your Project ID and API Key
postmon.init('YOUR_PROJECT_ID', 'YOUR_API_KEY')

# Track a custom event
postmon.track(
    event_name='user_signed_up',
    distinct_id='user_123',
    properties={
        'plan': 'premium',
        'source': 'website'
    }
)
print("Event 'user_signed_up' sent to Postmon.")

Replace 'YOUR_PROJECT_ID' and 'YOUR_API_KEY' with your actual credentials. The distinct_id is crucial for identifying unique users in Postmon's analytics. The Postmon Python SDK documentation provides more details on identifying users and tracking complex events.

Using the HTTP API (Direct Request)

For environments without a specific SDK or for direct integration, you can use the Postmon HTTP API. This requires constructing a JSON payload and sending it as a POST request. Your API Key is used for authentication.

curl -X POST \
  https://api.postmon.com/track \
  -H "Content-Type: application/json" \
  -H "X-Postmon-API-Key: YOUR_API_KEY" \
  -d '{
        "event": "custom_event",
        "properties": {
          "distinct_id": "user_456",
          "action": "button_click",
          "element_id": "submit_btn"
        },
        "project_id": "YOUR_PROJECT_ID"
      }'

Ensure you replace YOUR_API_KEY and YOUR_PROJECT_ID with your valid credentials. This example sends a custom_event with properties defining the user and the action performed. The Postmon API reference offers comprehensive details on supported event structures and endpoints.

Common next steps

Once you have successfully sent your first event to Postmon, several common next steps can help you leverage the platform for deeper insights:

  1. Verify Event Data: Check the 'Live Events' or 'Data Explorer' section within your Postmon dashboard to confirm that your events are being received correctly. This verifies that your integration is functioning as expected.
  2. Identify Users: Implement user identification calls (e.g., postmon.identify() in SDKs) to associate events with specific users. This is critical for tracking individual user journeys, creating user segments, and performing cohort analysis.
  3. Track Key Events: Define and implement tracking for all critical user actions within your application, such as sign-ups, purchases, feature usage, and content views. A well-defined event taxonomy is crucial for meaningful analytics.
  4. Create Funnels and Cohorts: Utilize Postmon's analytics features to build conversion funnels, understanding user drop-off points, and create cohorts to analyze user behavior over time.
  5. Integrate with Data Warehouses: If you use a data warehouse, explore Postmon's integration options to export your event stream for centralized data analysis and reporting. Postmon supports integration with various data warehousing solutions.
  6. Configure Dashboards and Reports: Set up custom dashboards and reports in Postmon to visualize key metrics relevant to your product and business goals.

Troubleshooting the first call

Encountering issues during your initial Postmon integration is common. Here are some troubleshooting steps:

  • Check Credentials: Double-check that your Project ID and API Key are copied correctly and match the ones in your Postmon dashboard. Even a single character mismatch can lead to authentication failures.
  • Network Connectivity: Ensure your application or environment has outbound network access to api.postmon.com. Firewall rules or proxy settings can sometimes block these requests.
  • HTTP Status Codes: If using the HTTP API, inspect the HTTP status code returned in the response. Common error codes include:
    • 400 Bad Request: Indicates an issue with your request payload (e.g., malformed JSON, missing required fields). Review the Postmon API reference for correct payload structure.
    • 401 Unauthorized: Typically means your API Key is incorrect or missing.
    • 403 Forbidden: Your API Key might be valid, but lacks the necessary permissions for the requested action, or the Project ID is incorrect for the given API key.
    • 5xx Server Error: Suggests an issue on Postmon's side. If these persist, check the Postmon status page or contact support.
  • SDK Debugging: Most Postmon SDKs offer a debug mode or logging options. Enable these to get more verbose output in your console or logs, which can reveal issues like incorrect initialization or event property formatting. Consult your specific Postmon SDK documentation for how to enable debugging.
  • Dashboard Live Events: The 'Live Events' view in the Postmon dashboard is a critical tool. If events are not appearing there even after successful API calls, there might be a processing issue, or the project ID used might be for a different project.
  • CORS Issues (Web SDK): If you encounter Cross-Origin Resource Sharing (CORS) errors when using the JavaScript SDK, ensure that the domain where your script is running is properly configured in your Postmon project settings as an authorized domain. The MDN Web Docs on CORS provide a technical overview of this security mechanism.