MailerPress public REST API

Authentication

applicationPassword http (basic)

WordPress Application Password (HTTP Basic Auth). Generate in Users > Profile.

apiKey apiKey

MailerPress API Key (starts with mpk_)

X-MailerPress-API-Key in header

apiSecret apiKey

MailerPress API Secret (starts with mps_)

X-MailerPress-API-Secret in header

Contacts

Contact management, notes, and statistics

GET /contacts/all List all contacts

Get paginated list of contacts with filtering and search

Parameters

Name	In	Type	Description
`paged`	query	`integer`	Page number
`perPages`	query	`integer`	Results per page
`search`	query	`string`	Search by email or contact ID
`subscription_status`	query	`string`	Filter by subscription status
`list`	query	`integer`	Filter by list ID
`tag`	query	`integer`	Filter by tag ID
`orderby`	query	`string`	Sort field
`order`	query	`string`	Sort direction

Responses

200Successful response

Property	Type	Description
`posts`	`array<Contact>`
`pages`	`integer`
`count`	`integer`

401Unauthorized – Authentication required

Property	Type	Description
`code`	`string`
`message`	`string`
`data`	`object`

POST /contact Create or update contact

Create a new contact or update existing one by email

Request Body required

Property	Type	Description
`email`*	`string`
`first_name`	`string`
`last_name`	`string`
`status`	`string` subscribed \| unsubscribed \| pending
`tags`	`array<object>`
`lists`	`array<object>`
`custom_fields`	`object`
`opt_in_source`	`string`	Default: `"api"`

Responses

200Contact created/updated successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`
`data`	`object`

400Bad Request – Invalid parameters

Property	Type	Description
`code`	`string`
`message`	`string`
`data`	`object`

DELETE /contact Delete contacts

Delete multiple contacts by IDs

Request Body required

Property	Type	Description
`ids`*	`array<integer>`

Responses

200Contacts deleted successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`
`deleted_count`	`integer`

PUT /contacts Bulk update contacts

Bulk update contacts (status, tags, lists, custom fields, profile data)

Request Body required

Property	Type	Description
`ids`	`array<integer>`
`newStatus`	`string` subscribed \| unsubscribed \| pending
`first_name`	`string`
`last_name`	`string`
`email`	`string`
`tags`	`array<object>`
`removeTags`	`array<object>`
`lists`	`array<object>`
`removeLists`	`array<object>`
`custom_fields`	`object`

Responses

200Contacts updated successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`

PUT /contact/{id} Update single contact

Update a single contact by ID

Parameters

Name	In	Type	Description
`id`*	path	`integer`

Request Body required

Property	Type	Description
`email`	`string`
`first_name`	`string`
`last_name`	`string`
`newStatus`	`string` subscribed \| unsubscribed \| pending
`tags`	`array<object>`
`removeTags`	`array<object>`
`lists`	`array<object>`
`removeLists`	`array<object>`
`custom_fields`	`object`

Responses

200Contact updated successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`

404Not Found – Resource not found

Property	Type	Description
`code`	`string`
`message`	`string`
`data`	`object`

GET /contact/{contact_id}/activity Get contact activity

Get activity history for a specific contact

Parameters

Name	In	Type	Description
`contact_id`*	path	`integer`
`page`	query	`integer`

Responses

200Contact activity list

GET /contact/{contact_id}/campaigns Get contact campaigns

Get campaigns associated with a specific contact

Parameters

Name	In	Type	Description
`contact_id`*	path	`integer`

Responses

200Campaigns associated with the contact

GET /stats/{contact_id} Get contact stats

Get email engagement statistics for a specific contact

Parameters

Name	In	Type	Description
`contact_id`*	path	`integer`
`campaign_id`	query	`integer`	Optional campaign ID to filter stats

Responses

200Contact engagement statistics

Property	Type	Description
`total_opened`	`integer`
`total_clicked`	`integer`
`total_unsubscribed`	`integer`

GET /contact-note/{contact_id} Get contact notes

Get all notes for a specific contact

Parameters

Name	In	Type	Description
`contact_id`*	path	`integer`

Responses

200Contact notes

Property	Type	Description
`success`	`boolean`
`notes`	`array<ContactNote>`

POST /contact/note Create contact note

Add a note to a contact

Request Body required

Property	Type	Description
`contact_id`*	`integer`
`content`*	`string`

Responses

200Note created successfully

Property	Type	Description
`success`	`boolean`
`note`	`ContactNote`

PUT /contact/note/{note_id} Update contact note

Update an existing contact note

Parameters

Name	In	Type	Description
`note_id`*	path	`integer`

Request Body required

Property	Type	Description
`content`*	`string`

Responses

200Note updated successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`

DELETE /contact/note/{note_id} Delete contact note

Delete a contact note

Parameters

Name	In	Type	Description
`note_id`*	path	`integer`

Responses

200Note deleted successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`

GET /contact/check-email Check email existence

Check if an email address already exists in contacts

Parameters

Name	In	Type	Description
`email`*	query	`string`
`exclude_id`	query	`integer`	Contact ID to exclude from the check

Responses

200Email check result

Property	Type	Description
`exists`	`boolean`

POST /contact/export Export contacts

Export contacts to a downloadable file

Request Body required

Property	Type	Description
`contact_ids`	`array<integer>`
`email`	`string`	Email to send the export link to

Responses

200Export initiated successfully

Campaigns

Campaign management, sending, and analytics

GET /campaigns List campaigns

Get paginated list of campaigns with filtering

Parameters

Name	In	Type	Description
`paged`	query	`integer`
`perPages`	query	`integer`
`search`	query	`string`	Search by campaign name
`status`	query	`string`	Filter by status (comma-separated)
`campaign_type`	query	`string`	Filter by campaign type
`orderby`	query	`string`
`order`	query	`string`

Responses

200Successful response

Property	Type	Description
`posts`	`array<Campaign>`
`pages`	`integer`
`count`	`integer`

POST /campaigns Create campaign

Create a new campaign

Request Body required

Property	Type	Description
`title`*	`string`
`campaign_type`	`string` newsletter \| automated \| automation \| wp_email \| wc_email	Default: `"newsletter"`
`meta`	`object`
`automation_id`	`integer`
`step_id`	`integer`

Responses

200Campaign created successfully

Property	Type	Description
`success`	`boolean`
`id`	`integer`
`message`	`string`

GET /campaign/{id} Get campaign

Get a single campaign by ID

Parameters

Name	In	Type	Description
`id`*	path	`integer`

Responses

200Campaign data

Property	Type	Description
`campaign_id`	`integer`
`name`	`string`
`subject`	`string`
`status`	`string`
`campaign_type`	`string`
`content_html`	`string`
`config`	`object`
`created_at`	`string`
`updated_at`	`string`

404Not Found – Resource not found

Property	Type	Description
`code`	`string`
`message`	`string`
`data`	`object`

PUT /campaign/{id} Update campaign

Update a campaign's title and metadata

Parameters

Name	In	Type	Description
`id`*	path	`integer`

Request Body

Property	Type	Description
`title`	`string`
`meta`	`object`

Responses

200Campaign updated successfully

DELETE /campaign Delete campaigns

Delete multiple campaigns by IDs

Request Body required

Property	Type	Description
`ids`*	`array<integer>`

Responses

200Campaigns deleted successfully

Property	Type	Description
`success`	`boolean`
`deleted_count`	`integer`

GET /campaign-status Get campaign status

Get status and statistics for one or more campaigns

Parameters

Name	In	Type	Description
`ids`*	query	`array`	Campaign IDs (array)

Responses

200Campaign status data

PUT /campaign/{id}/rename Rename campaign

Rename a campaign

Parameters

Name	In	Type	Description
`id`*	path	`integer`

Request Body required

Property	Type	Description
`title`*	`string`

Responses

200Campaign renamed successfully

PUT /campaign/status Update campaign status

Change the status of a campaign (draft, trash, etc.)

Request Body required

Property	Type	Description
`id`*	`integer`
`status`*	`string`

Responses

200Status updated successfully

POST /campaign/send_test Send test email

Send a test email for a campaign

Request Body required

Property	Type	Description
`contacts`*	`array<string>`
`htmlContent`*	`string`
`subject`*	`string`

Responses

200Test email sent successfully

POST /campaign/count-audience Count audience

Count potential recipients based on targeting criteria

Request Body required

Property	Type	Description
`tags`	`array<integer>`
`lists`	`array<integer>`
`recipientTargeting`	`string`
`segment`	`object`

Responses

200Audience count

GET /campaign/batches Get campaign batches

Get send batches for a campaign

Parameters

Name	In	Type	Description
`id`*	query	`integer`	Campaign ID
`paged`	query	`integer`
`perPage`	query	`integer`

Responses

200Campaign batches

Property	Type	Description
`batches`	`array`
`count`	`integer`
`pages`	`integer`

GET /batch-opened-contacts Get contacts who opened

Get paginated list of contacts who opened a batch email

Parameters

Name	In	Type
`batch_id`*	query	`integer`
`search`	query	`string`
`paged`	query	`integer`
`perPage`	query	`integer`

Responses

200Contacts who opened

Property	Type	Description
`posts`	`array`
`count`	`integer`
`identified_count`	`integer`
`anonymous_count`	`integer`
`pages`	`integer`

GET /batch-clicked-contacts Get contacts who clicked

Get paginated list of contacts who clicked a link in a batch email

Parameters

Name	In	Type
`batch_id`*	query	`integer`
`search`	query	`string`
`paged`	query	`integer`
`perPage`	query	`integer`

Responses

200Contacts who clicked

Property	Type	Description
`posts`	`array`
`count`	`integer`
`identified_count`	`integer`
`anonymous_count`	`integer`
`pages`	`integer`

GET /batch-unsubscribed-contacts Get contacts who unsubscribed

Get paginated list of contacts who unsubscribed from a batch email

Parameters

Name	In	Type
`batch_id`*	query	`integer`
`search`	query	`string`
`paged`	query	`integer`
`perPage`	query	`integer`

Responses

200Contacts who unsubscribed

Property	Type	Description
`posts`	`array`
`count`	`integer`
`identified_count`	`integer`
`anonymous_count`	`integer`
`pages`	`integer`

GET /campaigns/{id}/logs Get campaign logs

Get send logs for a campaign

Parameters

Name	In	Type
`id`*	path	`integer`
`page`	query	`integer`
`per_page`	query	`integer`
`status`	query	`string`

Responses

200Campaign send logs

Lists

Contact list management

GET /list List all lists

Get paginated list of contact lists

Parameters

Name	In	Type
`paged`	query	`integer`
`perPages`	query	`integer`
`search`	query	`string`
`orderby`	query	`string`
`order`	query	`string`

Responses

200Successful response

Property	Type	Description
`posts`	`array<ContactList>`
`pages`	`integer`
`count`	`integer`

POST /list Create list

Create a new contact list

Request Body required

Property	Type	Description
`title`*	`string`
`description`	`string`

Responses

200List created successfully

Property	Type	Description
`id`	`integer`
`label`	`string`
`description`	`string`
`is_default`	`integer`

DELETE /list Delete lists

Delete multiple lists by IDs

Request Body required

Property	Type	Description
`ids`*	`array<integer>`

Responses

200Lists deleted successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`
`deleted_count`	`integer`

GET /list/all Get all lists (no pagination)

Get all contact lists without pagination

Responses

200All lists

PUT /list/{id}/rename Rename list

Rename a contact list

Parameters

Name	In	Type	Description
`id`*	path	`integer`

Request Body required

Property	Type	Description
`title`*	`string`
`description`	`string`

Responses

200List renamed successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`
`list_id`	`integer`

PUT /list/{id}/set-default Set default list

Set a list as the default contact list

Parameters

Name	In	Type	Description
`id`*	path	`integer`

Responses

200Default list updated

Property	Type	Description
`success`	`boolean`
`message`	`string`
`list_id`	`integer`

API Keys

API key management and permissions

GET /api-keys List API keys

Get paginated list of API keys

Parameters

Name	In	Type
`paged`	query	`integer`
`perPages`	query	`integer`
`search`	query	`string`
`status`	query	`string`
`orderby`	query	`string`
`order`	query	`string`

Responses

200API keys list

Property	Type	Description
`posts`	`array<ApiKey>`
`count`	`integer`
`page`	`integer`
`pages`	`integer`

POST /api-keys Create API key

Create a new API key. The key and secret are only shown once in the response.

Request Body required

Property	Type	Description
`name`*	`string`
`description`	`string`
`permissions`	`array<string>`
`rate_limit_requests`	`integer`	Default: `1000`
`rate_limit_window`	`integer`	Default: `3600`
`allowed_ips`	`array<string>`
`expires_in_days`	`integer`	Default: `0`

Responses

201API key created successfully

Property	Type	Description
`success`	`boolean`
`message`	`string`
`key_id`	`integer`
`api_key`	`string`
`api_secret`	`string`
`name`	`string`
`expires_at`	`string`

PUT /api-keys/{key_id} Update API key

Update an API key's settings

Parameters

Name	In	Type	Description
`key_id`*	path	`integer`

Request Body

Property	Type	Description
`name`	`string`
`description`	`string`
`permissions`	`array<string>`
`rate_limit_requests`	`integer`
`rate_limit_window`	`integer`
`allowed_ips`	`array<string>`

Responses

200API key updated

Property	Type	Description
`success`	`boolean`
`message`	`string`

DELETE /api-keys/{key_id} Revoke API key

Revoke (soft delete) an API key. Use /api-keys/{key_id}/delete for permanent deletion.

Parameters

Name	In	Type	Description
`key_id`*	path	`integer`

Responses

200API key revoked

Property	Type	Description
`success`	`boolean`
`message`	`string`

POST /api-keys/{key_id}/reactivate Reactivate API key

Reactivate a previously revoked API key

Parameters

Name	In	Type	Description
`key_id`*	path	`integer`

Responses

200API key reactivated

Property	Type	Description
`success`	`boolean`
`message`	`string`

DELETE /api-keys/{key_id}/delete Permanently delete API key

Permanently delete an API key (cannot be undone)

Parameters

Name	In	Type	Description
`key_id`*	path	`integer`

Responses

200API key permanently deleted

Property	Type	Description
`success`	`boolean`
`message`	`string`

GET /api-keys/{key_id}/stats Get API key stats

Get usage statistics for an API key

Parameters

Name	In	Type	Description
`key_id`*	path	`integer`

Responses

200API key usage statistics

Property	Type	Description
`key_id`	`integer`
`name`	`string`
`status`	`string`
`request_count`	`integer`
`last_used_at`	`string`
`created_at`	`string`
`rate_limit`	`object`

GET /api-keys/permissions List available permissions

Get all available API key permissions

Responses

200Available permissions

Property	Type	Description
`permissions`	`array<Permission>`

Custom Fields

Contact custom field definitions

GET /custom-fields List custom field definitions

Get all custom field definitions for contacts

Responses

200Custom field definitions

Property	Type	Description
`success`	`boolean`
`fields`	`array<object>`

Schemas

Contact

Property	Type	Description
`contact_id`	`integer`
`id`	`integer`
`email`	`string`
`first_name`	`string`
`last_name`	`string`
`subscription_status`	`string` subscribed \| unsubscribed \| pending
`created_at`	`string`
`updated_at`	`string`
`tags`	`array<object>`
`contact_lists`	`array<object>`
`custom_fields`	`array<object>`

CreateContactRequest

Property	Type	Description
`email`*	`string`
`first_name`	`string`
`last_name`	`string`
`status`	`string` subscribed \| unsubscribed \| pending
`tags`	`array<object>`
`lists`	`array<object>`
`custom_fields`	`object`
`opt_in_source`	`string`	Default: `"api"`

UpdateContactsRequest

Property	Type	Description
`ids`	`array<integer>`
`newStatus`	`string` subscribed \| unsubscribed \| pending
`first_name`	`string`
`last_name`	`string`
`email`	`string`
`tags`	`array<object>`
`removeTags`	`array<object>`
`lists`	`array<object>`
`removeLists`	`array<object>`
`custom_fields`	`object`

ContactNote

Property	Type	Description
`id`	`integer`
`contact_id`	`integer`
`content`	`string`
`created_at`	`string`
`updated_at`	`string`

Campaign

Property	Type	Description
`id`	`integer`
`campaign_id`	`integer`
`name`	`string`
`subject`	`string`
`status`	`string` draft \| sent \| scheduled \| sending \| error \| trash
`campaign_type`	`string` newsletter \| automated \| automation \| wp_email \| wc_email
`created_at`	`string`
`updated_at`	`string`

CampaignDetail

Property	Type	Description
`campaign_id`	`integer`
`name`	`string`
`subject`	`string`
`status`	`string`
`campaign_type`	`string`
`content_html`	`string`
`config`	`object`
`created_at`	`string`
`updated_at`	`string`

CampaignStatus

Property	Type	Description
`campaign_id`	`integer`
`title`	`string`
`subject`	`string`
`status`	`string`
`batch`	`object`
`statistics`	`object`

ContactList

Property	Type	Description
`list_id`	`integer`
`id`	`integer`
`name`	`string`
`description`	`string`
`is_default`	`integer` 0 \| 1
`contact_count`	`integer`
`created_at`	`string`

Tag

Property	Type	Description
`tag_id`	`integer`
`name`	`string`
`created_at`	`string`

ApiKey

Property	Type	Description
`key_id`	`integer`
`name`	`string`
`description`	`string`
`permissions`	`array<string>`
`status`	`string` active \| revoked \| expired
`rate_limit_requests`	`integer`
`rate_limit_window`	`integer`
`allowed_ips`	`array<string>`
`request_count`	`integer`
`last_used_at`	`string`
`expires_at`	`string`
`created_at`	`string`
`updated_at`	`string`

CreateApiKeyRequest

Property	Type	Description
`name`*	`string`
`description`	`string`
`permissions`	`array<string>`
`rate_limit_requests`	`integer`	Default: `1000`
`rate_limit_window`	`integer`	Default: `3600`
`allowed_ips`	`array<string>`
`expires_in_days`	`integer`	Default: `0`

CreateApiKeyResponse

Property	Type	Description
`success`	`boolean`
`message`	`string`
`key_id`	`integer`
`api_key`	`string`
`api_secret`	`string`
`name`	`string`
`expires_at`	`string`

UpdateApiKeyRequest

Property	Type	Description
`name`	`string`
`description`	`string`
`permissions`	`array<string>`
`rate_limit_requests`	`integer`
`rate_limit_window`	`integer`
`allowed_ips`	`array<string>`

Permission

Property	Type	Description
`id`	`string`
`name`	`string`
`description`	`string`

Error

Property	Type	Description
`code`	`string`
`message`	`string`
`data`	`object`