REST API of MailerPress, the email marketing plugin for WordPress. Every endpoint accepts a WordPress Application Password; the endpoints of the free plugin also accept an API key, limited to the scopes it was given. The Pro endpoints (segments, webhooks, A/B tests, resends, custom field management) accept Application Passwords only.
Authentication
applicationPasswordHTTP basicWordPress Application Password (HTTP Basic). Generated under Users > Profile. Works on every endpoint, with the capabilities of the user.
apiKeyAPI key in theX-MailerPress-API-KeyheaderMailerPress API key (starts with mpk_), sent with its secret. Limited to the scopes it was given (see GET /api-keys/permissions); rate-limited per key, with 429 and Retry-After when exceeded. Not accepted by the Pro endpoints.
apiSecretAPI key in theX-MailerPress-API-SecretheaderMailerPress API secret (starts with mps_), always sent with the key.
Contacts
Contacts, their notes, activity and statistics
GET /contacts/all List contacts
/contacts/all List contactsReturns a paginated list of contacts with their tags, lists, custom fields and engagement totals.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch by email or contact ID
subscription_statusstring queryFilter by subscription status
One of:
subscribed,unsubscribed,pendinglistarray<object> queryFilter by lists: objects holding an `id`
Child attributes
idinteger
tagarray<object> queryFilter by tags: objects holding an `id`
Child attributes
idinteger
segmentarray<object> queryPro — filter by segments: objects holding an `id`
Child attributes
idinteger
engagementstring queryFilter by engagement level
One of:
engaged,unengaged,inactivecustom_fieldsobject queryFilter by custom field values, keyed by field key
orderbystring querySort field
orderstring querySort direction
One of:
ASC,DESCDefault:DESC
Responses
GET /contacts List contacts of given tags and lists
/contacts List contacts of given tags and listsReturns, without pagination, the contacts that belong to the given tags and lists.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
tagsarray<integer> queryTag ids
listsarray<integer> queryList ids
Responses
PUT /contacts Update contacts in bulk
/contacts Update contacts in bulkUpdates several contacts at once: status, tags, lists, custom fields, profile data.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
idsarray<integer>Contact ids to update; with `newStatus` alone, all contacts when empty
newStatusstringOne of:
subscribed,unsubscribed,pendingemailstring (email)first_namestringlast_namestringtagsarray<object>Child attributes
idinteger
removeTagsarray<object>Child attributes
idinteger
listsarray<object>Child attributes
idinteger
removeListsarray<object>Child attributes
idinteger
custom_fieldsarray<object>Child attributes
field_keystringfield_valuestring
Responses
POST /contact Create or update a contact
/contact Create or update a contactCreates a contact, or updates the one that already has this email. Also the endpoint the subscription forms post to: with an API key the `contacts:write` scope is required, and the submission is trusted (no double opt-in, fields overwritten). Rate-limited per IP.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
emailstring (email) requiredfirst_namestringlast_namestringsubscription_statusstringOne of:
subscribed,unsubscribed,pendingtagsarray<object>Objects holding a tag `id`
Child attributes
idinteger
listsarray<object>Objects holding a list `id`; the default list when empty
Child attributes
idinteger
custom_fieldsobjectValues keyed by field key
opt_in_sourcestringDefault:
unknownoptin_detailsstringlangstringLanguage code, for multilingual sites
Responses
200 Contact created or updated
successbooleanmessagestringcontact_idintegerdataobject
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
429 Too many requests — the rate limit of the API key is exceeded; Retry-After gives the seconds to wait
DELETE /contact Delete contacts
/contact Delete contactsDeletes the given contacts and everything attached to them.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
idsarray<integer> required
Responses
PUT /contact/{id} Update a contact
/contact/{id} Update a contactUpdates one contact by id.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
idinteger path required
Request body required
emailstring (email)first_namestringlast_namestringnewStatusstringOne of:
subscribed,unsubscribed,pendingtagsarray<object>Child attributes
idinteger
removeTagsarray<object>Child attributes
idinteger
listsarray<object>Child attributes
idinteger
removeListsarray<object>Child attributes
idinteger
custom_fieldsarray<object>Child attributes
field_keystringfield_valuestring
Responses
DELETE /contact/all Delete every contact
/contact/all Delete every contactDeletes all contacts. Above 20 000 contacts the deletion runs in the background and a batch id is returned.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Responses
DELETE /contact/list/{id} Remove a contact from a list
/contact/list/{id} Remove a contact from a listDetaches a list from a contact.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
idinteger path requiredContact id
Request body required
listIdinteger required
Responses
DELETE /contact/tag/{id} Remove a tag from a contact
/contact/tag/{id} Remove a tag from a contactDetaches a tag from a contact.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
idinteger path requiredContact id
Request body required
tagIdinteger required
Responses
GET /contact/check-email Check whether an email exists
/contact/check-email Check whether an email existsTells whether a contact already has this email address.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
emailstring (email) query requiredexclude_idinteger queryContact id to leave out of the check
Responses
GET /contact/{contact_id}/activity Contact activity
/contact/{contact_id}/activity Contact activityReturns the activity of a contact (sent, opened, clicked, unsubscribed), grouped by campaign, four campaigns per page.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
contact_idinteger path requiredpageinteger queryPage number
Default:
1
Responses
200 The activity
activitiesarray<ContactActivity>pageintegerper_pageintegertotalinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /contact/{contact_id}/campaigns Campaigns of a contact
/contact/{contact_id}/campaigns Campaigns of a contactReturns the campaigns a contact received.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
contact_idinteger path required
Responses
GET /stats/{contact_id} Contact statistics
/stats/{contact_id} Contact statisticsReturns the email engagement totals of a contact, optionally for one campaign.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
contact_idinteger path requiredcampaign_idinteger queryRestrict the totals to this campaign
Responses
GET /contact-note/{contact_id} Notes of a contact
/contact-note/{contact_id} Notes of a contactReturns the notes attached to a contact.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
contact_idinteger path required
Responses
200 The notes
successbooleannotesarray<ContactNote>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /contact/note Add a note to a contact
/contact/note Add a note to a contactAdds a note to a contact.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
contact_idinteger requiredcontentstring required
Responses
200 Note created
successbooleannoteContactNote
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
PUT /contact/note/{note_id} Update a note
/contact/note/{note_id} Update a noteUpdates the content of a note.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
note_idinteger path required
Request body required
contentstring required
Responses
200 Note updated
successbooleannoteContactNote
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
DELETE /contact/note/{note_id} Delete a note
/contact/note/{note_id} Delete a noteDeletes a note.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
note_idinteger path required
Responses
POST /contact/{id}/confirm Confirm a pending contact
/contact/{id}/confirm Confirm a pending contactMarks a pending contact as subscribed, as if it had clicked the confirmation link.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
idinteger path required
Responses
POST /contact/{id}/send-confirmation-reminder Resend the confirmation email
/contact/{id}/send-confirmation-reminder Resend the confirmation emailSends the double opt-in confirmation email again to a pending contact.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
idinteger path required
Responses
POST /contact/export Export contacts
/contact/export Export contactsStarts an export of the given contacts, or of all of them, to a file. The download link is emailed to the given address.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
contact_idsarray<integer>Contacts to export; all of them when empty
emailstring (email) required
Responses
POST /contacts/import/init Start a contact import
/contacts/import/init Start a contact importCreates an import batch. Then send the rows with POST /contacts/import/chunk and follow it with GET /contacts/import/progress/{batch_id}.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
dataobject requiredChild attributes
statusstringSubscription status given to the imported contacts
One of:
subscribed,unsubscribed,pendingDefault:pendingtagsarray<object>Child attributes
idinteger
listsarray<object>Child attributes
idinteger
forceUpdatebooleanOverwrite the contacts that already exist
Default:
false
Responses
POST /contacts/import/chunk Add rows to an import
/contacts/import/chunk Add rows to an importAdds contacts to an import batch and schedules their processing.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
batch_idinteger requiredchunkarray<object> requiredThe contacts to import
Child attributes
emailstring (email) requiredfirst_namestringlast_namestring
forceUpdateboolean
Responses
GET /contacts/import/progress/{batch_id} Import progress
/contacts/import/progress/{batch_id} Import progressReturns the progress of an import batch.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
batch_idinteger path required
Responses
200 The progress
batch_idintegerstatusstringOne of:
pending,processing,completed,failedtotal_contactsintegerprocessed_contactsintegerprogress_percentagenumberchunksobjectChild attributes
totalintegerpendingintegerprocessingintegercompletedintegerfailedinteger
created_atstring (date-time)updated_atstring (date-time)
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /contacts/import/retry/{batch_id} Retry the failed rows of an import
/contacts/import/retry/{batch_id} Retry the failed rows of an importQueues the failed chunks of an import batch again.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Parameters
batch_idinteger path required
Responses
POST /contacts/import/reset Cancel an import
/contacts/import/reset Cancel an importDeletes an import batch and its pending work.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
batch_idinteger required
Responses
POST /contact/import Import one contact
/contact/import Import one contactCreates or updates one contact from an import row, with its tags, lists and custom fields.
Authorization applicationPassword or apiKey (contacts:write) + apiSecret
Request body required
itemobject requiredChild attributes
emailstring (email) requiredfirst_namestringlast_namestring
statusstringOne of:
subscribed,unsubscribed,pendingDefault:pendingtagsarray<object>Child attributes
idinteger
listsarray<object>Child attributes
idinteger
forceUpdateboolean
Responses
Campaigns
Campaigns: content, sending, status and statistics
GET /campaigns List campaigns
/campaigns List campaignsReturns a paginated list of campaigns with their batch and statistics.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
10searchstring querySearch by campaign name
statusstring queryStatuses, comma-separated; `mine` keeps the current user’s campaigns
campaign_typearray<object> queryCampaign types: objects holding an `id`
Child attributes
idstringOne of:
newsletter,ab_test,automated,automation,wp_email,wc_email,confirm_email
orderbystring querySort field
orderstring querySort direction
One of:
ASC,DESCDefault:DESC
Responses
POST /campaigns Create a campaign
/campaigns Create a campaignCreates a draft campaign. Returns its id.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
titlestring requiredcampaign_typestringOne of:
newsletter,ab_test,automated,automation,wp_email,wc_email,confirm_emailDefault:newslettermetaobjectChild attributes
emailConfigobjectChild attributes
campaignSubjectstringemail_typestringOne of:
html,textDefault:html
automation_idintegerFor an `automation` campaign: the workflow it belongs to
step_idstringFor an `automation` campaign: the step it is sent by
Responses
GET /campaign/{id} Read a campaign
/campaign/{id} Read a campaignReturns a campaign with its editor document and configuration.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
idinteger path required
Responses
200 The campaign
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
PUT /campaign/{id} Update a campaign
/campaign/{id} Update a campaignUpdates the title and status of a campaign, and marks it as being edited by the caller.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Request body required
titlestringmetaobjectChild attributes
statusstring
Responses
PUT /campaign/{id}/rename Rename a campaign
/campaign/{id}/rename Rename a campaignRenames a campaign.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Request body required
titlestring required
Responses
PUT /campaign/{id}/settings Update the email settings of a campaign
/campaign/{id}/settings Update the email settings of a campaignUpdates the subject, sender and other email settings of a campaign.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Request body required
emailConfigobject requiredChild attributes
campaignSubjectstringfromNamestringfromTostring (email)replyTostring (email)preheaderstring
Responses
PUT /campaign/save-content/{id} Save the content of a campaign
/campaign/save-content/{id} Save the content of a campaignSaves the editor document and the rendered HTML of a campaign. 423 when another user is editing it.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Request body required
contentstringThe editor document (JSON)
htmlstringThe rendered HTML
Responses
PUT /campaign/status Change the status of campaigns
/campaign/status Change the status of campaignsChanges the status of one, several or all campaigns (`id` = `all`, optionally narrowed by `campaign_type`, `filter_status` and `search`). Moving to `trash` requires the delete permission.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
idinteger | array<integer> |allrequiredA campaign id, several, or `all`
statusstring requiredOne of:
draft,scheduled,sending,sent,paused,cancelled,trashcampaign_typearray<object>Child attributes
idstring
filter_statusstringWith `all`: only the campaigns in this status
searchstringWith `all`: only the campaigns matching this text
Responses
200 Statuses updated
successbooleanmessagestringupdated_idsarray<integer>new_statusstringscheduled_actions_cancelledintegerautomated_campaigns_restoredinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
DELETE /campaign Delete campaigns
/campaign Delete campaignsPermanently deletes the given campaigns, their batches and their scheduled sends.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
idsarray<integer> required
Responses
DELETE /campaign/delete Empty the trash
/campaign/delete Empty the trashPermanently deletes trashed campaigns: the given ids, or all of them with `id` = `all`.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
idinteger | array<integer> |allrequiredcampaign_typearray<object>Child attributes
idstring
filter_statusstringsearchstring
Responses
DELETE /campaign/all Empty the trash of given types
/campaign/all Empty the trash of given typesPermanently deletes every trashed campaign of the given types.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
campaign_typearray<object> requiredChild attributes
idstringnamestring
Responses
POST /campaign/create_batch_V2 Send or schedule a campaign
/campaign/create_batch_V2 Send or schedule a campaignCreates the send batch of a campaign: the recipients are resolved from the targeting, the HTML stored, and the sending queued now or at `scheduledAt`. 409 when the campaign was already sent or a batch is already running.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
recipientTargetingstringHow the recipients are chosen
One of:
classic,segment,contact_idsDefault:classiclistsarray<object>With `classic`: the lists to send to
Child attributes
idinteger
tagsarray<object>With `classic`: the tags to send to
Child attributes
idinteger
segmentarray<object>With `segment`: one object holding the segment id; with `contact_ids`: the contact ids
postEditinteger requiredThe campaign id
sendTypestring required`now` sends at once, `future` at `scheduledAt`
One of:
now,futurescheduledAtstringDate and time in the site’s timezone, `Y-m-d H:i:s` or ISO 8601
htmlstring requiredThe rendered HTML to send
configSenderConfig requiredopenTrackingstringOne of:
yes,noDefault:yesclickTrackingstringOne of:
yes,noDefault:yes
Responses
POST /campaign/pause_batch Pause a send
/campaign/pause_batch Pause a sendCancels the queued work of a batch and puts the campaign back to draft.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
batchIdinteger requiredcampaignIdinteger required
Responses
POST /campaign/resume_batch Resume a send
/campaign/resume_batch Resume a sendPuts a paused batch back to pending.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
batchIdinteger required
Responses
POST /campaign/send_test Send a test email
/campaign/send_test Send a test emailSends the given HTML as a test email to the given addresses.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
contactsarray<string (email)> requiredhtmlContentstring requiredsubjectstring requiredconfigobjectChild attributes
fromNamestringfromTostring (email)
Responses
200 Result per address
statusstringOne of:
success,partialsentarray<string>errorsarray<object>Child attributes
contactstringmessagestring
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /campaign/count-audience Count an audience
/campaign/count-audience Count an audienceCounts the recipients a targeting resolves to.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
Responses
GET /campaign-status Status and statistics of campaigns
/campaign-status Status and statistics of campaignsReturns the status, batch and statistics of one or more campaigns.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
idsstring query requiredCampaign ids, comma-separated
Responses
200 The campaigns
array<CampaignStatus>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /campaign/{id}/status Editing lock of a campaign
/campaign/{id}/status Editing lock of a campaignTells whether another user is editing the campaign.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
idinteger path required
Responses
GET /campaign/batches Send batches of a campaign
/campaign/batches Send batches of a campaignReturns the send batches of a campaign with their statistics.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
idinteger query requiredCampaign id
pagedinteger queryPage number
Default:
1perPageinteger queryResults per page
Default:
10
Responses
200 The batches
postsarray<object>Child attributes
batchBatchstatisticsBatchStatistics
pagesintegercountintegercurrent_pageintegerper_pageinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /batch/{batch_id}/chunks Chunks of a batch
/batch/{batch_id}/chunks Chunks of a batchReturns the chunks a batch is sent in, with their status.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
batch_idinteger path requiredpageinteger queryPage number
Default:
1per_pageinteger queryResults per page
Default:
50statusstring queryFilter by chunk status
One of:
pending,processing,completed,failedorderbystring queryDefault:
chunk_indexorderstring queryOne of:
ASC,DESCDefault:ASC
Responses
200 The chunks
chunksarray<object>Child attributes
idintegerbatch_idintegerchunk_indexintegerstatusstringcontacts_countintegerprocessed_atstring (date-time)
countintegerpagesintegercurrent_pageinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /batch-opened-contacts Contacts who opened
/batch-opened-contacts Contacts who openedReturns a paginated list of the contacts who opened a batch email.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
batch_idinteger query requiredpagedinteger queryPage number
Default:
1perPageinteger queryResults per page
Default:
10searchstring querySearch text
Responses
GET /batch-clicked-contacts Contacts who clicked
/batch-clicked-contacts Contacts who clickedReturns a paginated list of the contacts who clicked a link in a batch email.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
batch_idinteger query requiredpagedinteger queryPage number
Default:
1perPageinteger queryResults per page
Default:
10searchstring querySearch text
Responses
GET /batch-unsubscribed-contacts Contacts who unsubscribed
/batch-unsubscribed-contacts Contacts who unsubscribedReturns a paginated list of the contacts who unsubscribed from a batch email.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
batch_idinteger query requiredpagedinteger queryPage number
Default:
1perPageinteger queryResults per page
Default:
10searchstring querySearch text
Responses
GET /campaigns/{id}/logs Send logs of a campaign
/campaigns/{id}/logs Send logs of a campaignReturns, per contact, what happened to the email of a campaign.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
idinteger path requiredpageinteger queryPage number
Default:
1per_pageinteger queryResults per page
Default:
50statusstring queryFilter by status
One of:
sent,opened,clicked,unsubscribed,failed
Responses
200 The logs
logsarray<CampaignLog>countintegerpagesintegerpageintegerper_pageinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /campaigns/{id}/email-logs Delivery logs of a campaign
/campaigns/{id}/email-logs Delivery logs of a campaignReturns the delivery log of a campaign as the email service recorded it.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Parameters
idinteger path requiredpageinteger queryPage number
Default:
1per_pageinteger queryResults per page
Default:
50statusstring queryOne of:
success,error,pending
Responses
GET /campaign/{id}/activate Activate an automated campaign
/campaign/{id}/activate Activate an automated campaignActivates an `automated` campaign (recurring or triggered send).
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Responses
GET /campaign/{id}/deactivate Deactivate an automated campaign
/campaign/{id}/deactivate Deactivate an automated campaignDeactivates an `automated` campaign and cancels its scheduled sends.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Responses
POST /campaign/create_automated_campaign Set up an automated campaign
/campaign/create_automated_campaign Set up an automated campaignStores the HTML, targeting and schedule of an `automated` campaign and activates it.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
recipientTargetingstringHow the recipients are chosen
One of:
classic,segment,contact_idsDefault:classiclistsarray<object>With `classic`: the lists to send to
Child attributes
idinteger
tagsarray<object>With `classic`: the tags to send to
Child attributes
idinteger
segmentarray<object>With `segment`: one object holding the segment id; with `contact_ids`: the contact ids
postEditinteger requiredThe campaign id
sendTypestringscheduledAtstringhtmlstring requiredconfigSenderConfig requiredautomateSettingsobjectThe recurrence or trigger settings
Responses
POST /campaign/update_automated_campaign Update an automated campaign
/campaign/update_automated_campaign Update an automated campaignUpdates the HTML and settings of an `automated` campaign.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Request body required
campaignIdinteger requiredhtmlstringdataobjectThe settings to merge
Responses
GET /campaign/{id}/revisions Revisions of a campaign
/campaign/{id}/revisions Revisions of a campaignReturns the saved revisions of a campaign’s editor document.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
idinteger path required
Responses
200 The revisions
array<CampaignRevision>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /campaign/{id}/revision/{revision_id} Read a revision
/campaign/{id}/revision/{revision_id} Read a revisionReturns one revision.
Authorization applicationPassword or apiKey (campaigns:read) + apiSecret
Parameters
idinteger path requiredrevision_idinteger path required
Responses
200 The revision
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /campaign/revision/{id} Save a revision
/campaign/revision/{id} Save a revisionSaves the given editor document as a revision, when it differs from the last one. Five revisions are kept.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path required
Request body required
jsonobject requiredThe editor document
Responses
POST /campaign/{id}/restore-revision/{revision_id} Restore a revision
/campaign/{id}/restore-revision/{revision_id} Restore a revisionPuts a revision back as the campaign’s content.
Authorization applicationPassword or apiKey (campaigns:write) + apiSecret
Parameters
idinteger path requiredrevision_idinteger path required
Responses
POST /campaign/{id}/resend-unengaged Resend to the contacts who did not engage
/campaign/{id}/resend-unengaged Resend to the contacts who did not engagePro — creates a copy of a sent newsletter and sends it to the contacts who did not open it, did not click, or neither.
Authorization applicationPassword
Parameters
idinteger path required
Request body
modestringOne of:
unengaged,not_opened,not_clickedDefault:unengagedtitlestringName of the new campaign
Responses
200 The resend campaign and its batch
campaign_idintegerbatch_idinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
422 The campaign cannot be resent (not sent, not a newsletter, no open tracking)
Lists
Contact lists
GET /list List lists
/list List listsReturns a paginated list of contact lists.
Authorization applicationPassword or apiKey (lists:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch text
orderbystring querySort field
orderstring querySort direction
One of:
ASC,DESCDefault:DESC
Responses
200 The page of lists
postsarray<ContactList>pagesintegercountinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /list Create a list
/list Create a listCreates a contact list. 409 when the name is taken.
Authorization applicationPassword or apiKey (lists:write) + apiSecret
Request body required
titlestring requireddescriptionstring
Responses
DELETE /list Delete lists
/list Delete listsDeletes the given lists. The default list is skipped.
Authorization applicationPassword or apiKey (lists:write) + apiSecret
Request body required
idsarray<integer> required
Responses
GET /list/all All lists
/list/all All listsReturns every list, without pagination.
Authorization applicationPassword or apiKey (lists:read) + apiSecret
Responses
DELETE /list/all Delete every list
/list/all Delete every listPUT /list/{id}/rename Rename a list
/list/{id}/rename Rename a listRenames a list and updates its description.
Authorization applicationPassword or apiKey (lists:write) + apiSecret
Parameters
idinteger path required
Request body required
titlestring requireddescriptionstring
Responses
PUT /list/{id}/set-default Set the default list
/list/{id}/set-default Set the default listMakes a list the one new contacts join when no list is given.
Authorization applicationPassword or apiKey (lists:write) + apiSecret
Parameters
idinteger path required
Responses
Tags
Contact tags
GET /tags List tags
/tags List tagsReturns a paginated list of tags.
Authorization applicationPassword or apiKey (tags:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch text
orderbystring querySort field
orderstring querySort direction
One of:
ASC,DESCDefault:DESC
Responses
POST /tags Create a tag
/tags Create a tagCreates a tag. 409 when the name is taken.
Authorization applicationPassword or apiKey (tags:write) + apiSecret
Request body required
namestring required
Responses
GET /tag/all All tags
/tag/all All tagsDELETE /tag/all Delete every tag
/tag/all Delete every tagPUT /tag/{id}/rename Rename a tag
/tag/{id}/rename Rename a tagRenames a tag.
Authorization applicationPassword or apiKey (tags:write) + apiSecret
Parameters
idinteger path required
Request body required
titlestring required
Responses
DELETE /tag Delete tags
/tag Delete tagsDeletes the given tags.
Authorization applicationPassword or apiKey (tags:write) + apiSecret
Request body required
idsarray<integer> required
Responses
Custom Fields
Custom field definitions of the contacts (creating, renaming and deleting them requires MailerPress Pro)
GET /custom-field/all List custom fields
/custom-field/all List custom fieldsReturns every custom field definition.
Authorization applicationPassword or apiKey (contacts:read) + apiSecret
Responses
200 The definitions
array<CustomFieldDefinition>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /custom-field Create a custom field
/custom-field Create a custom fieldCreates a custom field; the key is derived from the label. Returns the existing field when the key is taken.
Authorization applicationPassword or apiKey (settings:write) + apiSecret
Request body required
labelstring requiredtypestringOne of:
text,number,date,checkbox,selectDefault:text
Responses
POST /custom-fields Create a custom field with options
/custom-fields Create a custom field with optionsPro — creates a custom field with an explicit key, options and required flag.
Authorization applicationPassword
Request body required
field_keystring requiredlabelstring requiredtypestring requiredOne of:
text,number,date,checkbox,selectoptionsarray<object>Child attributes
labelstringvaluestring
requiredboolean
Responses
DELETE /custom-fields Delete custom fields
/custom-fields Delete custom fieldsPro — deletes several custom fields by id or key.
Authorization applicationPassword
Request body required
idsarray<integer>field_keysarray<string>
Responses
PUT /custom-fields/{field_key} Update a custom field
/custom-fields/{field_key} Update a custom fieldPro — updates a custom field; a new `field_key` renames it and moves the contacts’ values.
Authorization applicationPassword
Parameters
field_keystring path required
Request body required
field_keystringlabelstringtypestringOne of:
text,number,date,checkbox,selectoptionsarray<object>Child attributes
labelstringvaluestring
requiredboolean
Responses
DELETE /custom-fields/{field_key} Delete a custom field
/custom-fields/{field_key} Delete a custom fieldPro — deletes a custom field and the contacts’ values for it.
Authorization applicationPassword
Parameters
field_keystring path required
Responses
API Keys
API keys, their scopes and rate limits (settings:* scope, i.e. the *:* permission)
GET /api-keys List API keys
/api-keys List API keysReturns a paginated list of the API keys.
Authorization applicationPassword or apiKey (settings:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch text
statusstring queryOne of:
active,revoked,expiredorderbystring queryOne of:
created_at,name,last_used_at,request_countDefault:created_atorderstring queryOne of:
ASC,DESCDefault:DESC
Responses
POST /api-keys Create an API key
/api-keys Create an API keyCreates an API key. The key and the secret are only returned here, once.
Authorization applicationPassword or apiKey (settings:write) + apiSecret
Request body required
namestring requireddescriptionstringpermissionsarray<string>Scopes, from GET /api-keys/permissions
rate_limit_requestsintegerRequests allowed per window
Default:
1000rate_limit_windowintegerWindow in seconds
Default:
3600allowed_ipsarray<string>IPs allowed to use the key; empty for any
expires_in_daysintegerDays until the key expires; 0 for never
Default:
0
Responses
200 The new key and its secret
successbooleanmessagestringkey_idintegerapi_keystringExample:
mpk_…api_secretstringExample:
mps_…namestringexpires_atstring (date-time), nullable
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
PUT /api-keys/{key_id} Update an API key
/api-keys/{key_id} Update an API keyUpdates the name, description, scopes, rate limit or allowed IPs of a key.
Authorization applicationPassword or apiKey (settings:write) + apiSecret
Parameters
key_idinteger path required
Request body required
Responses
DELETE /api-keys/{key_id} Revoke an API key
/api-keys/{key_id} Revoke an API keyRevokes a key: it stops working but stays listed. DELETE /api-keys/{key_id}/delete removes it for good.
Authorization applicationPassword or apiKey (settings:write) + apiSecret
Parameters
key_idinteger path required
Responses
POST /api-keys/{key_id}/reactivate Reactivate an API key
/api-keys/{key_id}/reactivate Reactivate an API keyReactivates a revoked key.
Authorization applicationPassword or apiKey (settings:write) + apiSecret
Parameters
key_idinteger path required
Responses
DELETE /api-keys/{key_id}/delete Delete an API key
/api-keys/{key_id}/delete Delete an API keyPermanently deletes a key.
Authorization applicationPassword or apiKey (settings:write) + apiSecret
Parameters
key_idinteger path required
Responses
GET /api-keys/{key_id}/stats Usage of an API key
/api-keys/{key_id}/stats Usage of an API keyReturns the request count, last use and rate limit of a key.
Authorization applicationPassword or apiKey (settings:read) + apiSecret
Parameters
key_idinteger path required
Responses
200 The usage
key_idintegernamestringstatusstringrequest_countintegerlast_used_atstring (date-time)created_atstring (date-time)rate_limitobjectChild attributes
requestsintegerwindowinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /api-keys/permissions Available permissions
/api-keys/permissions Available permissionsReturns the scopes an API key can be given.
Authorization applicationPassword or apiKey (settings:read) + apiSecret
Responses
200 The permissions
permissionsarray<Permission>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
Templates
Email templates and their categories (templates:* scope, i.e. the *:* permission)
GET /templates/all List templates
/templates/all List templatesReturns a paginated list of templates.
Authorization applicationPassword or apiKey (templates:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch text
categoryinteger queryCategory id
categoriesarray<integer> queryCategory ids
usage_typestring queryOne of:
newsletter,automationinternalboolean queryOnly the built-in templates
orderbystring querySort field
orderstring querySort direction
One of:
ASC,DESCDefault:DESC
Responses
POST /template Create a template
/template Create a templateCreates a template; unknown category names are created.
Authorization applicationPassword or apiKey (templates:write) + apiSecret
Request body required
templateNamestring requiredtemplateCategoryarray<string>templateJSONstring requiredThe editor document
usage_typestringOne of:
newsletter,automationDefault:newsletter
Responses
GET /template/{id} Read a template
/template/{id} Read a templateReturns a template with its content.
Authorization applicationPassword or apiKey (templates:read) + apiSecret
Parameters
idinteger path required
Responses
PUT /template/{id} Update a template
/template/{id} Update a templateUpdates the name, categories and usage type of a template.
Authorization applicationPassword or apiKey (templates:write) + apiSecret
Parameters
idinteger path required
Request body required
templateNamestring requiredtemplateCategoryarray<string>usage_typestringOne of:
newsletter,automation
Responses
PUT /template/{id}/content Update the content of a template
/template/{id}/content Update the content of a templateReplaces the editor document of a template.
Authorization applicationPassword or apiKey (templates:write) + apiSecret
Parameters
idinteger path required
Request body required
contentstring requiredThe editor document
Responses
DELETE /templates/{id} Delete a template
/templates/{id} Delete a templateDeletes a template.
Authorization applicationPassword or apiKey (templates:write) + apiSecret
Parameters
idinteger path required
Responses
GET /categories/all Template categories
/categories/all Template categoriesReturns the template categories.
Authorization applicationPassword or apiKey (templates:read) + apiSecret
Parameters
usage_typestring queryOne of:
newsletter,automation
Responses
POST /category/rename Rename a category
/category/rename Rename a categoryRenames a template category.
Authorization applicationPassword or apiKey (templates:write) + apiSecret
Request body required
current_namestring requirednew_namestring required
Responses
DELETE /category/delete Delete a category
/category/delete Delete a categoryDeletes a template category.
Authorization applicationPassword or apiKey (templates:write) + apiSecret
Request body required
namestring required
Responses
Automations
Workflows: their steps, status, jobs and logs (automations:* scope, i.e. the *:* permission)
GET /workflows List workflows
/workflows List workflowsReturns a paginated list of workflows with their job statistics.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch text
statusstring queryOne of:
DRAFT,ENABLED,DISABLEDtrigger_typestring queryFilter by trigger key
orderbystring queryOne of:
name,id,created_at,updated_atDefault:updated_atorderstring queryOne of:
ASC,DESCDefault:DESC
Responses
200 The page of workflows
postsarray<AutomationListItem>pagesintegercountinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /workflows Create a workflow
/workflows Create a workflowCreates a workflow from its steps, or from a template.
Authorization applicationPassword or apiKey (automations:write) + apiSecret
Request body required
Responses
200 The workflow
automationAutomationnodesarray<AutomationNode>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /workflows/{id} Read a workflow
/workflows/{id} Read a workflowReturns a workflow and its steps.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
idinteger path required
Responses
200 The workflow
automationAutomationnodesarray<AutomationNode>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
PUT /workflows/{id} Update a workflow
/workflows/{id} Update a workflowReplaces the settings and steps of a workflow. 400 with the list of errors when a step is invalid.
Authorization applicationPassword or apiKey (automations:write) + apiSecret
Parameters
idinteger path required
Request body required
Responses
200 The workflow
automationAutomationnodesarray<AutomationNode>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
DELETE /workflows/{id} Delete a workflow
/workflows/{id} Delete a workflowDeletes a workflow and its jobs.
Authorization applicationPassword or apiKey (automations:write) + apiSecret
Parameters
idinteger path required
Responses
DELETE /workflows/all Delete every workflow
/workflows/all Delete every workflowDeletes all workflows.
Authorization applicationPassword or apiKey (automations:write) + apiSecret
Responses
PUT /workflows/status Change the status of workflows
/workflows/status Change the status of workflowsEnables, disables or drafts the given workflows, or all of them with `ids` = `all`.
Authorization applicationPassword or apiKey (automations:write) + apiSecret
Request body required
idsarray<integer> |allrequiredstatusstring requiredOne of:
DRAFT,ENABLED,DISABLED
Responses
GET /workflows/{id}/stats Statistics of a workflow
/workflows/{id}/stats Statistics of a workflowReturns the job and log counts of a workflow.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
idinteger path required
Responses
200 The statistics
total_jobsintegeractive_jobsintegercompleted_jobsintegerfailed_jobsintegerjobs_by_statusobjecttotal_logsintegerlogs_by_statusobjectunique_usersintegerlast_executionstring (date-time)
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /workflows/{id}/logs Logs of a workflow
/workflows/{id}/logs Logs of a workflowReturns the execution log of a workflow, per contact and step.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
idinteger path requiredpageinteger queryPage number
Default:
1per_pageinteger queryResults per page
Default:
50statusstring queryFilter by status
Responses
200 The logs
logsarray<AutomationLog>countintegerpagesintegerpageintegerper_pageinteger
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /workflows/{id}/goals Goals of a workflow
/workflows/{id}/goals Goals of a workflowReturns the goal steps of a workflow with their conversion statistics.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
idinteger path required
Responses
200 The goals
goalsarray<object>Child attributes
step_idstringgoal_eventstringlabelstringnext_step_idstringalternative_step_idstringstatsobject
totalsobject
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /workflows/ab-tests/{automationId} A/B tests of a workflow
/workflows/ab-tests/{automationId} A/B tests of a workflowReturns the results of the A/B test steps of a workflow.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
automationIdinteger path required
Responses
200 The tests
idintegertest_namestringstep_idstringstatusstringOne of:
running,completedwinnerstring, nullablewinner_metricnumber, nullablewinning_criteriastringOne of:
open_rate,click_ratecreated_atstring (date-time)completed_atstring (date-time), nullableversion_aobjectChild attributes
subjectstringmetricsobject
version_bobjectChild attributes
subjectstringmetricsobject
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /workflows/{id}/retry-failed Retry the failed jobs
/workflows/{id}/retry-failed Retry the failed jobsQueues the failed jobs of a workflow again — one, with `job_id`, or all of them.
Authorization applicationPassword or apiKey (automations:write) + apiSecret
Parameters
idinteger path required
Request body
job_idinteger
Responses
GET /workflows/failed-jobs Failed jobs
/workflows/failed-jobs Failed jobsReturns the failed jobs of every workflow over a period.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Parameters
intervalstring queryPeriod
One of:
24h,7d,30dDefault:7d
Responses
200 The jobs
failed_jobsarray<object>Child attributes
idintegerautomation_idintegerworkflow_namestringuser_idintegeruser_emailstringstatusstringcreated_atstring (date-time)updated_atstring (date-time)stepsarray<object>Child attributes
step_idstringstatusstringcreated_atstring (date-time)dataobject
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /workflows/triggers Available triggers
/workflows/triggers Available triggersReturns the triggers a workflow step can use, with their keys and settings.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Responses
GET /workflows/actions Available actions
/workflows/actions Available actionsReturns the actions a workflow step can use, with their keys and settings.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Responses
GET /workflows/conditions Available conditions
/workflows/conditions Available conditionsReturns the conditions a workflow step can use, with their keys and settings.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Responses
GET /workflows/goals Available goals
/workflows/goals Available goalsReturns the goals a workflow step can use, with their keys and settings.
Authorization applicationPassword or apiKey (automations:read) + apiSecret
Responses
Segments
Pro — dynamic contact segments. Application Password only: the Pro endpoints do not accept API keys.
GET /segments List segments
/segments List segmentsPro — returns a paginated list of segments with their contact count.
Authorization applicationPassword
Parameters
pagedinteger queryPage number
Default:
1perPagesinteger queryResults per page
Default:
20searchstring querySearch text
orderbystring querySort field
orderstring querySort direction
One of:
ASC,DESCDefault:DESC
Responses
POST /segments Create a segment
/segments Create a segmentPro — creates a segment from its conditions. 409 when the name is taken.
Authorization applicationPassword
Request body required
namestring requiredconditionsobject required
Responses
PUT /segments/{id} Update a segment
/segments/{id} Update a segmentPro — updates the name and conditions of a segment.
Authorization applicationPassword
Parameters
idinteger path required
Request body required
namestring requiredconditionsobject required
Responses
DELETE /segments/{id} Delete a segment
/segments/{id} Delete a segmentPro — deletes a segment.
Authorization applicationPassword
Parameters
idinteger path required
Responses
POST /segments/preview-count Count the contacts of conditions
/segments/preview-count Count the contacts of conditionsPro — counts the contacts that match a condition tree, before saving it.
Authorization applicationPassword
Request body required
conditionsobject required
Responses
GET /getContactSegment Contacts of a segment
/getContactSegment Contacts of a segmentPro — returns the contacts of a segment: paginated, or only their ids.
Authorization applicationPassword
Parameters
segmentNamestring query requiredonlyIdsboolean queryReturn the ids only
response_typestring queryOne of:
paginated,idspageinteger queryPage number
Default:
1per_pageinteger queryResults per page
Default:
20
Responses
GET /conditions-metadata Available conditions
/conditions-metadata Available conditionsPro — returns the fields, operators and input types a segment condition can use.
Authorization applicationPassword
Responses
Webhooks
Pro — outgoing webhooks (MailerPress calls your URLs on events) and incoming webhooks (your systems call MailerPress). Application Password only.
GET /webhooks/events Available events
/webhooks/events Available eventsPro — returns the events an outgoing webhook can subscribe to.
Authorization applicationPassword
Responses
200 The events
array<WebhookEvent>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /webhooks/outgoing Outgoing webhooks
/webhooks/outgoing Outgoing webhooksPro — returns the outgoing webhook configuration, keyed by event.
Authorization applicationPassword
Responses
POST /webhooks/outgoing Save the outgoing webhooks
/webhooks/outgoing Save the outgoing webhooksPro — replaces the outgoing webhook configuration. Each event is POSTed as JSON to its URLs, signed with `X-Webhook-Signature: sha256=<HMAC-SHA256 of the body with the secret>`.
Authorization applicationPassword
Request body required
object
Responses
GET /webhooks/outgoing-settings Outgoing webhooks with their events
/webhooks/outgoing-settings Outgoing webhooks with their eventsPro — returns the events and the outgoing configurations in one call.
Authorization applicationPassword
Responses
200 Events and configurations
eventsarray<WebhookEvent>configsobject
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /webhooks/outgoing/{event_key}/test Send a test event
/webhooks/outgoing/{event_key}/test Send a test eventPro — POSTs a sample payload of an event to the given URLs, or to the configured ones.
Authorization applicationPassword
Parameters
event_keystring path required
Request body
urlsarray<string (uri)>secretstring
Responses
200 One result per URL
successbooleanmessagestringresultsarray<object>Child attributes
urlstringsuccessbooleanstatus_codeintegerresponse_bodystringerrorstring
test_payloadWebhookPayload
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /webhooks Incoming webhooks
/webhooks Incoming webhooksPro — returns the incoming webhooks.
Authorization applicationPassword
Responses
200 The webhooks
array<IncomingWebhook>
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
GET /webhooks/incoming Incoming webhooks with their handlers
/webhooks/incoming Incoming webhooks with their handlersPro — returns the incoming webhooks and the handlers they can run.
Authorization applicationPassword
Responses
200 Webhooks and handlers
webhooksarray<IncomingWebhook>available_handlersarray<object>Child attributes
keystringlabelstringdescriptionstring
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
POST /webhooks/incoming Save the incoming webhooks
/webhooks/incoming Save the incoming webhooksPro — replaces the incoming webhook configuration.
Authorization applicationPassword
Request body required
object
Responses
POST /webhooks/{webhook_id} Save an incoming webhook
/webhooks/{webhook_id} Save an incoming webhookPro — creates or updates one incoming webhook. A secret is generated when none is given.
Authorization applicationPassword
Parameters
webhook_idstring path required
Request body required
descriptionstringenabledbooleanDefault:
truehandlersarray<string>secretstring
Responses
200 Webhook saved
successbooleanmessagestringwebhookIncomingWebhook
400 Bad request — invalid parameters
401 Unauthorized — authentication required
403 Forbidden — insufficient permissions or scope
404 Not found
DELETE /webhooks/{webhook_id} Delete an incoming webhook
/webhooks/{webhook_id} Delete an incoming webhookPro — deletes an incoming webhook.
Authorization applicationPassword
Parameters
webhook_idstring path required
Responses
GET /webhooks/incoming/{webhook_id}/secret Secret of an incoming webhook
/webhooks/incoming/{webhook_id}/secret Secret of an incoming webhookPro — returns the signing secret of an incoming webhook.
Authorization applicationPassword
Parameters
webhook_idstring path required
Responses
POST /webhooks/incoming/{webhook_id}/regenerate-secret Regenerate the secret
/webhooks/incoming/{webhook_id}/regenerate-secret Regenerate the secretPro — replaces the signing secret of an incoming webhook.
Authorization applicationPassword
Parameters
webhook_idstring path required
Responses
POST /webhooks/receive/{webhook_id} Call an incoming webhook
/webhooks/receive/{webhook_id} Call an incoming webhookPro — the URL your systems call. The body (JSON or form) is signed with `X-Webhook-Signature` (or `X-Hub-Signature-256`, `X-Signature`): `sha256=<HMAC-SHA256 of the body with the webhook’s secret>`. The handlers of the webhook then run on the payload.
No authentication required.
Parameters
webhook_idstring path required
Request body required
object
Responses
A/B Tests
Pro — A/B tests between campaign variations. Application Password only.
GET /ab-campaigns List A/B tests
/ab-campaigns List A/B testsPro — returns a paginated list of A/B tests.
Authorization applicationPassword
Parameters
pagedinteger queryPage number
Default:
1per_pageinteger queryResults per page
Default:
20searchstring querySearch text
statusstring queryOne of:
draft,running,completed,canceled
Responses
POST /ab-campaigns Create an A/B test
/ab-campaigns Create an A/B testPro — creates a draft A/B test and one campaign per variation.
Authorization applicationPassword
Request body required
Responses
GET /ab-campaigns/{id} Read an A/B test
/ab-campaigns/{id} Read an A/B testPro — returns a test with its variations and their metrics.
Authorization applicationPassword
Parameters
idinteger path required
Responses
DELETE /ab-campaigns/{id} Delete an A/B test
/ab-campaigns/{id} Delete an A/B testPro — deletes a test and its variation campaigns.
Authorization applicationPassword
Parameters
idinteger path required
Responses
PUT /ab-campaigns/{id}/settings Update the settings of an A/B test
/ab-campaigns/{id}/settings Update the settings of an A/B testPro — updates a draft test: mode, sample, duration, winner metric, audience. 409 once launched.
Authorization applicationPassword
Parameters
idinteger path required
Request body required
Responses
POST /ab-campaigns/{id}/variations/{campaign_id}/clone Copy a variation
/ab-campaigns/{id}/variations/{campaign_id}/clone Copy a variationPro — copies the content of one variation campaign into another of the same test.
Authorization applicationPassword
Parameters
idinteger path requiredcampaign_idinteger path requiredThe variation campaign to copy into
Request body required
source_campaign_idinteger requiredonly_if_emptybooleanOnly when the target has no content yet
Responses
POST /ab-campaigns/{id}/launch Launch an A/B test
/ab-campaigns/{id}/launch Launch an A/B testPro — sends the sample of each variation. 422 with fewer than two variations or when one has no content.
Authorization applicationPassword
Parameters
idinteger path required
Responses
POST /ab-campaigns/{id}/evaluate Evaluate an A/B test
/ab-campaigns/{id}/evaluate Evaluate an A/B testPro — compares the variations on the winner metric and, with `send_winner`, sends the winner to the rest of the audience.
Authorization applicationPassword
Parameters
idinteger path required
Request body
send_winnerboolean
Responses
POST /ab-campaigns/{id}/send-winner Send the winner
/ab-campaigns/{id}/send-winner Send the winnerPro — sends the winning variation to the contacts who were not in the sample.
Authorization applicationPassword
Parameters
idinteger path required
Responses
POST /ab-campaigns/{id}/cancel Cancel an A/B test
/ab-campaigns/{id}/cancel Cancel an A/B testPro — cancels a running test and its pending sends.
Authorization applicationPassword
Parameters
idinteger path required
Responses
Schemas
Error
ErrorcodestringExample:
rest_forbiddenmessagestringdataobjectChild attributes
statusintegerExample:
403
Tag
Tagtag_idintegerExample:
3namestringExample:
VIPcreated_atstring (date-time)
ContactList
ContactListlist_idintegerExample:
1namestringExample:
Newsletterdescriptionstringis_defaultintegerOne of:
0,1contact_countintegercreated_atstring (date-time)
CustomFieldDefinition
CustomFieldDefinitionidintegerfield_keystringExample:
companylabelstringExample:
CompanytypestringOne of:
text,number,date,checkbox,selectrequiredbooleanis_editablebooleanoptionsarray<object>Child attributes
labelstringvaluestring
Contact
Contactcontact_idintegerExample:
42idintegerExample:
42emailstring (email)Example:
[email protected]first_namestringExample:
Johnlast_namestringExample:
Doesubscription_statusstringOne of:
subscribed,unsubscribed,pendingExample:subscribedcreated_atstring (date-time)updated_atstring (date-time)tagsarray<object>Child attributes
tag_idintegertag_namestring
contact_listsarray<object>Child attributes
list_idintegerlist_namestring
custom_fieldsarray<object>Child attributes
field_keystringlabelstringtypestringrequiredbooleanoptionsarray<string>valuestring
total_openedintegertotal_clickedinteger
ContactNote
ContactNoteidintegercontact_idintegercontentstringcreated_atstring (date-time)updated_atstring (date-time)
ContactActivity
ContactActivitycampaign_idintegercampaign_namestringengagement_scorenumberactivitiesarray<object>Child attributes
typestringOne of:
sent,opened,clicked,unsubscribedtimestampstring (date-time)detailsobject
Campaign
CampaignidintegerExample:
12namestringExample:
October newslettersubjectstringstatusstringOne of:
draft,scheduled,pending,sending,sent,paused,cancelled,error,trash,active,inactivecampaign_typestringOne of:
newsletter,ab_test,automated,automation,wp_email,wc_email,confirm_emailemail_typestringOne of:
html,textuser_idintegerauthorobjectChild attributes
namestringemailstring
batchintegerpublic_urlstring (uri)lockedbooleanstatisticsBatchStatisticscreated_atstring (date-time)updated_atstring (date-time)
CampaignDetail
CampaignDetailtitlestringstatusstringjsonstringThe editor document (JSON) of the campaign
configobjecttypestringcampaign_typestringemail_typestringeditor_typestringOne of:
visual,htmlautomation_idinteger, nullableautomation_namestring, nullablestep_idstring, nullable
BatchStatistics
BatchStatisticstotal_opensintegertotal_clicksintegertotal_unsubscribesinteger
Batch
Batchidintegercampaign_idintegerstatusstringOne of:
pending,scheduled,processing,completed,paused,cancelled,drafttotal_emailsintegersender_namestringsender_tostring (email)subjectstringscheduled_atstring (date-time), nullablecreated_atstring (date-time)
CampaignStatus
CampaignStatuscampaign_idintegertitlestringsubjectstringstatusstringbatchBatchstatisticsBatchStatistics
SenderConfig
SenderConfigfromNamestringExample:
MailerPressfromTostring (email)Example:
[email protected]subjectstring requiredExample:
Our October news
AudienceTargeting
AudienceTargetingrecipientTargetingstringHow the recipients are chosen
One of:
classic,segment,contact_idsDefault:classiclistsarray<object>With `classic`: the lists to send to
Child attributes
idinteger
tagsarray<object>With `classic`: the tags to send to
Child attributes
idinteger
segmentarray<object>With `segment`: one object holding the segment id; with `contact_ids`: the contact ids
CampaignLog
CampaignLogidintegercontact_idintegeremailstringfirst_namestringlast_namestringstatusstringOne of:
sent,opened,clicked,unsubscribed,faileddataobjectChild attributes
emails_openedintegeremails_clickedintegerunsubscribedbooleanunsubscribed_atstring (date-time)opened_atstring (date-time)
created_atstring (date-time)
EmailLog
EmailLogidintegerto_emailstring (email)subjectstringfrom_emailstringfrom_namestringservicestringExample:
brevostatusstringOne of:
pending,success,errorerror_messagestring, nullablecreated_atstring (date-time)sent_atstring (date-time), nullableis_htmlboolean
CampaignRevision
CampaignRevisionidintegercampaign_idintegerjsonstringcreated_byintegercreated_by_namestringcreated_atstring (date-time)
ApiKey
ApiKeykey_idintegernamestringdescriptionstringpermissionsarray<string>statusstringOne of:
active,revoked,expiredrate_limit_requestsintegerExample:
1000rate_limit_windowintegerWindow in seconds
Example:
3600allowed_ipsarray<string>request_countintegerlast_used_atstring (date-time), nullableexpires_atstring (date-time), nullablecreated_atstring (date-time)updated_atstring (date-time)
ApiKeyInput
ApiKeyInputnamestringdescriptionstringpermissionsarray<string>Scopes, from GET /api-keys/permissions
rate_limit_requestsintegerRequests allowed per window
Default:
1000rate_limit_windowintegerWindow in seconds
Default:
3600allowed_ipsarray<string>IPs allowed to use the key; empty for any
Permission
PermissionidstringExample:
contacts:readlabelstringdescriptionstring
Template
TemplateidintegernamestringcontentstringThe editor document (JSON)
cat_idintegercategoriesarray<object>Child attributes
category_idintegernamestringslugstring
usage_typestringOne of:
newsletter,automationinternalbooleancreated_atstring (date-time)updated_atstring (date-time)
Automation
AutomationidintegernamestringauthorintegerstatusstringOne of:
DRAFT,ENABLED,DISABLEDrun_once_per_subscriberbooleancreated_atstring (date-time)updated_atstring (date-time)
AutomationNode
AutomationNodeidstringExample:
step_1step_idstringExample:
step_1typestringOne of:
trigger,action,condition,delay,goal,ab_testkeystringThe trigger, action or condition key, from the /workflows/triggers, /actions and /conditions catalogues
Example:
contact_subscribedsettingsobjectnext_step_idstring, nullablealternative_step_idstring, nullablepositionobjectChild attributes
xnumberynumber
AutomationInput
AutomationInputautomationobject requiredChild attributes
namestring requiredstatusstringOne of:
DRAFT,ENABLED,DISABLEDrun_once_per_subscriberboolean
nodesarray<AutomationNode> requiredtemplate_idstringStart from a workflow template instead of the nodes given
AutomationListItem
AutomationListItemidintegerautomation_idintegernamestringstatusstringcreated_atstring (date-time)updated_atstring (date-time)statsobjectChild attributes
total_jobsintegeractive_jobsintegercompleted_jobsintegerfailed_jobsintegerlast_executionstring (date-time)
ab_testobject, nullableChild attributes
latest_winnerstringlatest_completed_atstring (date-time)
AutomationLog
AutomationLoguser_idintegeremailstringstatusstringdataobjectcreated_atstring (date-time)job_statusstringcondition_rulesobject, nullableevent_namestringstep_typestringstep_keystring
Segment
SegmentidintegernamestringExample:
Engaged buyersconditionsobjectThe condition tree, as the segment builder saves it; the fields and operators come from GET /conditions-metadata
contact_countintegercreated_atstring (date-time)updated_atstring (date-time)
OutgoingWebhookConfig
OutgoingWebhookConfigenabledbooleanurlsarray<string (uri)>The URLs the event is POSTed to
secretstringSigning secret; `***` in responses and to keep the stored one on save
WebhookEvent
WebhookEventkeystringExample:
contact.creatednamestringdescriptionstringcategorystring
WebhookPayload
WebhookPayloadeventstringExample:
contact.createddataobjectmetadataobjectChild attributes
timestampstring (date-time)event_keystringevent_namestring
IncomingWebhook
IncomingWebhookidstringExample:
crm-syncdescriptionstringenabledbooleanhandlersarray<string>Handler keys, from `available_handlers`
secretstring`***` in responses
urlstring (uri)
AbVariation
AbVariationidintegercampaign_idintegerlabelstringExample:
Atraffic_percentageintegersample_contact_countintegersent_contact_countintegertitlestringsubjectstringstatusstringeditor_typestringOne of:
visual,htmlconfigobjectmetricsobjectChild attributes
sentintegeropensintegerclicksintegeropen_ratenumberclick_ratenumberperformance_scorenumber
AbTest
AbTestidintegernamestringuser_idintegerstatusstringOne of:
draft,running,completed,canceledtest_modestringwinner: send the sample, pick a winner, send it to the rest; split: send each variation to its share
One of:
winner,splitsample_percentageintegertest_duration_valueintegertest_duration_unitstringOne of:
minutes,hours,daystest_duration_secondsintegerwinner_metricstringOne of:
open_rate,click_rate,performance_scoreauto_send_winnerbooleanfallback_campaign_idinteger, nullablewinner_campaign_idinteger, nullableaudience_configAudienceTargetingvariationsarray<AbVariation>created_atstring (date-time)updated_atstring (date-time)
AbTestInput
AbTestInputnamestring requiredtest_modestringOne of:
winner,splitDefault:winnersample_percentageintegerDefault:
20test_duration_valueintegertest_duration_unitstringOne of:
minutes,hours,daysDefault:hourswinner_metricstringOne of:
open_rate,click_rate,performance_scoreDefault:performance_scoreauto_send_winnerbooleanfallback_variation_labelstringDefault:
AaudienceAudienceTargetingvariation_countintegervariationsarray<object>Child attributes
labelstringsource_campaign_idintegerCopy this campaign into the variation
base_email_configobjectSender and subject shared by the variations
base_jsonstringEditor document shared by the variations