Sending Email Campaigns via API

The MailHub module allows you to send previously configured email campaigns via API. This feature is useful for triggering campaigns automatically after specific events in your application, such as purchase completions, registrations, etc.

Requirements

To use this feature, you need to:

1. Create an email campaign in the admin panel.
2. Configure the campaign with the desired template and mark it with the "Ready" status.
3. Obtain the campaign UUID (available in the campaign list).
4. Have a valid API key for authentication.

Request

POST /api/mailhub/campaigns/send
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
    "campaign_uuid": "campaign-uuid-here",
    "recipients": [
        {
            "email": "recipient@example.com",
            "name": "Recipient Name"
        },
        {
            "email": "another@example.com",
            "name": "Another Recipient"
        }
    ]
}

Parameters

Parameter	Type	Description
campaign_uuid	string	UUID of the campaign to be sent
recipients	array	List of recipients
email	string	Recipient's email
name	string	Recipient's name (optional)

Success Response

{
    "success": true,
    "message": "Campaign sent",
    "data": {
        "campaign_uuid": "campaign-uuid-here",
        "campaign_name": "Campaign Name",
        "results": {
            "sent": [
                {
                    "email": "recipient@example.com",
                    "name": "Recipient Name"
                }
            ],
            "skipped": [
                {
                    "email": "another@example.com",
                    "name": "Another Recipient",
                    "reason": "Already sent"
                }
            ]
        },
        "sent_count": 1,
        "skipped_count": 1
    }
}

Duplicate Control

The system keeps a record of which campaigns have been sent to which recipients. This ensures that even if the API is called multiple times with the same data, each recipient will receive the campaign only once.

When a recipient has already received the campaign previously, they are included in the skipped list with the reason Already sent.

Campaign Status

A campaign can only be sent via API if it has the "Ready" status. Otherwise, the API will return an error indicating that the campaign is not ready for sending.

Error - Campaign Not Ready

{
    "success": false,
    "message": "Campaign is not ready for sending",
    "data": {
        "current_status": "draft",
        "campaign_uuid": "campaign-uuid-here"
    }
}

Error - Campaign Not Found

{
    "success": false,
    "message": "Campaign not found"
}

Notes

• Recipients who have unsubscribed will not receive the campaign, even if included in the recipient list.
• If a recipient does not exist in the system, they will be created automatically.
• The email will be sent using the SMTP configuration associated with the campaign.