Silverpop Email Marketing

naftiko: "1.0.0-alpha1"

info:
  label: "Silverpop Email Marketing"
  description: "Workflow capability for email marketing and campaign management using Silverpop (Acoustic Campaign). Covers the full campaign lifecycle: contact management, campaign creation and scheduling, transactional messaging, engagement reporting, and marketing automation programs."
  tags:
  - Email Marketing
  - Campaign Management
  - Marketing Automation
  - Contact Management
  - Reporting
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SILVERPOP_ACCESS_TOKEN: SILVERPOP_ACCESS_TOKEN

capability:
  consumes:
    - import: silverpop
      location: ./shared/silverpop.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: email-marketing-api
      description: "Unified REST API for email marketing and campaign management via Silverpop/Acoustic."
      resources:
        - path: /v1/databases
          name: databases
          description: "Contact database management."
          operations:
            - method: GET
              name: list-databases
              description: "List all contact databases."
              call: "silverpop.list-databases"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/databases/{id}/contacts
          name: contacts
          description: "Contact management within a database."
          operations:
            - method: GET
              name: list-contacts
              description: "List contacts in a database."
              call: "silverpop.list-contacts"
              with:
                database_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: add-contact
              description: "Add a new contact to a database."
              call: "silverpop.add-contact"
              with:
                database_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/databases/{db_id}/contacts/{contact_id}
          name: contact
          description: "Single contact operations."
          operations:
            - method: GET
              name: get-contact
              description: "Get a contact's details."
              call: "silverpop.get-contact"
              with:
                database_id: "rest.db_id"
                contact_id: "rest.contact_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: update-contact
              description: "Update a contact's attributes."
              call: "silverpop.update-contact"
              with:
                database_id: "rest.db_id"
                contact_id: "rest.contact_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: remove-contact
              description: "Remove a contact from a database."
              call: "silverpop.remove-contact"
              with:
                database_id: "rest.db_id"
                contact_id: "rest.contact_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/campaigns
          name: campaigns
          description: "Email campaign management."
          operations:
            - method: GET
              name: list-campaigns
              description: "List all email campaigns."
              call: "silverpop.list-campaigns"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-campaign
              description: "Create a new email campaign."
              call: "silverpop.create-campaign"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/campaigns/{id}
          name: campaign
          description: "Single campaign operations."
          operations:
            - method: GET
              name: get-campaign
              description: "Get campaign details."
              call: "silverpop.get-campaign"
              with:
                mailing_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/campaigns/{id}/schedule
          name: campaign-schedule
          description: "Campaign scheduling."
          operations:
            - method: POST
              name: schedule-campaign
              description: "Schedule a campaign for delivery."
              call: "silverpop.schedule-campaign"
              with:
                mailing_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/campaigns/{id}/reports/summary
          name: campaign-summary
          description: "Campaign performance summary."
          operations:
            - method: GET
              name: get-campaign-summary
              description: "Get campaign aggregate performance metrics."
              call: "silverpop.get-campaign-summary"
              with:
                mailing_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/campaigns/{id}/reports/opens
          name: campaign-opens
          description: "Campaign open events."
          operations:
            - method: GET
              name: get-campaign-opens
              description: "Get campaign open event data."
              call: "silverpop.get-campaign-opens"
              with:
                mailing_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/campaigns/{id}/reports/clicks
          name: campaign-clicks
          description: "Campaign click events."
          operations:
            - method: GET
              name: get-campaign-clicks
              description: "Get campaign click event data."
              call: "silverpop.get-campaign-clicks"
              with:
                mailing_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/programs
          name: programs
          description: "Marketing automation programs."
          operations:
            - method: GET
              name: list-programs
              description: "List all marketing automation programs."
              call: "silverpop.list-programs"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/programs/{id}
          name: program
          description: "Single program operations."
          operations:
            - method: GET
              name: get-program
              description: "Get program details and status."
              call: "silverpop.get-program"
              with:
                program_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: email-marketing-mcp
      transport: http
      description: "MCP server for AI-assisted email marketing and campaign management."
      tools:
        - name: list-databases
          description: "List all contact databases (lists) in the Silverpop account."
          hints:
            readOnly: true
            openWorld: true
          call: "silverpop.list-databases"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-contacts
          description: "List contacts in a specific database with pagination."
          hints:
            readOnly: true
            openWorld: true
          call: "silverpop.list-contacts"
          with:
            database_id: "tools.database_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: add-contact
          description: "Add a new contact to a Silverpop database."
          hints:
            readOnly: false
          call: "silverpop.add-contact"
          with:
            database_id: "tools.database_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-contact
          description: "Get a specific contact's profile and custom fields."
          hints:
            readOnly: true
          call: "silverpop.get-contact"
          with:
            database_id: "tools.database_id"
            contact_id: "tools.contact_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-contact
          description: "Update a contact's attributes and custom fields."
          hints:
            readOnly: false
            idempotent: true
          call: "silverpop.update-contact"
          with:
            database_id: "tools.database_id"
            contact_id: "tools.contact_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: remove-contact
          description: "Remove (opt-out) a contact from a database."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "silverpop.remove-contact"
          with:
            database_id: "tools.database_id"
            contact_id: "tools.contact_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-campaigns
          description: "List all email campaigns with optional status filtering."
          hints:
            readOnly: true
            openWorld: true
          call: "silverpop.list-campaigns"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-campaign
          description: "Create a new email campaign mailing."
          hints:
            readOnly: false
          call: "silverpop.create-campaign"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-campaign
          description: "Get details of a specific email campaign."
          hints:
            readOnly: true
          call: "silverpop.get-campaign"
          with:
            mailing_id: "tools.mailing_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: schedule-campaign
          description: "Schedule a campaign for delivery at a specific date and time."
          hints:
            readOnly: false
          call: "silverpop.schedule-campaign"
          with:
            mailing_id: "tools.mailing_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-campaign-summary
          description: "Get aggregate performance metrics for a sent campaign (opens, clicks, unsubscribes, bounces)."
          hints:
            readOnly: true
          call: "silverpop.get-campaign-summary"
          with:
            mailing_id: "tools.mailing_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-campaign-opens
          description: "Get detailed open event records for a campaign."
          hints:
            readOnly: true
            openWorld: true
          call: "silverpop.get-campaign-opens"
          with:
            mailing_id: "tools.mailing_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-campaign-clicks
          description: "Get detailed click-through event records for a campaign."
          hints:
            readOnly: true
            openWorld: true
          call: "silverpop.get-campaign-clicks"
          with:
            mailing_id: "tools.mailing_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-programs
          description: "List all marketing automation programs."
          hints:
            readOnly: true
            openWorld: true
          call: "silverpop.list-programs"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-program
          description: "Get details and status of a specific marketing automation program."
          hints:
            readOnly: true
          call: "silverpop.get-program"
          with:
            program_id: "tools.program_id"
          outputParameters:
            - type: object
              mapping: "$."