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
| Method | Endpoint | What it does |
|---|---|---|
GET | /api/ | Get contact by the external id and name |
GET | /api/ | Get the contact list |
GET | /api/ | Get the list of contacts (those that have external id and external name) |
GET | /api/ | Get the list of unmapped contacts (those that have no external id or external name) |
POST | /api/ | Import contacts |
POST | /api/ | Map external id and external name to unmapped contact |
DELETE | /api/ | Unmap contact's external id and name based on the provided details |
PUT | /api/ | Update the given contact |
DELETE | /api/ | Delete the given contact by providing external id and external name |
POST | /api/ | Add contact to group with the given external id and external name |
POST | /api/ | Add contact to mailing list with the given external id and external name |
DELETE | /api/ | Delete contacts from group with the given external id and external name |
DELETE | /api/ | Delete contacts from mailing list with the given external id and external name |
POST | /api/ | Create and send a new operational message |
POST | /api/ | Create and send a new operational sms message |
GET | /api/ | Get contact's fields information |
GET | /api/ | Get the list of contacts activities |
GET | /api/ | Get a contact's email activity by external ID and external name |
GET | /api/ | Get 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.
| Parameter | In | Type | Description |
|---|---|---|---|
externalId | path | string | External id Required. |
externalName | query | string | External 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
| Parameter | In | Type | Description |
|---|---|---|---|
email | query | string | The email of the contacts you would like to get. Required if SMS is not in use |
sms | query | string | The 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)
| Parameter | In | Type | Description |
|---|---|---|---|
customer_states | query | CustomerStates | Filter by contact status. Values: ALL, ACTIVE, INACTIVE, CUSTOMER_REQUEST, BOUNCED, SPAM_COMPLIENT, QUARANTINED. |
from_date | query | date | Start of the date range. |
to_date | query | date | End of the date range. |
page | query | integer | Get a specific page (number of pages is limited) (Range: inclusive between 1 and 2147483647) |
limit | query | integer | Limit 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)
| Parameter | In | Type | Description |
|---|---|---|---|
customer_states | query | CustomerStates | Filter by contact status. Values: ALL, ACTIVE, INACTIVE, CUSTOMER_REQUEST, BOUNCED, SPAM_COMPLIENT, QUARANTINED. |
from_date | query | date | Start of the date range. Format: mm-dd-yyyy. |
to_date | query | date | End of the date range. Format: mm-dd-yyyy. |
page | query | integer | Get a specific page (number of pages is limited) (Range: inclusive between 1 and 2147483647) |
limit | query | integer | Limit 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
| Parameter | In | Type | Description |
|---|---|---|---|
mailing_list | body | integer | Mailing 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) |
group | body | integer | Group 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) |
contacts | body | Collection of ApiExternalContact | Contacts - 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
| Parameter | In | Type | Description |
|---|---|---|---|
customerId | body | integer | Contact's ID. can be found using the endpoint "Get the list of unmapped contacts" |
externalId | body | string | The external id of contact. Required in a post endpoint. |
externalName | body | string | The 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
| Parameter | In | Type | Description |
|---|---|---|---|
externalId | path | string | External id. Required. |
externalName | query | string | External name. Required. |
Full reference, request and response samples
Update the given contact
PUT https://webapi.mymarketing.co.il/api/external/contact/{externalId}
| Parameter | In | Type | Description |
|---|---|---|---|
externalId | path | string | External id. Required. |
externalName | query | string | External name. Required. |
contact | body | UpdateContactContainer | See 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
| Parameter | In | Type | Description |
|---|---|---|---|
externalId | path | string | External id. Required. |
externalName | query | string | External 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.
| Parameter | In | Type | Description |
|---|---|---|---|
groupId | path | integer | Group 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. |
contacts | body | Collection 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.
| Parameter | In | Type | Description |
|---|---|---|---|
mailinglistId | path | integer | Mailing 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. |
contacts | body | Collection 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}
| Parameter | In | Type | Description |
|---|---|---|---|
groupId | path | integer | Group id Required. |
contacts | body | Collection 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}
| Parameter | In | Type | Description |
|---|---|---|---|
mailinglistId | path | integer | Mailing list id Required. |
contacts | body | Collection 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
| Parameter | In | Type | Description |
|---|---|---|---|
package | body | Collection of ApiExternalPackage | ExternalId and ExternalName with collection of pairs of keys and values you provide to replace your placeholders in the operational message per recipient |
details | body | ApiMessageDetails | Message details Required. |
design | body | ApiMessageDesign | Message design Required. |
bcc | body | ApiMessageBCC | BCC 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
| Parameter | In | Type | Description |
|---|---|---|---|
details | body | ApiSMSCampaignDetails | SMS Campaign details |
scheduling | body | ApiSmsCampaignScheduling | Scheduling the SMS campaign |
customers | body | Collection of ApiExternalSMS | The 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)
| Parameter | In | Type | Description |
|---|---|---|---|
page | query | integer | |
limit | query | integer | |
from-date-time | query | date | Start of the date range. Format: mm-dd-yyyy. |
to-date-time | query | date | End 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.
| Parameter | In | Type | Description |
|---|---|---|---|
externalId | query | string | Required. |
externalName | query | string | Required. |
from-date-time | query | date | Start of the date range. Format: mm-dd-yyyy. |
to-date-time | query | date | End 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.
| Parameter | In | Type | Description |
|---|---|---|---|
externalId | query | string | Required. |
externalName | query | string | Required. |
from-date-time | query | date | Start of the date range. Format: mm-dd-yyyy. Required. |
to-date-time | query | date | End 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.