Email Campaigns API

Create and manage email marketing campaigns for your store.

Feature Requirement

Email campaigns require the email_marketing feature enabled on your plan.

List Campaigns

http

GET /api/external/v1/email-campaigns

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter: `draft`, `scheduled`, `sending`, `sent`, `cancelled`
`from`	string	Start date (YYYY-MM-DD)
`to`	string	End date (YYYY-MM-DD)

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/email-campaigns?status=sent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Summer Sale Announcement",
      "subject": "Exclusive 25% Off - Summer Sale Now Live!",
      "status": "sent",
      "recipient_type": "all_customers",
      "from_name": "GameStore",
      "from_email": "noreply@gamestore.com",
      "recipients_count": 1250,
      "opens_count": 487,
      "clicks_count": 156,
      "bounces_count": 12,
      "unsubscribes_count": 3,
      "open_rate": 38.96,
      "click_rate": 12.48,
      "bounce_rate": 0.96,
      "unsubscribe_rate": 0.24,
      "scheduled_at": null,
      "sent_at": "2025-01-15T14:00:00Z",
      "created_at": "2025-01-14T10:30:00Z",
      "updated_at": "2025-01-15T14:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 52
  }
}

Get Single Campaign

http

GET /api/external/v1/email-campaigns/{id}

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Summer Sale Announcement",
    "subject": "Exclusive 25% Off - Summer Sale Now Live!",
    "content": "<html>...</html>",
    "status": "sent",
    "recipient_type": "all_customers",
    "recipient_filters": null,
    "from_name": "GameStore",
    "from_email": "noreply@gamestore.com",
    "recipients_count": 1250,
    "opens_count": 487,
    "clicks_count": 156,
    "bounces_count": 12,
    "unsubscribes_count": 3,
    "open_rate": 38.96,
    "click_rate": 12.48,
    "bounce_rate": 0.96,
    "unsubscribe_rate": 0.24,
    "scheduled_at": null,
    "sent_at": "2025-01-15T14:00:00Z",
    "created_at": "2025-01-14T10:30:00Z",
    "updated_at": "2025-01-15T14:00:00Z",
    "recipient_summary": {
      "total": 1250,
      "sent": 1238,
      "opened": 487,
      "clicked": 156,
      "bounced": 12,
      "unsubscribed": 3
    }
  }
}

Create Campaign

http

POST /api/external/v1/email-campaigns

Request Body

Field	Type	Required	Description
`name`	string	Yes	Campaign name (max 255 chars)
`subject`	string	Conditional	Email subject line (required if no template_id)
`content`	string	Conditional	HTML email content (required if no template_id)
`from_name`	string	Yes	Sender display name
`from_email`	string	Yes	Sender email address
`recipient_type`	string	Yes	`all_customers`, `segment`, or `custom_list`
`recipient_filters`	object	No	Filters when using `segment` type
`template_id`	integer	No	Use existing email template

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/email-campaigns" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Product Launch",
    "subject": "Introducing Our Latest Ranks!",
    "content": "<html><body><h1>New Ranks Available!</h1><p>Check out our new VIP+ rank with exclusive perks.</p></body></html>",
    "from_name": "GameStore",
    "from_email": "noreply@gamestore.com",
    "recipient_type": "all_customers"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": 2,
    "name": "New Product Launch",
    "subject": "Introducing Our Latest Ranks!",
    "status": "draft",
    "recipient_type": "all_customers",
    "from_name": "GameStore",
    "from_email": "noreply@gamestore.com",
    "recipients_count": 0,
    "opens_count": 0,
    "clicks_count": 0,
    "bounces_count": 0,
    "unsubscribes_count": 0,
    "created_at": "2025-01-20T15:00:00Z",
    "updated_at": "2025-01-20T15:00:00Z"
  },
  "message": "Campaign created successfully"
}

Using Templates

You can use a pre-defined email template instead of specifying content:

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/email-campaigns" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Newsletter",
    "from_name": "GameStore",
    "from_email": "noreply@gamestore.com",
    "recipient_type": "all_customers",
    "template_id": 5
  }'

Recipient Filters

When using recipient_type: "segment", you can specify filters:

json

{
  "name": "VIP Customer Exclusive",
  "subject": "Special Offer for Our VIP Customers",
  "content": "<html>...</html>",
  "from_name": "GameStore",
  "from_email": "noreply@gamestore.com",
  "recipient_type": "segment",
  "recipient_filters": {
    "total_spent_min": 100,
    "has_purchased": true,
    "last_order_days": 30
  }
}

Update Campaign

Update a draft or scheduled campaign.

http

PUT /api/external/v1/email-campaigns/{id}

Note

Only campaigns with draft or scheduled status can be updated.

Request Body

Field	Type	Required	Description
`name`	string	No	Campaign name
`subject`	string	No	Email subject line
`content`	string	No	HTML email content
`from_name`	string	No	Sender display name
`from_email`	string	No	Sender email address
`recipient_type`	string	No	`all_customers`, `segment`, or `custom_list`
`recipient_filters`	object	No	Filters when using `segment` type

Example Request

bash

curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated: Introducing Our Latest Ranks!",
    "content": "<html><body><h1>New Ranks Available!</h1><p>Updated content with more details.</p></body></html>"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": 2,
    "name": "New Product Launch",
    "subject": "Updated: Introducing Our Latest Ranks!",
    "status": "draft",
    "updated_at": "2025-01-20T16:00:00Z"
  },
  "message": "Campaign updated successfully"
}

Send Campaign

Send a campaign immediately or schedule it for later.

http

POST /api/external/v1/email-campaigns/{id}/send

Request Body

Field	Type	Required	Description
`scheduled_at`	string	No	ISO 8601 datetime to schedule (must be in future)
`test_email`	string	No	Send test email to this address instead of full send
`force`	boolean	No	Skip content validation warnings

Send Immediately

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/2/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 2,
    "name": "New Product Launch",
    "status": "sending",
    "sent_at": "2025-01-20T16:30:00Z"
  },
  "message": "Campaign is being sent"
}

Schedule for Later

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/2/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2025-01-25T10:00:00Z"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": 2,
    "name": "New Product Launch",
    "status": "scheduled",
    "scheduled_at": "2025-01-25T10:00:00Z"
  },
  "message": "Campaign scheduled for 2025-01-25 10:00:00"
}

Send Test Email

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/2/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "test_email": "test@example.com"
  }'

Response

json

{
  "success": true,
  "message": "Test email sent successfully"
}

Content Validation Warnings

If the content contains potential spam triggers, you'll receive warnings:

json

{
  "success": false,
  "warnings": [
    "Subject line contains excessive punctuation",
    "Content contains commonly blocked phrases"
  ],
  "message": "Content validation warnings found. Send with force=true to ignore."
}

To proceed anyway, add force: true to the request.

Get Campaign Stats

Get detailed statistics for a campaign.

http

GET /api/external/v1/email-campaigns/{id}/stats

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/1/stats" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "campaign_id": 1,
    "name": "Summer Sale Announcement",
    "status": "sent",
    "sent_at": "2025-01-15T14:00:00Z",
    "delivery": {
      "total": 1250,
      "sent": 1238,
      "failed": 12,
      "delivery_rate": 99.04
    },
    "engagement": {
      "opens": 487,
      "unique_opens": 423,
      "open_rate": 38.96,
      "clicks": 156,
      "unique_clicks": 134,
      "click_rate": 12.48,
      "click_to_open_rate": 32.03
    },
    "negative": {
      "bounces": 12,
      "bounce_rate": 0.96,
      "unsubscribes": 3,
      "unsubscribe_rate": 0.24,
      "spam_complaints": 0
    },
    "timeline": {
      "first_open": "2025-01-15T14:02:15Z",
      "last_open": "2025-01-18T09:45:00Z",
      "first_click": "2025-01-15T14:05:30Z",
      "last_click": "2025-01-17T21:15:00Z"
    }
  }
}

Delete Campaign

Delete a campaign. Cannot delete campaigns that are currently being sent.

http

DELETE /api/external/v1/email-campaigns/{id}

Example Request

bash

curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/2" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

json

{
  "success": true,
  "message": "Campaign deleted successfully"
}

Duplicate Campaign

Create a copy of an existing campaign.

http

POST /api/external/v1/email-campaigns/{id}/duplicate

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/1/duplicate" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

json

{
  "success": true,
  "data": {
    "id": 3,
    "name": "Summer Sale Announcement (Copy)",
    "status": "draft",
    "created_at": "2025-01-20T17:00:00Z"
  },
  "message": "Campaign duplicated successfully"
}

Preview Recipients

Preview the recipients list before sending.

http

GET /api/external/v1/email-campaigns/{id}/preview-recipients

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/email-campaigns/2/preview-recipients" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "total_recipients": 1250,
    "sample_recipients": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
      },
      {
        "id": 2,
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    ]
  }
}

Campaign Object

Field	Type	Description
`id`	integer	Unique identifier
`name`	string	Campaign name
`subject`	string	Email subject line
`content`	string	HTML email content
`status`	string	`draft`, `scheduled`, `sending`, `sent`, `cancelled`
`recipient_type`	string	`all_customers`, `segment`, `custom_list`
`recipient_filters`	object	Filters for segment targeting
`from_name`	string	Sender display name
`from_email`	string	Sender email address
`recipients_count`	integer	Total recipients
`opens_count`	integer	Total opens
`clicks_count`	integer	Total clicks
`bounces_count`	integer	Total bounces
`unsubscribes_count`	integer	Total unsubscribes
`open_rate`	float	Percentage of recipients who opened
`click_rate`	float	Percentage of recipients who clicked
`bounce_rate`	float	Percentage of bounced emails
`unsubscribe_rate`	float	Percentage who unsubscribed
`scheduled_at`	string	ISO 8601 scheduled send time
`sent_at`	string	ISO 8601 actual send time
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

Campaign Statuses

Status	Description
`draft`	Campaign is being created, not yet sent
`scheduled`	Campaign is scheduled for future delivery
`sending`	Campaign is currently being delivered
`sent`	Campaign has been fully delivered
`cancelled`	Campaign was cancelled before sending

Recipient Types

Type	Description
`all_customers`	Send to all customers who have not unsubscribed
`segment`	Send to customers matching filter criteria
`custom_list`	Send to a custom uploaded list

Merge Tags

Use these tags in your email content for personalization:

Tag	Description
`{customer_name}`	Customer's full name
`{customer_email}`	Customer's email address
`{store_name}`	Your store name
`{store_url}`	Your store URL
`{unsubscribe_link}`	Link to unsubscribe

Example Content

html

<html>
<body>
  <h1>Hello, {customer_name}!</h1>
  <p>Thank you for shopping at {store_name}.</p>
  <p>Visit us at <a href="{store_url}">{store_url}</a></p>
  <hr>
  <small><a href="{unsubscribe_link}">Unsubscribe</a></small>
</body>
</html>

Errors

Status	Error	Description
401	Unauthorized	Invalid or missing token
403	Forbidden	Token lacks `email_campaigns:read` or `email_campaigns:write` scope
403	Campaign cannot be edited	Campaign status doesn't allow editing
403	Cannot delete sending campaign	Campaign is currently being sent
404	Not Found	Campaign doesn't exist
422	Validation Error	Invalid request parameters
422	Content warnings	Email content has potential issues

Email Campaigns API ​

List Campaigns ​

Query Parameters ​

Example Request ​

Response ​

Get Single Campaign ​

Example Request ​

Response ​

Create Campaign ​

Request Body ​

Example Request ​

Response ​

Using Templates ​

Recipient Filters ​

Update Campaign ​

Request Body ​

Example Request ​

Response ​

Send Campaign ​

Request Body ​

Send Immediately ​

Response ​

Schedule for Later ​

Response ​

Send Test Email ​

Response ​

Content Validation Warnings ​

Get Campaign Stats ​

Example Request ​

Response ​

Delete Campaign ​

Example Request ​

Response ​

Duplicate Campaign ​

Example Request ​

Response ​

Preview Recipients ​

Example Request ​

Response ​

Campaign Object ​

Campaign Statuses ​

Recipient Types ​

Merge Tags ​

Example Content ​

Errors ​

Email Campaigns API

List Campaigns

Query Parameters

Example Request

Response

Get Single Campaign

Example Request

Response

Create Campaign

Request Body

Example Request

Response

Using Templates

Recipient Filters

Update Campaign

Request Body

Example Request

Response

Send Campaign

Request Body

Send Immediately

Response

Schedule for Later

Response

Send Test Email

Response

Content Validation Warnings

Get Campaign Stats

Example Request

Response

Delete Campaign

Example Request

Response

Duplicate Campaign

Example Request

Response

Preview Recipients

Example Request

Response

Campaign Object

Campaign Statuses

Recipient Types

Merge Tags

Example Content

Errors