Work with contacts by your own external ID: read, import, update and delete contacts, map and unmap them, add them to groups and mailing lists, send operational messages, and read activity and statistics. For accounts that use the External ID feature; see External ID: purpose and how it works.

All endpoints use the base URL https://webapi.mymarketing.co.il and an API key in the Authorization header. New to the API? Start with Get started with the ActiveTrail API.

Endpoints

MethodEndpointWhat it does
GET/api/external/{externalId}Get contact by the external id and name
GET/api/externalGet the contact list
GET/api/external/contactsGet the list of contacts (those that have external id and external name)
GET/api/external/unmappedGet the list of unmapped contacts (those that have no external id or external name)
POST/api/external/importImport contacts
POST/api/external/mappingMap external id and external name to unmapped contact
DELETE/api/external/unmap/{externalId}Unmap contact's external id and name based on the provided details
PUT/api/external/contact/{externalId}Update the given contact
DELETE/api/external/contact/{externalId}Delete the given contact by providing external id and external name
POST/api/external/group/{groupId}Add contact to group with the given external id and external name
POST/api/external/mailinglist/{mailinglistId}Add contact to mailing list with the given external id and external name
DELETE/api/external/group/{groupId}Delete contacts from group with the given external id and external name
DELETE/api/external/mailinglist/{mailinglistId}Delete contacts from mailing list with the given external id and external name
POST/api/external/operational/messageCreate and send a new operational message
POST/api/external/operational/sms_messageCreate and send a new operational sms message
GET/api/external/schemaGet contact's fields information
GET/api/external/activityGet the list of contacts activities
GET/api/external/statistics/mailGet a contact's email activity by external ID and external name
GET/api/external/statistics/smsGet a contact's SMS activity by external ID and external name

Endpoint details

Get contact by the external id and name

GET https://webapi.mymarketing.co.il/api/external/{externalId}

Get contact by the external id and name. if one doesn't match the other we'll get an empty response.

ParameterInTypeDescription
externalIdpathstringExternal id Required.
externalNamequerystringExternal name Required.

Full reference, request and response samples

Get the contact list

GET https://webapi.mymarketing.co.il/api/external

Get the contact list. You can get the list filtered by email and/or mobile number

ParameterInTypeDescription
emailquerystringThe email of the contacts you would like to get. Required if SMS is not in use
smsquerystringThe sms of the contacts you would like to get. Required if email is not in use

Full reference, request and response samples

Get the list of contacts (those that have external id and external name)

GET https://webapi.mymarketing.co.il/api/external/contacts

Get the list of contacts (those that have external id and external name). You can get the list filtered by customer status (active, unsubscribed, bounced. etc.,) by the registration date (from/to date, the default is three months back) and limited to a number of contacts (up to 100 per call)

ParameterInTypeDescription
customer_statesqueryCustomerStatesFilter by contact status. Values: ALL, ACTIVE, INACTIVE, CUSTOMER_REQUEST, BOUNCED, SPAM_COMPLIENT, QUARANTINED.
from_datequerydateStart of the date range.
to_datequerydateEnd of the date range.
pagequeryintegerGet a specific page (number of pages is limited) (Range: inclusive between 1 and 2147483647)
limitqueryintegerLimit the number of items you get in the results. (Removing the "limit" will, by default, display only 20 records) (Range: inclusive between 1 and 100)

Full reference, request and response samples

Get the list of unmapped contacts (those that have no external id or external name)

GET https://webapi.mymarketing.co.il/api/external/unmapped

Get the list of unmapped contacts (those that have no external id or external name). You can get the list filtered by customer status (active, unsubscribed, bounced. etc.,) by the registration date (from/to date, the default is three months back) and limited to a number of contacts (up to 100 per call)

ParameterInTypeDescription
customer_statesqueryCustomerStatesFilter by contact status. Values: ALL, ACTIVE, INACTIVE, CUSTOMER_REQUEST, BOUNCED, SPAM_COMPLIENT, QUARANTINED.
from_datequerydateStart of the date range. Format: mm-dd-yyyy.
to_datequerydateEnd of the date range. Format: mm-dd-yyyy.
pagequeryintegerGet a specific page (number of pages is limited) (Range: inclusive between 1 and 2147483647)
limitqueryintegerLimit the number of items you get in the results. (Removing the "limit" will, by default, display only 20 records) (Range: inclusive between 1 and 100)

Full reference, request and response samples

Import contacts

POST https://webapi.mymarketing.co.il/api/external/import

Import contacts. Limited to 1000 contacts. If the external ID you try to import exists - you'll get an error

ParameterInTypeDescription
mailing_listbodyintegerMailing list id. Delete it if you don't have mailing lists on your account. Can be found using the endpoint "Get account's mailing lists" or in the UI (go to Contacts->Mailing Lists->click on the mailing lists's name -> you'll find the id in the URL)
groupbodyintegerGroup id. Required. Can be found using the endpoint "Get account's groups" or in the UI (go to Contacts->Groups->click on the group's name -> you'll find the id in the URL)
contactsbodyCollection of ApiExternalContactContacts - imports contacts is limited to 1000

The request body is a JSON object (ImportExternalContactsContainer).

Full reference, request and response samples

Map external id and external name to unmapped contact

POST https://webapi.mymarketing.co.il/api/external/mapping
ParameterInTypeDescription
customerIdbodyintegerContact's ID. can be found using the endpoint "Get the list of unmapped contacts"
externalIdbodystringThe external id of contact. Required in a post endpoint.
externalNamebodystringThe external name of contact. Required in a post endpoint.

The request body is a JSON object (MappingExternalContact).

Full reference, request and response samples

Unmap contact's external id and name based on the provided details

DELETE https://webapi.mymarketing.co.il/api/external/unmap/{externalId}

Unmap contact's external id and name based on the provided details. If one doesn't match the other or doesn't exist you'll get an error

ParameterInTypeDescription
externalIdpathstringExternal id. Required.
externalNamequerystringExternal name. Required.

Full reference, request and response samples

Update the given contact

PUT https://webapi.mymarketing.co.il/api/external/contact/{externalId}
ParameterInTypeDescription
externalIdpathstringExternal id. Required.
externalNamequerystringExternal name. Required.
contactbodyUpdateContactContainerSee UpdateContactContainer

The request body is a JSON object (UpdateExternalContactContainer).

Full reference, request and response samples

Delete the given contact by providing external id and external name

DELETE https://webapi.mymarketing.co.il/api/external/contact/{externalId}

Delete the given contact by providing external id and external name. If one doesn't match the other or doesn't exist we'll get an error

ParameterInTypeDescription
externalIdpathstringExternal id. Required.
externalNamequerystringExternal name. Required.

Full reference, request and response samples

Add contact to group with the given external id and external name

POST https://webapi.mymarketing.co.il/api/external/group/{groupId}

Add contact to group with the given external id and external name. Limited to 1000 contacts per call.

ParameterInTypeDescription
groupIdpathintegerGroup id. Can be found using the endpoint "Get account's groups" or in the UI (go to Contacts->Groups->click on the group's name -> you'll find the id in the URL) Required.
contactsbodyCollection of ExternalBase

The request body is a JSON object (ExternalList).

Full reference, request and response samples

Add contact to mailing list with the given external id and external name

POST https://webapi.mymarketing.co.il/api/external/mailinglist/{mailinglistId}

Add contact to mailing list with the given external id and external name. Limited to 1000 contacts per call.

ParameterInTypeDescription
mailinglistIdpathintegerMailing list id. Can be found using the endpoint "Get account's mailing lists" or in the UI (go to Contacts->Mailing Lists->click on the mailing lists's name -> you'll find the id in the URL) Required.
contactsbodyCollection of ExternalBase

The request body is a JSON object (ExternalList).

Full reference, request and response samples

Delete contacts from group with the given external id and external name

DELETE https://webapi.mymarketing.co.il/api/external/group/{groupId}
ParameterInTypeDescription
groupIdpathintegerGroup id Required.
contactsbodyCollection of ExternalBase

The request body is a JSON object (ExternalList).

Full reference, request and response samples

Delete contacts from mailing list with the given external id and external name

DELETE https://webapi.mymarketing.co.il/api/external/mailinglist/{mailinglistId}
ParameterInTypeDescription
mailinglistIdpathintegerMailing list id Required.
contactsbodyCollection of ExternalBase

The request body is a JSON object (ExternalList).

Full reference, request and response samples

Create and send a new operational message

POST https://webapi.mymarketing.co.il/api/external/operational/message
ParameterInTypeDescription
packagebodyCollection of ApiExternalPackageExternalId and ExternalName with collection of pairs of keys and values you provide to replace your placeholders in the operational message per recipient
detailsbodyApiMessageDetailsMessage details Required.
designbodyApiMessageDesignMessage design Required.
bccbodyApiMessageBCCBCC emails

The request body is a JSON object (ApiExternalOperationalMessage).

Full reference, request and response samples

Create and send a new operational sms message

POST https://webapi.mymarketing.co.il/api/external/operational/sms_message
ParameterInTypeDescription
detailsbodyApiSMSCampaignDetailsSMS Campaign details
schedulingbodyApiSmsCampaignSchedulingScheduling the SMS campaign
customersbodyCollection of ApiExternalSMSThe list of customers that receive the SMS campaign

The request body is a JSON object (ApiExternalSmsCampaignPostContainer).

Full reference, request and response samples

Get contact's fields information

GET https://webapi.mymarketing.co.il/api/external/schema

No parameters.

Full reference, request and response samples

Get the list of contacts activities

GET https://webapi.mymarketing.co.il/api/external/activity

Get the list of contacts activities. You can get the list filtered by the status changed date (from/to date, the default is three months back) and limited to a number of contacts (up to 100 per call)

ParameterInTypeDescription
pagequeryinteger
limitqueryinteger
from-date-timequerydateStart of the date range. Format: mm-dd-yyyy.
to-date-timequerydateEnd of the date range. Format: mm-dd-yyyy.

Full reference, request and response samples

Get a contact's email activity by external ID and external name

GET https://webapi.mymarketing.co.il/api/external/statistics/mail

Get a contact's email activity by external ID and external name. If the two don't match, the response is empty.

ParameterInTypeDescription
externalIdquerystring Required.
externalNamequerystring Required.
from-date-timequerydateStart of the date range. Format: mm-dd-yyyy.
to-date-timequerydateEnd of the date range. Format: mm-dd-yyyy.

Full reference, request and response samples

Get a contact's SMS activity by external ID and external name

GET https://webapi.mymarketing.co.il/api/external/statistics/sms

Get a contact's SMS activity by external ID and external name. If the two don't match, the response is empty.

ParameterInTypeDescription
externalIdquerystring Required.
externalNamequerystring Required.
from-date-timequerydateStart of the date range. Format: mm-dd-yyyy. Required.
to-date-timequerydateEnd of the date range. Format: mm-dd-yyyy. Required.

Full reference, request and response samples

This reference is based on the ActiveTrail API documentation, where you can also test each endpoint with your own API key.