Salesforce Marketing Cloud REST API

openapi: 3.1.0
info:
  title: Salesforce Marketing Cloud REST API
  description: >
    The Salesforce Marketing Cloud REST API provides access to Marketing Cloud
    resources including contacts, journeys, data extensions, triggered sends,
    and transactional messaging. It uses OAuth 2.0 for authentication and is
    the primary interface for programmatic Marketing Cloud integrations.
  version: v1
  contact:
    name: Salesforce Marketing Cloud Developers
    url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rest-api.html
  license:
    name: Salesforce Developer Terms
    url: https://www.salesforce.com/company/legal/agreements/
servers:
  - url: https://{subdomain}.rest.marketingcloudapis.com
    description: >
      Marketing Cloud REST API endpoint. The subdomain is the tenant-specific
      subdomain for the Marketing Cloud account.
    variables:
      subdomain:
        default: YOUR_SUBDOMAIN
        description: >
          The Marketing Cloud tenant subdomain (also known as the MID-specific
          subdomain). Obtain this from the Marketing Cloud Setup > Company
          Settings > Account Info.
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: >
      OAuth 2.0 token operations for obtaining access tokens using client
      credentials or authorization code flows.
  - name: Contacts
    description: >
      Operations for listing, retrieving, and deleting Marketing Cloud contact
      records.
  - name: Data Extensions
    description: >
      Operations for reading and writing rows in Marketing Cloud Data
      Extensions, which are custom tables for storing subscriber data and
      campaign data.
  - name: Messaging
    description: >
      Operations for creating and tracking email and SMS message sends,
      including triggered sends and transactional messages.
  - name: Journeys
    description: >
      Operations for listing and retrieving Marketing Cloud Journey Builder
      journeys (interactions) and firing journey entry events.
  - name: Assets
    description: >
      Operations for managing Marketing Cloud Content Builder assets including
      emails, images, and other content items.
paths:
  /v2/token:
    post:
      operationId: getAccessToken
      summary: Get an access token
      description: >
        Obtains an OAuth 2.0 access token for authenticating subsequent API
        requests. Supports both client credentials (server-to-server) and
        authorization code grant types. The access token should be included in
        the Authorization header as "Bearer {access_token}" for all API calls.
        Tokens expire after a defined period; request a new token when needed.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        description: OAuth 2.0 token request parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token obtained successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: >
            Bad request. Invalid client credentials, grant type, or request
            parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid client ID or client secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contacts/v1/contacts:
    get:
      operationId: listContacts
      summary: List contacts
      description: >
        Returns a paginated list of contacts in the Marketing Cloud account.
        Contacts are the core subscriber entities that can be subscribed to
        email, SMS, or other channels. Use the page and pageSize parameters to
        paginate through large contact lists.
      tags:
        - Contacts
      parameters:
        - name: page
          in: query
          required: false
          description: The page number to retrieve. Defaults to 1.
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: pageSize
          in: query
          required: false
          description: The number of contacts to return per page. Defaults to 50.
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: Paginated list of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of contact records.
                    items:
                      $ref: '#/components/schemas/Contact'
                  count:
                    type: integer
                    description: Total number of contacts matching the request.
                  page:
                    type: integer
                    description: The current page number.
                  pageSize:
                    type: integer
                    description: The number of items per page.
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteContacts
      summary: Delete contacts
      description: >
        Deletes one or more contacts from Marketing Cloud. Deletion is
        asynchronous; the response indicates the operation was accepted. Contact
        deletion removes the contact and their data across all business units
        in the account.
      tags:
        - Contacts
      requestBody:
        required: true
        description: Contact keys identifying the contacts to delete.
        content:
          application/json:
            schema:
              type: object
              required:
                - contactKeys
              properties:
                contactKeys:
                  type: array
                  description: Array of contact keys (subscriber keys) to delete.
                  items:
                    type: string
                deleteOperationType:
                  type: string
                  enum:
                    - ContactAndAttributes
                    - BusinessUnit
                    - Enterprise
                  description: >
                    The scope of the deletion operation. ContactAndAttributes
                    deletes the contact and all attribute data. BusinessUnit
                    deletes the contact from the current business unit.
                    Enterprise deletes from all business units.
      responses:
        '200':
          description: Contact deletion request accepted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestServiceMessageID:
                    type: string
                    description: >
                      Unique ID for the deletion request. Use this to track the
                      deletion status.
                  resultMessages:
                    type: array
                    description: Result messages for the deletion request.
                    items:
                      type: string
        '400':
          description: Bad request. Invalid contact keys or deletion type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contacts/v1/contacts/{contactKey}:
    get:
      operationId: getContact
      summary: Get a contact by contact key
      description: >
        Retrieves a single Marketing Cloud contact by their contact key. The
        contact key is a unique identifier for the contact, typically the
        subscriber key or email address used when the contact was created.
      tags:
        - Contacts
      parameters:
        - name: contactKey
          in: path
          required: true
          description: >
            The unique contact key (subscriber key) of the Marketing Cloud
            contact to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: The requested Marketing Cloud contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Contact not found for the specified contact key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /data/v1/async/dataextensions/key:{key}/rows:
    get:
      operationId: getDataExtensionRows
      summary: Get Data Extension rows
      description: >
        Retrieves rows from a Marketing Cloud Data Extension identified by its
        external key. Data Extensions are custom tables for storing subscriber
        data, lookup tables, or any structured data used in campaigns and
        journeys. Use the $pageSize and $page parameters to paginate through
        large data sets.
      tags:
        - Data Extensions
      parameters:
        - name: key
          in: path
          required: true
          description: >
            The external key of the Data Extension. Find this in Marketing
            Cloud Email Studio under the Data Extension properties.
          schema:
            type: string
        - name: $pageSize
          in: query
          required: false
          description: The number of rows to return per page. Defaults to 50.
          schema:
            type: integer
            default: 50
        - name: $page
          in: query
          required: false
          description: The page number to retrieve. Defaults to 1.
          schema:
            type: integer
            default: 1
        - name: $orderBy
          in: query
          required: false
          description: >
            Field name and direction for sorting results (e.g., "LastName ASC"
            or "CreatedDate DESC").
          schema:
            type: string
      responses:
        '200':
          description: Paginated rows from the Data Extension.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of rows in the Data Extension.
                  page:
                    type: integer
                    description: The current page number.
                  pageSize:
                    type: integer
                    description: The number of rows per page.
                  items:
                    type: array
                    description: Array of Data Extension row objects.
                    items:
                      $ref: '#/components/schemas/DataExtensionRow'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Data Extension not found for the specified key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: insertDataExtensionRows
      summary: Insert rows into a Data Extension
      description: >
        Inserts one or more rows into a Marketing Cloud Data Extension. If a row
        with the same primary key already exists, the operation upserts the row
        (updates existing values). Returns the number of rows inserted or
        updated.
      tags:
        - Data Extensions
      parameters:
        - name: key
          in: path
          required: true
          description: The external key of the Data Extension to insert rows into.
          schema:
            type: string
      requestBody:
        required: true
        description: Array of Data Extension rows to insert or upsert.
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  description: >
                    Array of row objects to insert. Each object contains
                    key-value pairs matching the Data Extension column names.
                  items:
                    $ref: '#/components/schemas/DataExtensionRow'
      responses:
        '200':
          description: Rows inserted or updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: Unique ID for this insert request.
        '400':
          description: >
            Bad request. Invalid row data, missing required columns, or data
            type mismatch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Data Extension not found for the specified key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /messaging/v1/email/messages:
    post:
      operationId: createEmailSend
      summary: Create an email send (triggered send)
      description: >
        Creates and initiates a triggered email send to one or more recipients.
        Each send requires a message definition key referencing a triggered send
        definition configured in Marketing Cloud Email Studio. Supports
        personalization attributes and subscriber data overrides.
      tags:
        - Messaging
      requestBody:
        required: true
        description: Email message send configuration and recipients.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailMessage'
      responses:
        '202':
          description: >
            Email send request accepted. The send is queued for processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: Unique ID for this send request.
                  responses:
                    type: array
                    description: >
                      Array of recipient-level responses indicating acceptance
                      or errors.
                    items:
                      type: object
                      properties:
                        recipientSendId:
                          type: string
                          description: >
                            Unique ID for this recipient's send. Use as the
                            messageKey in status lookups.
                        hasErrors:
                          type: boolean
                          description: Whether this recipient's request had errors.
                        messages:
                          type: array
                          description: >
                            Error messages if hasErrors is true.
                          items:
                            type: string
        '400':
          description: Bad request. Invalid message definition or recipient data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /messaging/v1/sms/messages:
    post:
      operationId: createSmsSend
      summary: Create an SMS send
      description: >
        Creates and initiates an SMS message send to one or more recipients.
        Requires a message definition key referencing an SMS definition
        configured in Marketing Cloud MobileConnect. Supports personalization
        attributes for dynamic message content.
      tags:
        - Messaging
      requestBody:
        required: true
        description: SMS message send configuration and recipients.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMSMessage'
      responses:
        '202':
          description: SMS send request accepted and queued for processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: Unique ID for this SMS send request.
                  responses:
                    type: array
                    description: Array of recipient-level send responses.
                    items:
                      type: object
                      properties:
                        recipientSendId:
                          type: string
                          description: Unique ID for this recipient's SMS send.
                        hasErrors:
                          type: boolean
                          description: Whether this recipient's request had errors.
        '400':
          description: Bad request. Invalid message definition or phone number format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /messaging/v1/email/messages/{messageKey}:
    get:
      operationId: getMessageStatus
      summary: Get email message send status
      description: >
        Retrieves the status of a triggered email send for a specific recipient
        using the messageKey (recipientSendId) returned when the send was
        created. Returns the current delivery status and any error details.
      tags:
        - Messaging
      parameters:
        - name: messageKey
          in: path
          required: true
          description: >
            The unique message key (recipientSendId) returned when the email
            send was created.
          schema:
            type: string
      responses:
        '200':
          description: Email message send status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  eventCategoryType:
                    type: string
                    description: >
                      The delivery event type (e.g., SendReady,
                      NotSent, Sent, Delivered, Bounced, Opened, Clicked).
                  timestamp:
                    type: string
                    format: date-time
                    description: The timestamp of the most recent status event.
                  subscriberKey:
                    type: string
                    description: The subscriber key of the recipient.
                  messageKey:
                    type: string
                    description: The unique message key for this send.
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found for the specified message key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /interaction/v1/interactions:
    get:
      operationId: listJourneys
      summary: List journeys
      description: >
        Returns a paginated list of Marketing Cloud Journey Builder journeys
        (interactions). Includes both active and inactive journeys. Use the
        page and pageSize parameters to paginate. Can filter by journey status.
      tags:
        - Journeys
      parameters:
        - name: page
          in: query
          required: false
          description: The page number to retrieve. Defaults to 1.
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          description: The number of journeys to return per page. Defaults to 50.
          schema:
            type: integer
            default: 50
        - name: status
          in: query
          required: false
          description: >
            Filter journeys by status. Use Draft, Published, ScheduledToSend,
            Stopped, or Deleted.
          schema:
            type: string
            enum:
              - Draft
              - Published
              - ScheduledToSend
              - Stopped
              - Deleted
      responses:
        '200':
          description: Paginated list of journeys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of journeys matching the filter.
                  page:
                    type: integer
                    description: The current page number.
                  pageSize:
                    type: integer
                    description: The number of journeys per page.
                  items:
                    type: array
                    description: Array of journey objects.
                    items:
                      $ref: '#/components/schemas/Journey'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /interaction/v1/interactions/{interactionId}:
    get:
      operationId: getJourney
      summary: Get a journey by ID
      description: >
        Retrieves detailed information about a specific Marketing Cloud Journey
        Builder journey, including its activities, triggers, goals, and current
        status.
      tags:
        - Journeys
      parameters:
        - name: interactionId
          in: path
          required: true
          description: The unique ID of the journey (interaction) to retrieve.
          schema:
            type: string
        - name: versionNumber
          in: query
          required: false
          description: >
            The version number of the journey to retrieve. If not specified,
            returns the latest version.
          schema:
            type: integer
      responses:
        '200':
          description: Detailed information about the specified journey.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Journey not found for the specified interaction ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /interaction/v1/events:
    post:
      operationId: fireJourneyEvent
      summary: Fire a journey entry event
      description: >
        Fires an event that causes contacts to enter a Marketing Cloud Journey
        Builder journey at the specified event-triggered entry source. The
        event definition key must match an API event or custom event configured
        as the journey's entry source. Supports passing contact data to
        personalize the journey experience.
      tags:
        - Journeys
      requestBody:
        required: true
        description: Journey entry event data including the contact and event details.
        content:
          application/json:
            schema:
              type: object
              required:
                - ContactKey
                - EventDefinitionKey
              properties:
                ContactKey:
                  type: string
                  description: >
                    The subscriber key of the contact entering the journey.
                EventDefinitionKey:
                  type: string
                  description: >
                    The external key of the event definition configured as the
                    journey entry source.
                Data:
                  type: object
                  description: >
                    Additional data attributes to pass with the event for
                    personalization within the journey.
                  additionalProperties: true
      responses:
        '201':
          description: Journey entry event fired successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: Unique ID for this event request.
                  eventInstanceId:
                    type: string
                    description: Unique ID for this specific event instance.
        '400':
          description: >
            Bad request. Invalid event definition key, contact key, or event
            data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /asset/v1/content/assets:
    get:
      operationId: listAssets
      summary: List content assets
      description: >
        Returns a paginated list of Marketing Cloud Content Builder assets
        including emails, images, documents, and other content items. Supports
        filtering by asset type and searching by name.
      tags:
        - Assets
      parameters:
        - name: page
          in: query
          required: false
          description: The page number to retrieve. Defaults to 1.
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          description: The number of assets to return per page. Defaults to 50.
          schema:
            type: integer
            default: 50
        - name: assetType
          in: query
          required: false
          description: >
            Filter by asset type name (e.g., templatebasedemail,
            htmlemail, image, document, block).
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of content assets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of assets matching the filter.
                  page:
                    type: integer
                    description: The current page number.
                  pageSize:
                    type: integer
                    description: The number of assets per page.
                  items:
                    type: array
                    description: Array of content asset objects.
                    items:
                      $ref: '#/components/schemas/ContentAsset'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createAsset
      summary: Create a content asset
      description: >
        Creates a new content asset in Marketing Cloud Content Builder. Assets
        can be emails, templates, images, blocks, or other content types.
        The asset type is specified using the assetType object. File content
        can be provided inline as a base64 string or referenced by URL.
      tags:
        - Assets
      requestBody:
        required: true
        description: Content asset definition to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentAsset'
      responses:
        '201':
          description: Content asset created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAsset'
        '400':
          description: Bad request. Invalid asset definition or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /asset/v1/content/assets/{id}:
    get:
      operationId: getAsset
      summary: Get a content asset by ID
      description: >
        Retrieves a single Marketing Cloud Content Builder asset by its numeric
        ID. Returns the asset metadata and content.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/assetId'
      responses:
        '200':
          description: The requested content asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAsset'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Asset not found for the specified ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateAsset
      summary: Update a content asset
      description: >
        Replaces the content and metadata of an existing Marketing Cloud Content
        Builder asset. The entire asset definition must be provided; partial
        updates are not supported. Returns the updated asset.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/assetId'
      requestBody:
        required: true
        description: Complete updated content asset definition.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentAsset'
      responses:
        '200':
          description: Content asset updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAsset'
        '400':
          description: Bad request. Invalid asset definition or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Asset not found for the

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/salesforce/refs/heads/main/openapi/salesforce-marketing-cloud-rest-openapi.yml