Logo

Docs / MsgGO

Discover how to integrate and manage your notification system with our simple yet powerful messaging service.

Docs

Delivering Events to MsgGO

Before You Start

You'll need:

Delivering Events to MsgGO

For MsgGO to send messages to your configured delivery targets, you first need to deliver an event to MsgGO. When MsgGO receives your event, it processes it according to your configuration and sends appropriate messages to all configured delivery targets.

You can deliver events to MsgGO in two simple ways:

Ways to Deliver the API Key

MsgGO offers flexibility in how you can provide your API key. This is useful because events might be sent from various systems and external services where you don't always have full control over the request format. You can deliver the API key in four ways:

API Key in URL Path

You can include the API key directly in the URL path.

https://msggo.io/inbox/YOUR_API_KEY?event=your-event
curl "https://msggo.io/inbox/YOUR_API_KEY?event=deploy_done&status=success"

The API key can be sent as a query parameter named msggo-key.

https://msggo.io/inbox?msggo-key=YOUR_API_KEY&event=your-event
curl "https://msggo.io/inbox?msggo-key=YOUR_API_KEY&event=user_registered&email=test@example.com"

For POST requests, the API key can be part of the request body as a field named msggo-key.

{
    "msggo-key": "YOUR_API_KEY",
    "event": "your-event",
    "data_field": "value"
}
curl -X POST "<https://msggo.io/inbox>" \
     -d '{"msggo-key":"YOUR_API_KEY","event":"payment_processed","amount":100}'
curl -X POST "https://msggo.io/inbox" \
     -d "msggo-key=YOUR_API_KEY" \
     -d "event=form_submission" \
     -d "customer_id=123"

The most recommended method is to send the API key in the X-MsgGO-Key HTTP header.

X-MsgGO-Key: YOUR_API_KEY
curl -X POST "https://msggo.io/inbox" \
     -H "X-MsgGO-Key: YOUR_API_KEY" \
     -d '{"event":"backup_completed","status":"success"}'

MsgGO detects the API key in the following order of priority:

  1. Header X-MsgGO-Key
  2. URL path /inbox/YOUR_API_KEY
  3. Query parameter msggo-key
  4. Body field msggo-key

Ways to Send Event Content

For MsgGO to process your event and send appropriate notifications, you need to deliver its content. You can do this in several ways:

Event Content as Query Parameters

You can send event data as query parameters in the URL. This applies to both GET and POST requests. All query parameters (except msggo-key) will be converted into fields of a JSON document.

Example (GET or POST):

https://msggo.io/inbox?msggo-key=YOUR_API_KEY&event=contact-form&name=John%20Doe&email=john.doe@example.com>
{
    "event": "contact-form",
    "name": "John Doe",
    "email": "john.doe@example.com"
}

For POST requests, you can send event data as standard form fields (application/x-www-form-urlencoded). These fields will also be converted into a JSON document.

curl example:

curl -X POST "https://msggo.io/inbox" \
     -H "X-MsgGO-Key: YOUR_API_KEY" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "event=new_order" \
     -d "product_id=XYZ123" \
     -d "quantity=2"
{
    "event": "new_order",
    "product_id": "XYZ123",
    "quantity": "2" // Note: values from form data are typically strings
}

This is the preferred method for complex data. You send a full JSON document in the body of the POST request with the Content-Type: application/json header.

curl example:

curl -X POST "<https://msggo.io/inbox>" \
     -H "X-MsgGO-Key: YOUR_API_KEY" \
     -d '{
           "event": "system_alert",
           "severity": "critical",
           "details": {
             "host": "server01",
             "metric": "cpu_usage",
             "value": "95%"
           }
         }'

MsgGO allows you to combine data sent as query parameters with data sent in the POST request body (both application/x-www-form-urlencoded and application/json). This data will be merged into a single JSON document. In case of conflicting field names, values from the POST request body take precedence over values from query parameters.

Default JSON Content Interpretation

If your request to MsgGO does not include a Content-Type header, MsgGO will automatically interpret the request body as a JSON document. To ensure correct processing, verify that data sent without this header is in valid JSON format.

Sending Events Directly from Frontend Applications (Browser/Mobile)

You can send events directly to MsgGO from your frontend applications (e.g., websites running in a browser, mobile apps) using a Public API Key.

Using Public API Keys

  • Generation: Public API Keys are generated within the MsgGO Api Keys section. Refer to How to generate an API key for instructions.
  • Security: Public keys are designed to be potentially visible in client-side code. Their security relies on:
    • Domain Restrictions: You must configure a list of Allowed Domains from which requests with this key will be accepted. Requests from other domains will be rejected.
    • Rate Limits: Public keys have stricter rate limits (e.g., 5 events per minute per IP address) to prevent abuse. Exceeding these limits will temporarily block the IP.
  • Usage: The actual mechanism for sending the event data (query parameters, POST body) and providing the Public API Key (header, query parameter, URL path) is the same as described in the "Ways to Deliver the API Key" and "Ways to Send Event Content" sections.

Even with the ability to use Public API Keys, a backend proxy might still be the preferred approach in certain scenarios:

  • Higher Rate Limit Requirements: If your frontend needs to send more events than allowed by public key rate limits, a backend proxy using a Private API Key (which has no rate limits) can be used.
  • Sensitive Pre-processing: If you need to add sensitive data or perform complex business logic before sending the event to MsgGO, this should be done on a secure backend.
  • Consolidating Requests: To hide the direct interaction with MsgGO or to consolidate event submissions from various client types through a single, controlled point.
  • Using a Private API Key for Other Reasons: If the specific action inherently requires the permissions or characteristics of a Private API Key that a Public Key doesn't offer.

Rate Limits

  • Private API Keys: Generally have no rate limits imposed by MsgGO for event ingestion. However, delivery targets (Slack, Email) have their own rate limits.
  • Public API Keys: Have specific rate limits for event ingestion (e.g., 5 events/minute per IP address). Exceeding these limits can result in temporary IP blocks.

If you exceed delivery target rate limits, message delivery will be paused, and you'll receive a notification in MsgGO.

Sample Backend Proxy Implementation

Instead of sending events directly from your frontend, create a backend endpoint that receives the event data from your frontend and then forwards it to MsgGO. This keeps your API key secure on your server.

Example Implementation

// Safe frontend implementation - sends data to your backend
async function sendEventToBackend(eventData) {
  try {
    const response = await fetch('https://your-backend.com/api/events', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        event_name: 'user-action',
        ...eventData
      })
    });
    
    const result = await response.json();
    return result;
  } catch (error) {
    console.error('Error sending event:', error);
    throw error;
  }
}

// Example usage
sendEventToBackend({ 
  action: 'button_click', 
  page: 'homepage',
  timestamp: new Date().toISOString() 
});

Error Responses

When delivering events to MsgGO, you might encounter various error responses. Understanding these errors will help you troubleshoot delivery issues effectively:

API Key Errors (HTTP 401 Unauthorized)

If your API key is invalid or missing, the endpoint will return:

{    
	"ok": false,    
	"statusCode": 401,    
	"message": "API key missing in the request"
}
  • Forgotten msggo-key parameter in your request or X-MsgGO-Key header
  • Using an incorrect or deleted API key
  • Sending the key in the wrong format

Payload Size Errors (HTTP 413 Payload Too Large)

If your JSON payload exceeds the maximum size limit, you'll receive:

{    
	"ok": false,    
	"statusCode": 413,    
	"message": "Payload too large"
}

Testing Your Messages

In the following sections, you'll find examples of how to deliver events using different programming languages. However, before implementing these in your code, you might want to test if your events are properly received by MsgGO. You can do this using tools like Postman, curl, or even your web browser.

Quick Browser Test

The simplest way to test event delivery is using your web browser. Just paste the URL with your API key and event parameters into your browser's address bar:

https://msggo.io/inbox?msggo-key=YOUR_API_KEY&event=your-event-name

Testing Through MsgGO UI

MsgGO provides a built-in testing feature in its interface. To send a test event:

  1. Go to the "Events" section in the left sidebar
  2. Find your event in the list
  3. Click on the 3 dots button on the right side and click “Send event”
  4. You can now:
    • Modify the test event data
    • Send the test event

This feature is particularly useful when you want to:

  • Verify your event configuration
  • Test your delivery target setup
  • Check message templates
  • Debug delivery issues

Code Examples

# GET
curl "https://msggo.io/inbox?msggo-key=YOUR_API_KEY&event=your-event-name"

# POST
curl -X POST "https://msggo.io/inbox" \
     -d '{"msggo-key":"YOUR_API_KEY","event":"your-event-name"}'

Best Practices

  • Use Appropriate API Key Type: Use Public API Keys for frontend applications and Private API Keys for backend services or secured environments.
  • Secure API Keys:
    • For Private API Keys: Never expose them in client-side code or public repositories. Use environment variables or secure credential management on your server.
    • For Public API Keys: Configure Allowed Domains meticulously. Regularly review and update these domains.
  • Use POST for Production Data: It is more secure (data is not in the URL, especially important for any potentially sensitive event data) and better suited for complex JSON structures.
  • Prefer API Key in Header: For both Public and Private keys, sending the API key in the X-MsgGO-Key header is a clean and standard approach.
  • Explicitly Set Content-Type: For POST requests, explicitly setting the Content-Type header (e.g., application/json) is recommended to avoid ambiguity.
  • Monitor Your Messages: Regularly check the Inbox section and event logs in MsgGO. Pay attention to any delivery errors or rate limit notifications.
  • Manage Rate Limits: Be aware of the rate limits for your chosen API key type and for delivery targets.

Common Questions

Q: Can I create custom delivery targets?

Currently, MsgGO supports a set of predefined delivery targets. We're constantly adding new integrations based on user needs.

Is there a limit to how many events I can create?

No practical limits exist. You can create tens of thousands of events and delivery targets.

Can I schedule events?

Events are processed immediately when received by MsgGO.