Delivering Events to MsgGO

Before You Start

You'll need:

• A MsgGO account
• An API key (How to generate an API key)
• At least one event created (How to create events)

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 example:

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

API Key as a Query Parameter

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 example:

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

API Key in POST Request Body

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 example (for application/json):

curl -X POST "<https://msggo.io/inbox>" \
     -d '{"msggo-key":"YOUR_API_KEY","event":"payment_processed","amount":100}'

curl example (for application/x-www-form-urlencoded):

curl -X POST "https://msggo.io/inbox" \
     -d "msggo-key=YOUR_API_KEY" \
     -d "event=form_submission" \
     -d "customer_id=123"

API Key in HTTP Headers (Recommended)

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

X-MsgGO-Key: YOUR_API_KEY

curl example:

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

Each method offers a different level of security. Sending the key in the request header or as part of the POST request body is generally considered more secure than including it directly in the URL.

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>

The above request will be interpreted by MsgGO as the following JSON event:

{
    "event": "contact-form",
    "name": "John Doe",
    "email": "john.doe@example.com"
}

Event Content as POST Request Fields (Form Data)

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"

MsgGO will convert this to:

{
    "event": "new_order",
    "product_id": "XYZ123",
    "quantity": "2" // Note: values from form data are typically strings
}

Event Content as JSON in POST Request

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%"
           }
         }'

Combining Query Parameters and POST Request Body

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.

When to Still Consider a Backend Proxy

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() 
});

const express = require('express');
const axios = require('axios');
const app = express();

app.use(express.json());

// Your secure backend proxy endpoint
app.post('/api/events', async (req, res) => {
  try {
    // Add your API key securely (stored in environment variables)
    const eventData = {
      'msggo-key': process.env.MSGGO_API_KEY,
      ...req.body
    };
    
    // Forward to MsgGO
    const response = await axios.post('https://msggo.io/inbox', eventData);
    
    res.json(response.data);
  } catch (error) {
    console.error('Error forwarding event to MsgGO:', error);
    res.status(500).json({ 
      error: 'Failed to process event',
      details: error.message
    });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/events', methods=['POST'])
def forward_event():
    try:
        # Get data from frontend request
        event_data = request.json
        
        # Add API key securely (stored in environment variables)
        event_data['msggo-key'] = os.environ.get('MSGGO_API_KEY')
        
        # Forward to MsgGO
        response = requests.post(
            'https://msggo.io/inbox',
            json=event_data,
        )
        
        # Return the response from MsgGO
        return jsonify(response.json()), response.status_code
        
    except Exception as e:
        return jsonify({
            'error': 'Failed to process event',
            'details': str(e)
        }), 500

if __name__ == '__main__':
    app.run(port=3000)

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

Common causes:

• 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"
}

Remember that MsgGO has a 10,000 character limit for messages. Larger payloads will be rejected with this error.

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

Press Enter, and you're done! If you receive a blank page with a 200 status code, your event was successfully delivered to MsgGO.

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"}'

import requests

# GET
response = requests.get('https://msggo.io/inbox', 
    params={'msggo-key': 'YOUR_API_KEY', 'event': 'your-event-name'})

# POST
response = requests.post('https://msggo.io/inbox', 
    json={'msggo-key': 'YOUR_API_KEY', 'event': 'your-event-name'})

// GET
file_get_contents('https://msggo.io/inbox?msggo-key=<your-api-key>&event=your-event-name')

// POST
$apiKey = '<your-api-key>';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'msggo-key' => $apiKey,
    'event'  => 'your-event-name'
]);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    // Handle the error
    echo 'Curl error: ' . curl_error($ch);
}

curl_close($ch);

// GET
fetch('https://msggo.io/inbox?msggo-key=YOUR_API_KEY&event=your-event-name')

// POST
fetch('https://msggo.io/inbox', {
    method: 'POST',
    body: JSON.stringify({
        '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