Actions

The ballerinax/salesforce.marketingcloud package exposes the following clients:

Client	Purpose
Client	Provides programmatic access to Salesforce Marketing Cloud REST APIs for journeys, events, campaigns, contacts, data extensions, assets, and messaging.

---

Client

Provides programmatic access to Salesforce Marketing Cloud REST APIs for journeys, events, campaigns, contacts, data extensions, assets, and messaging.

Configuration

Field	Type	Default	Description
auth	OAuth2ClientCredentialsGrantConfig	Required	OAuth 2.0 client credentials configuration with clientId, clientSecret, and accountId.
httpVersion	HttpVersion	HTTP_2_0	HTTP protocol version.
timeout	decimal	30	Request timeout in seconds.
retryConfig	RetryConfig	()	Retry configuration for failed requests.
secureSocket	ClientSecureSocket	()	SSL/TLS configuration.
proxy	ProxyConfig	()	Proxy server configuration.
circuitBreaker	CircuitBreakerConfig	()	Circuit breaker configuration for fault tolerance.
cache	CacheConfig	{}	HTTP caching configuration.
compression	Compression	AUTO	HTTP compression setting.
validation	boolean	true	Enable/disable payload validation.
laxDataBinding	boolean	true	Enable/disable lax data binding for responses.

Initializing the client

import ballerinax/salesforce.marketingcloud as mc;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string subDomain = ?;
configurable string accountId = ?;

mc:Client mcClient = check new (subDomain, {
    auth: {
        clientId,
        clientSecret,
        accountId
    }
});

Operations

Event management

getEventDefinitions

Retrieves a list of event definitions.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetEventDefinitionsQueries	No	Query parameters for filtering and pagination.

Returns: EventDefinitionList|error

Sample code:

mc:EventDefinitionList events = check mcClient->getEventDefinitions();

Sample response:

{"count": 2, "items": [{"id": "a1b2c3d4", "name": "Welcome Event", "type": "APIEvent", "eventDefinitionKey": "welcome-event-key"}, {"id": "e5f6g7h8", "name": "Purchase Event", "type": "APIEvent", "eventDefinitionKey": "purchase-event-key"}]}

createEventDefinition

Creates a new event definition.

Parameters:

Name	Type	Required	Description
payload	EventDefinition	Yes	The event definition to create.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: EventDefinition|error

Sample code:

mc:EventDefinition event = check mcClient->createEventDefinition({
    name: "New Signup Event",
    'type: "APIEvent",
    eventDefinitionKey: "new-signup-event"
});

Sample response:

{"id": "f9e8d7c6", "name": "New Signup Event", "type": "APIEvent", "eventDefinitionKey": "new-signup-event", "createdDate": "2025-01-15T10:30:00Z"}

getEventDefinitionByKey

Retrieves an event definition by its key.

Parameters:

Name	Type	Required	Description
eventDefinitionKey	string	Yes	Key of the event definition.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: EventDefinition|error

Sample code:

mc:EventDefinition event = check mcClient->getEventDefinitionByKey("welcome-event-key");

Sample response:

{"id": "a1b2c3d4", "name": "Welcome Event", "type": "APIEvent", "eventDefinitionKey": "welcome-event-key"}

updateEventDefinitionByKey

Updates an event definition identified by its key.

Parameters:

Name	Type	Required	Description
eventDefinitionKey	string	Yes	Key of the event definition.
payload	EventDefinition	Yes	Updated event definition payload.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: EventDefinition|error

Sample code:

mc:EventDefinition updated = check mcClient->updateEventDefinitionByKey("welcome-event-key", {
    name: "Updated Welcome Event",
    'type: "APIEvent",
    eventDefinitionKey: "welcome-event-key"
});

Sample response:

{"id": "a1b2c3d4", "name": "Updated Welcome Event", "type": "APIEvent", "eventDefinitionKey": "welcome-event-key"}

deleteEventDefinitionByKey

Deletes an event definition by its key.

Parameters:

Name	Type	Required	Description
eventDefinitionKey	string	Yes	Key of the event definition.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: json|error

Sample code:

json result = check mcClient->deleteEventDefinitionByKey("welcome-event-key");

Sample response:

{"message": "Event definition deleted successfully"}

updateEventDefinitionById

Updates an event definition identified by its ID.

Parameters:

Name	Type	Required	Description
eventDefinitionId	string	Yes	ID of the event definition.
payload	EventDefinition	Yes	Updated event definition payload.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: EventDefinition|error

Sample code:

mc:EventDefinition updated = check mcClient->updateEventDefinitionById("a1b2c3d4", {
    name: "Renamed Event",
    'type: "APIEvent",
    eventDefinitionKey: "welcome-event-key"
});

Sample response:

{"id": "a1b2c3d4", "name": "Renamed Event", "type": "APIEvent", "eventDefinitionKey": "welcome-event-key"}

deleteEventDefinitionById

Deletes an event definition by its ID.

Parameters:

Name	Type	Required	Description
eventDefinitionId	string	Yes	ID of the event definition.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: json|error

Sample code:

json result = check mcClient->deleteEventDefinitionById("a1b2c3d4");

Sample response:

{"message": "Event definition deleted successfully"}

fireEntryEvent

Fires an entry event to inject a contact into a journey.

Parameters:

Name	Type	Required	Description
payload	FireEvent	Yes	The event payload with contact key and event data.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: FireEventResponse|error

Sample code:

mc:FireEventResponse res = check mcClient->fireEntryEvent({
    contactKey: "[email protected]",
    eventDefinitionKey: "welcome-event-key",
    data: {
        "Email": "[email protected]",
        "FirstName": "Jane"
    }
});

Sample response:

{"requestId": "r1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6", "eventInstanceId": "e1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6"}

Journey management

getJourneys

Retrieves a list of journeys (interactions).

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetJourneysQueries	No	Query parameters for filtering and pagination.

Returns: JourneysList|error

Sample code:

mc:JourneysList journeys = check mcClient->getJourneys();

Sample response:

{"count": 1, "items": [{"id": "j1a2b3c4-d5e6-f7g8-h9i0", "key": "seasonal-journey", "name": "Seasonal Journey", "status": "Published", "version": 1}]}

createJourney

Creates a new journey (interaction).

Parameters:

Name	Type	Required	Description
payload	Journey	Yes	The journey definition to create.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Journey|error

Sample code:

mc:Journey journey = check mcClient->createJourney({
    name: "Welcome Journey",
    'key: "welcome-journey-key"
});

Sample response:

{"id": "j9e8d7c6-b5a4-3210", "key": "welcome-journey-key", "name": "Welcome Journey", "status": "Draft", "version": 1}

updateJourney

Updates an existing journey version.

Parameters:

Name	Type	Required	Description
payload	UpdateJourney	Yes	Updated journey payload.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Journey|error

Sample code:

mc:Journey updated = check mcClient->updateJourney({
    id: "j1a2b3c4-d5e6-f7g8-h9i0",
    name: "Updated Seasonal Journey",
    'key: "seasonal-journey"
});

Sample response:

{"id": "j1a2b3c4-d5e6-f7g8-h9i0", "key": "seasonal-journey", "name": "Updated Seasonal Journey", "status": "Draft", "version": 2}

getJourneyById

Retrieves a journey by its ID (UUID).

Parameters:

Name	Type	Required	Description
journeyId	string	Yes	ID of version 1 of the journey (UUID).
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetJourneyByIdQueries	No	Query parameters (e.g., extras).

Returns: Journey|error

Sample code:

mc:Journey journey = check mcClient->getJourneyById("j1a2b3c4-d5e6-f7g8-h9i0");

Sample response:

{"id": "j1a2b3c4-d5e6-f7g8-h9i0", "key": "seasonal-journey", "name": "Seasonal Journey", "status": "Published", "version": 1}

updateJourneyById

Updates an existing journey by its ID.

Parameters:

Name	Type	Required	Description
journeyId	string	Yes	ID of the journey (UUID).
payload	UpdateJourney	Yes	Updated journey payload.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Journey|error

Sample code:

mc:Journey updated = check mcClient->updateJourneyById("j1a2b3c4-d5e6-f7g8-h9i0", {
    name: "Renamed Journey"
});

Sample response:

{"id": "j1a2b3c4-d5e6-f7g8-h9i0", "name": "Renamed Journey", "status": "Draft", "version": 2}

deleteJourneyById

Deletes a journey by its ID. Deletes all versions unless a version number is specified.

Parameters:

Name	Type	Required	Description
journeyId	string	Yes	ID of the journey (UUID).
headers	map<string|string[]>	No	Optional HTTP headers.
queries	DeleteJourneyByIdQueries	No	Query parameters (e.g., versionNumber).

Returns: json|error

Sample code:

json result = check mcClient->deleteJourneyById("j1a2b3c4-d5e6-f7g8-h9i0");

Sample response:

{"message": "Journey deleted successfully"}

getJourneyByKey

Retrieves a journey by its key.

Parameters:

Name	Type	Required	Description
key	string	Yes	The key of the journey.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetJourneyByKeyQueries	No	Query parameters (e.g., extras).

Returns: Journey|error

Sample code:

mc:Journey journey = check mcClient->getJourneyByKey("seasonal-journey");

Sample response:

{"id": "j1a2b3c4-d5e6-f7g8-h9i0", "key": "seasonal-journey", "name": "Seasonal Journey", "status": "Published", "version": 1}

updateJourneyByKey

Updates an existing journey by its key.

Parameters:

Name	Type	Required	Description
key	string	Yes	The key of the journey.
payload	UpdateJourney	Yes	Updated journey payload.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Journey|error

Sample code:

mc:Journey updated = check mcClient->updateJourneyByKey("seasonal-journey", {
    name: "Updated Seasonal Journey"
});

Sample response:

{"id": "j1a2b3c4-d5e6-f7g8-h9i0", "key": "seasonal-journey", "name": "Updated Seasonal Journey", "status": "Draft", "version": 2}

deleteJourneyByKey

Deletes a journey by its key. Deletes all versions unless a version number is specified.

Parameters:

Name	Type	Required	Description
key	string	Yes	Key of the journey.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	DeleteJourneyByKeyQueries	No	Query parameters (e.g., versionNumber).

Returns: json|error

Sample code:

json result = check mcClient->deleteJourneyByKey("seasonal-journey");

Sample response:

{"message": "Journey deleted successfully"}

Contact membership & exit

getContactMembership

Retrieves the list of journeys a contact is currently enrolled in.

Parameters:

Name	Type	Required	Description
payload	ContactMembershipRequest	Yes	Request containing contact key list.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ContactMembershipResponse|error

Sample code:

mc:ContactMembershipResponse membership = check mcClient->getContactMembership({
    contactKeyList: ["[email protected]"]
});

Sample response:

{"results": {"contactMemberships": [{"contactKey": "[email protected]", "definitionKey": "aa0c871b-d1eb-66fb-c039-0a7cab4e20cd", "journeyName": "Seasonal Journey", "status": "Active"}]}}

removeContactFromJourney

Removes a contact from a journey.

Parameters:

Name	Type	Required	Description
payload	ContactExitRequest	Yes	Contact exit request payload.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ContactExitResponse|error

Sample code:

mc:ContactExitResponse res = check mcClient->removeContactFromJourney({
    contactKey: "[email protected]",
    definitionKey: "seasonal-journey-key"
});

Sample response:

{"status": "Accepted", "message": "Contact exit request received"}

getContactExitStatus

Retrieves the exit status of a contact removal request.

Parameters:

Name	Type	Required	Description
payload	ContactExitRequest	Yes	Contact exit request to check status for.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ContactExitStatusResponse|error

Sample code:

mc:ContactExitStatusResponse status = check mcClient->getContactExitStatus({
    contactKey: "[email protected]",
    definitionKey: "seasonal-journey-key"
});

Sample response:

{"contactKey": "[email protected]", "definitionKey": "seasonal-journey-key", "status": "Completed"}

Email validation

validateEmail

Validates an email address.

Parameters:

Name	Type	Required	Description
payload	ValidateEmailRequest	Yes	Request containing the email to validate.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ValidateEmailResponse|error

Sample code:

mc:ValidateEmailResponse validation = check mcClient->validateEmail({
    email: "[email protected]"
});

Sample response:

{"valid": true, "email": "[email protected]"}

Campaign management

getCampaigns

Retrieves a list of campaigns.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetCampaignsQueries	No	Query parameters for filtering and pagination.

Returns: CampaignList|error

Sample code:

mc:CampaignList campaigns = check mcClient->getCampaigns();

Sample response:

{"count": 2, "items": [{"id": "c001", "name": "Spring Sale 2025", "description": "Spring promotional campaign", "createdDate": "2025-03-01T00:00:00Z"}, {"id": "c002", "name": "Summer Campaign", "description": "Summer outreach", "createdDate": "2025-06-01T00:00:00Z"}]}

createCampaign

Creates a new campaign.

Parameters:

Name	Type	Required	Description
payload	UpsertCampaign	Yes	Campaign details to create.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Campaign|error

Sample code:

mc:Campaign campaign = check mcClient->createCampaign({
    name: "Holiday Campaign 2025",
    description: "End-of-year holiday promotions"
});

Sample response:

{"id": "c003", "name": "Holiday Campaign 2025", "description": "End-of-year holiday promotions", "createdDate": "2025-11-01T10:00:00Z"}

updateCampaign

Updates an existing campaign by its ID.

Parameters:

Name	Type	Required	Description
id	string	Yes	ID of the campaign to update.
payload	UpsertCampaign	Yes	Updated campaign details.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Campaign|error

Sample code:

mc:Campaign updated = check mcClient->updateCampaign("c003", {
    name: "Holiday Campaign 2025 (Updated)",
    description: "Revised holiday promotions"
});

Sample response:

{"id": "c003", "name": "Holiday Campaign 2025 (Updated)", "description": "Revised holiday promotions", "createdDate": "2025-11-01T10:00:00Z"}

deleteCampaign

Deletes a campaign by its ID.

Parameters:

Name	Type	Required	Description
id	string	Yes	ID of the campaign to delete.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check mcClient->deleteCampaign("c003");

Data extension operations

upsertDERowSetByKey

Upserts (inserts or updates) a set of rows in a Data Extension by its external key.

Parameters:

Name	Type	Required	Description
dEExternalKey	string	Yes	External key of the Data Extension.
payload	DataExtensionRowSet	Yes	Array of row objects with keys and values.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: DataExtensionRowSet|error

Sample code:

mc:DataExtensionRowSet result = check mcClient->upsertDERowSetByKey("DecSeasonal25", [
    {
        keys: {"id": "user-001"},
        values: {
            "SubscriberKey": "[email protected]",
            "EmailAddress": "[email protected]"
        }
    }
]);

Sample response:

[{"keys": {"id": "user-001"}, "values": {"SubscriberKey": "[email protected]", "EmailAddress": "[email protected]"}}]

deleteDERowSetByKey

Deletes a set of rows from a Data Extension by its external key.

Parameters:

Name	Type	Required	Description
dEExternalKey	string	Yes	External key of the Data Extension.
payload	DataExtensionRowSet	Yes	Array of row objects identifying rows to delete.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: DataExtensionRowSet|error

Sample code:

mc:DataExtensionRowSet deleted = check mcClient->deleteDERowSetByKey("DecSeasonal25", [
    {
        keys: {"id": "user-001"}
    }
]);

Sample response:

[{"keys": {"id": "user-001"}, "values": {}}]

upsertDERowSetByKeyAsync

Asynchronously upserts a set of rows in a Data Extension by its external key.

Parameters:

Name	Type	Required	Description
dEExternalKey	string	Yes	External key of the Data Extension.
payload	DataExtensionRowSet	Yes	Array of row objects with keys and values.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check mcClient->upsertDERowSetByKeyAsync("DecSeasonal25", [
    {
        keys: {"id": "user-002"},
        values: {
            "SubscriberKey": "[email protected]",
            "EmailAddress": "[email protected]"
        }
    }
]);

deleteDERowSetByKeyAsync

Asynchronously deletes a set of rows from a Data Extension by its external key.

Parameters:

Name	Type	Required	Description
dEExternalKey	string	Yes	External key of the Data Extension.
payload	DataExtensionRowSet	Yes	Array of row objects identifying rows to delete.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check mcClient->deleteDERowSetByKeyAsync("DecSeasonal25", [
    {
        keys: {"id": "user-002"}
    }
]);

Contact management

searchContactsByAttribute

Searches contacts by a specific attribute name.

Parameters:

Name	Type	Required	Description
attributeName	ContactAttributeName	Yes	The attribute name to search by.
payload	ContactAttributeFilterCondition	Yes	Filter conditions for the search.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: SearchContactsByAttributeResponse|error

Sample code:

mc:SearchContactsByAttributeResponse contacts = check mcClient->searchContactsByAttribute("email", {
    conditionSet: [{
        condition: {
            attribute: {
                key: "Email Address"
            },
            operator: "Equals",
            value: {items: ["[email protected]"]}
        }
    }]
});

Sample response:

{"items": [{"contactKey": "user-001", "values": {"Email Address": "[email protected]"}}]}

searchContactsByEmail

Searches contacts by email address.

Parameters:

Name	Type	Required	Description
payload	SearchContactsByEmailRequest	Yes	Request containing email addresses to search.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: SearchContactsByEmailResponse|error

Sample code:

mc:SearchContactsByEmailResponse results = check mcClient->searchContactsByEmail({
    emailAddresses: ["[email protected]"]
});

Sample response:

{"items": [{"contactKey": "user-001", "emailAddress": "[email protected]", "status": "Active"}]}

createContact

Creates a new contact.

Parameters:

Name	Type	Required	Description
payload	UpsertContactRequest	Yes	Contact details to create.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: UpsertContactResponse|error

Sample code:

mc:UpsertContactResponse res = check mcClient->createContact({
    contactKey: "user-003",
    attributeSets: []
});

Sample response:

{"contactKey": "user-003", "operationStatus": "Created"}

updateContact

Updates an existing contact.

Parameters:

Name	Type	Required	Description
payload	UpsertContactRequest	Yes	Updated contact details.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: UpsertContactResponse|error

Sample code:

mc:UpsertContactResponse res = check mcClient->updateContact({
    contactKey: "user-003",
    attributeSets: []
});

Sample response:

{"contactKey": "user-003", "operationStatus": "Updated"}

deleteContact

Submits a contact delete request.

Parameters:

Name	Type	Required	Description
payload	ContactDeleteRequest	Yes	Contact delete request payload.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	DeleteContactQueries	No	Query parameters for the delete operation.

Returns: ContactDeleteResponse|error

Sample code:

mc:ContactDeleteResponse res = check mcClient->deleteContact({
    contactKeys: ["user-003"]
});

Sample response:

{"requestId": "del-001", "status": "Accepted"}

getContactDeleteRequests

Retrieves details of contact delete requests.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetContactDeleteRequestsQueries	No	Query parameters for filtering.

Returns: ContactDeleteRequestsResponse|error

Sample code:

mc:ContactDeleteRequestsResponse requests = check mcClient->getContactDeleteRequests();

Sample response:

{"items": [{"requestId": "del-001", "status": "Completed", "completedDate": "2025-01-16T12:00:00Z"}]}

Contact preferences

getContactPreferencesByKey

Retrieves contact preferences by contact key.

Parameters:

Name	Type	Required	Description
contactKey	string	Yes	The contact key.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ContactPreferencesResponse|error

Sample code:

mc:ContactPreferencesResponse prefs = check mcClient->getContactPreferencesByKey("user-001");

Sample response:

{"contactKey": "user-001", "preferences": {"email": {"optedIn": true}, "sms": {"optedIn": false}}}

upsertContactPreferences

Creates or updates contact preferences.

Parameters:

Name	Type	Required	Description
payload	ContactPreferencesRequest	Yes	Preference data to upsert.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: UpsertContactPreferencesResponse|error

Sample code:

mc:UpsertContactPreferencesResponse res = check mcClient->upsertContactPreferences({
    contactKey: "user-001",
    preferences: {}
});

Sample response:

{"contactKey": "user-001", "operationStatus": "Updated"}

searchContactPreferences

Searches contact preferences based on filter criteria.

Parameters:

Name	Type	Required	Description
payload	SearchPreferencesRequest	Yes	Search criteria for preferences.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	SearchContactPreferencesQueries	No	Query parameters for pagination.

Returns: SearchPreferencesResponse|error

Sample code:

mc:SearchPreferencesResponse results = check mcClient->searchContactPreferences({
    contactKeyList: ["user-001", "user-002"]
});

Sample response:

{"items": [{"contactKey": "user-001", "preferences": {"email": {"optedIn": true}}}, {"contactKey": "user-002", "preferences": {"email": {"optedIn": false}}}]}

Asset management

getAssets

Retrieves a list of content assets from Content Builder.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetAssetsQueries	No	Query parameters for filtering and pagination.

Returns: AssetList|error

Sample code:

mc:AssetList assets = check mcClient->getAssets();

Sample response:

{"count": 1, "items": [{"id": 1001, "name": "hero-banner.png", "assetType": {"name": "png", "id": 28}, "category": {"id": 50, "name": "Images"}}]}

createAsset

Creates a new content asset in Content Builder.

Parameters:

Name	Type	Required	Description
payload	UpsertAsset	Yes	Asset details including name, type, category, and file data.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Asset|error

Sample code:

mc:Asset asset = check mcClient->createAsset({
    name: "promo-image.png",
    category: {"id": 50},
    assetType: {"name": "png", "id": 28}
});

Sample response:

{"id": 1002, "name": "promo-image.png", "assetType": {"name": "png", "id": 28}, "category": {"id": 50, "name": "Images"}, "createdDate": "2025-01-15T10:00:00Z"}

updateAsset

Updates an existing content asset by its ID.

Parameters:

Name	Type	Required	Description
id	int	Yes	ID of the content asset.
payload	UpsertAsset	Yes	Updated asset details.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Asset|error

Sample code:

mc:Asset updated = check mcClient->updateAsset(1002, {
    name: "promo-image-v2.png",
    category: {"id": 50},
    assetType: {"name": "png", "id": 28}
});

Sample response:

{"id": 1002, "name": "promo-image-v2.png", "assetType": {"name": "png", "id": 28}, "category": {"id": 50, "name": "Images"}}

deleteAsset

Deletes a content asset by its ID.

Parameters:

Name	Type	Required	Description
id	int	Yes	ID of the content asset to delete.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	DeleteAssetQueries	No	Query parameters for the delete operation.

Returns: error?

Sample code:

check mcClient->deleteAsset(1002);

Category management

getCategories

Retrieves a list of content categories from Content Builder.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetCategoriesQueries	No	Query parameters for filtering and pagination.

Returns: CategoryList|error

Sample code:

mc:CategoryList categories = check mcClient->getCategories();

Sample response:

{"count": 2, "items": [{"id": 50, "name": "Images", "parentId": 0}, {"id": 51, "name": "Templates", "parentId": 0}]}

createCategory

Creates a new content category in Content Builder.

Parameters:

Name	Type	Required	Description
payload	CreateCategory	Yes	Category details.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Category|error

Sample code:

mc:Category category = check mcClient->createCategory({
    name: "Campaign Assets",
    parentId: 0
});

Sample response:

{"id": 52, "name": "Campaign Assets", "parentId": 0}

Email messaging

getEmailDefinitions

Retrieves a list of email definitions.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetEmailDefinitionsQueries	No	Query parameters for filtering and pagination.

Returns: EmailDefinitionList|error

Sample code:

mc:EmailDefinitionList emailDefs = check mcClient->getEmailDefinitions();

Sample response:

{"count": 1, "definitions": [{"definitionKey": "welcome-email", "name": "Welcome Email", "status": "Active"}]}

createEmailDefinition

Creates a new email definition for transactional messaging.

Parameters:

Name	Type	Required	Description
payload	CreateEmailDefinition	Yes	Email definition details.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: EmailDefinition|error

Sample code:

mc:EmailDefinition emailDef = check mcClient->createEmailDefinition({
    name: "Order Confirmation",
    definitionKey: "order-confirmation",
    content: {
        customerKey: "order-confirm-content"
    }
});

Sample response:

{"definitionKey": "order-confirmation", "name": "Order Confirmation", "status": "Active", "createdDate": "2025-01-15T10:00:00Z"}

sendEmailMessage

Sends a transactional email message using an email definition.

Parameters:

Name	Type	Required	Description
payload	SendEmailMessageRequest	Yes	Email send request with recipient and definition key.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: SendEmailMessageResponse|error

Sample code:

mc:SendEmailMessageResponse res = check mcClient->sendEmailMessage({
    definitionKey: "order-confirmation",
    recipient: {
        contactKey: "[email protected]",
        to: "[email protected]"
    }
});

Sample response:

{"requestId": "msg-001", "responses": [{"messageKey": "mk-001", "status": "Accepted"}]}

Bulk data operations

importDataExtensionAsync

Submits an asynchronous import request for a Data Extension file.

Parameters:

Name	Type	Required	Description
payload	ImportRequest	Yes	Import request details including file location and Data Extension key.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ImportResponse|error

Sample code:

mc:ImportResponse res = check mcClient->importDataExtensionAsync({
    dataExtensionKey: "DecSeasonal25",
    fileName: "contacts.csv"
});

Sample response:

{"importId": 12345, "status": "Accepted", "message": "Import request accepted for processing"}

getImportSummary

Retrieves the summary of a Data Extension import operation.

Parameters:

Name	Type	Required	Description
id	int	Yes	The unique identifier for the import operation.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ImportSummaryResponse|error

Sample code:

mc:ImportSummaryResponse summary = check mcClient->getImportSummary(12345);

Sample response:

{"importId": 12345, "status": "Completed", "totalRows": 500, "importedRows": 498, "skippedRows": 2}

createBulkIngestJob

Creates a bulk ingest job to insert rows into a Data Extension.

Parameters:

Name	Type	Required	Description
payload	CreateBulkIngestJob	Yes	Bulk ingest job configuration.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CreateBulkIngestJobResponse|error

Sample code:

mc:CreateBulkIngestJobResponse job = check mcClient->createBulkIngestJob({
    dataExtensionKey: "DecSeasonal25"
});

Sample response:

{"jobId": "bulk-001", "status": "Created", "dataExtensionKey": "DecSeasonal25"}