API for subscribing to an email list

📬 The Subscription Api, version 2.0

 

Want to grow your audience lists automatically? Our Subscription API makes it super simple to collect new subscribers and keep your lists fresh.

Whether you're adding someone for the first time or updating existing details, here’s how to make it happen.

 

🔐 Step 1: Get Your Api Key

Before anything else, you’ll need an Api key to authenticate your requests.
Already have one? Great! Copy it to your clipboard.
Need one? You can generate it by heading over to Settings → Api Keys → Create New Api Key.

 

📨 Step 2: Add Your Api Key to the Request Header

When you’re ready to make your request, add your Api key into the header like this:

x-api-key: xxxx-xxxx-xxxx-xxxx
📋 Copy

 

🚀 Step 3: Send a POST Request to this endpoint

You’ll be sending a POST request to:

https://inbound.messengeros.com/2.0/subscribe
📋 Copy

This is where the magic happens ✨

 

🧱 Step 4: Build your Payload

Here’s the format your JSON payload should follow:
Mandatory fields: email or phone_number. 
{
    "project": "xxxxxx-xxxxxx-xxxx-xxxxx-xxxxxxxxx", // optional (if missing the default project will be used), can be found in Settings / Projects / Edit / Show Api Key
    "subscription": [
        {
            "email": "subscriber@example.com", // optional if phone_number is present, otherwise mandatory. The subscriber's email address
            "phone_number": "123456789", // optional if email is present, otherwise mandatory. The subscriber's phone number
            "name": "Subscriber's full name (First name + Last name) or Company name", // optional, if you want to add the subscriber's full name or company name
            "first_name": "Subscriber's first name", // optional, if you want to add the subscriber's first and last name separately
            "last_name": "Subscriber's last name", // optional, if you want to add the subscriber's first and last name separately
            "unsubscribed_from_all": 1, // optional, can be 0 or 1, if you want to unsubscribe or re-subscribe a recipient's email and/or phone number
            "distribution_lists": [ // optional (if missing the default list from the project will be used)
                "xxxxxx-xxxxxx-xxxx-xxxxx-xxxxxxxxx", // optional , if you want to add the subscriber to a specific distribution list - can be found in Audience / Lists / View list / Show Api Key
                "xxxxxx-xxxxxx-xxxx-xxxxx-xxxxxxxxx" // optional, if you want to add the subscriber to a another specific distribution list - can be found in Audience / Lists / View list / Show Api Key
            ],
            "custom_info": [
                {"key1":"value1"}, // optional, if you want to add custom information about the subscriber
                {"key2":"value2"} // optional, if you want to add more custom information about the subscriber
            ]
        }
    ]
}
📋 Copy

📌 Pro tip: You can add a single subscriber or multiple at once. Just repeat the object inside the subscription array.

 

✅ Step 5: Get a Confirmation

If everything looks good and your JSON is valid, the Api will respond with: 

{"status": "received"}

This means we’ve accepted the request and your subscriber is being processed in the background.

 

👀 Step 6: Double check in your Audience lists

Once your request goes through, head over to your Audience → Lists to confirm that your new subscriber has been added to the list(s) you specified in distribution_lists.
That’s it! 🎉 You’re now ready to welcome new subscribers with open arms.

Need help or want to test it out? Let us know—we’re always here to support.

© MessengerOS