SoftSync AI Email API

openapi: 3.2.0
info:
  title: Softsync Email API
  description: '## Introduction


    The Softsync Platform API


    This API lets you read and write your Softsync data from your own applications. Authenticate with a personal API key created in **Settings → API Keys**, sent as the `x-api-key` header.


    **New here?** Read **Concepts** first, then **Authentication**, then **Quickstart: full cycle** — it walks the whole thing end to end. **Objects**, **Records**, **Groups & Views** and **Notes** cover each area in depth, and **Code Generation** shows how to turn this document into a typed client.


    To try a request from this page, paste your API key into the **Authentication** panel on the right.


    ## Support


    If you need help with API access or integration details, contact contact@softsync.ai.'
  version: 0.1.0
  contact: {}
servers: []
security:
- x-api-key: []
tags:
- name: Email
paths:
  /openapi/email/mailboxes:
    get:
      description: Start here before sending. Each entry returns an `integrationId` to pass to sendEmail or sendEmailCampaign. If the list is empty, no mailbox has been connected yet and sending will fail — a mailbox must be connected in the app first, as it requires an interactive sign-in.
      operationId: listEmailMailboxes
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMailboxListDto'
      security:
      - bearer: []
      summary: List the connected Gmail and Outlook mailboxes this workspace can send from
      tags:
      - Email
      x-feature: messages
  /openapi/email/templates:
    get:
      description: Optionally filter to templates written for one object with `tableId`. A template can only be sent to records of the object it was written for.
      operationId: listEmailTemplates
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: tableId
        required: false
        in: query
        description: Return only templates written for this object, e.g. the contacts object.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateListDto'
      security:
      - bearer: []
      summary: List the reusable email templates in this workspace
      tags:
      - Email
      x-feature: messages
    post:
      description: A template is tied to one object via `tableId` and can only be sent to records of that object. Use `{{field_api_name}}` in the subject or body to insert values from each recipient’s record — call listEmailTemplateVariables first to see which names are valid. Requires the Editor or Admin role.
      operationId: createEmailTemplate
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailTemplateDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateDto'
        '403':
          description: Insufficient permissions
      security:
      - bearer: []
      summary: Create a reusable email template
      tags:
      - Email
      x-feature: messages
  /openapi/email/templates/variables:
    get:
      description: Call this before writing a template. Each returned `name` can be written as `{{name}}` in a subject or body and is replaced with that value from each recipient’s record when the email goes out. A placeholder that is not in this list renders as empty text rather than failing.
      operationId: listEmailTemplateVariables
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: tableId
        required: true
        in: query
        description: The object whose records will receive the email, e.g. the contacts object.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateVariableListDto'
      security:
      - bearer: []
      summary: List the `{{placeholders}}` you can use in a template aimed at a given object
      tags:
      - Email
      x-feature: messages
  /openapi/email/templates/{templateId}:
    get:
      operationId: getEmailTemplate
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: templateId
        required: true
        in: path
        description: Template identifier.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateDto'
        '404':
          description: Template not found
      security:
      - bearer: []
      summary: Get one email template, including its subject and body
      tags:
      - Email
      x-feature: messages
    patch:
      description: Only the fields you send are changed. The object a template targets cannot be changed after creation — create a new template instead. Requires the Editor or Admin role.
      operationId: updateEmailTemplate
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: templateId
        required: true
        in: path
        description: Template identifier.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailTemplateDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateDto'
        '403':
          description: Insufficient permissions
      security:
      - bearer: []
      summary: Change the subject, body, or copied addresses of a template
      tags:
      - Email
      x-feature: messages
    delete:
      description: Campaigns already in flight that use this template will fail for any recipient not yet sent to. Requires the Editor or Admin role.
      operationId: deleteEmailTemplate
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: templateId
        required: true
        in: path
        description: Template identifier.
        schema:
          type: string
      responses:
        '204':
          description: Template deleted
        '403':
          description: Insufficient permissions
      security:
      - bearer: []
      summary: Delete an email template
      tags:
      - Email
      x-feature: messages
  /openapi/email/send:
    post:
      description: 'The recipient address is read from the email field on the record, and the template’s `{{placeholders}}` are filled from that same record. Delivery is asynchronous: this responds 202 with a `campaignId` to poll via getEmailCampaign. Sending counts against the workspace’s hourly and daily mailbox limits, so a message may be queued rather than sent immediately. Requires the Editor or Admin role.'
      operationId: sendEmail
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailDto'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCampaignDto'
        '400':
          description: No mailbox connected, or the record has no email address
        '403':
          description: Insufficient permissions
      security:
      - bearer: []
      summary: Send one template to one record, such as a single contact
      tags:
      - Email
      x-feature: messages
  /openapi/email/campaigns:
    post:
      description: 'Each record gets its own copy with `{{placeholders}}` filled from that record, so this is a personalised send, not a group message: recipients cannot see each other. Delivery is asynchronous and paced to stay inside the workspace’s hourly and daily mailbox limits, so a large list is delivered over time rather than all at once. Use `sendWindow` to confine delivery to working hours. Responds 202 with a `campaignId` — poll getEmailCampaign for progress, or stop it with cancelEmailCampaign. Requires the Editor or Admin role.'
      operationId: sendEmailCampaign
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailCampaignDto'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCampaignDto'
        '400':
          description: No mailbox connected, recipients belong to a different object than the template, or the object has no email field
        '403':
          description: Insufficient permissions
      security:
      - bearer: []
      summary: Send one template to a list of records — the way to email many contacts at once
      tags:
      - Email
      x-feature: messages
  /openapi/email/campaigns/{campaignId}:
    get:
      description: Returns `pending` or `running` while messages are still going out, then `completed`, `failed`, or `cancelled`. A campaign held back by a send window or a rate limit stays `running`.
      operationId: getEmailCampaign
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: campaignId
        required: true
        in: path
        description: Identifier returned by sendEmail or sendEmailCampaign.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCampaignDto'
        '404':
          description: Campaign not found
      security:
      - bearer: []
      summary: Check whether a send has finished
      tags:
      - Email
      x-feature: messages
  /openapi/email/campaigns/{campaignId}/cancel:
    post:
      description: Messages already delivered cannot be recalled; this only prevents the remaining ones from going out. Requires the Editor or Admin role.
      operationId: cancelEmailCampaign
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: campaignId
        required: true
        in: path
        description: Identifier returned by sendEmail or sendEmailCampaign.
        schema:
          type: string
      responses:
        '204':
          description: Campaign cancelled
        '404':
          description: Campaign not found
      security:
      - bearer: []
      summary: Stop a send that is still in progress
      tags:
      - Email
      x-feature: messages
components:
  schemas:
    EmailTemplateVariableDto:
      type: object
      properties:
        name:
          type: string
          description: Write this as `{{name}}` in a subject or body to insert the value.
          example: first_name
        displayName:
          type: string
          description: Label shown for this field in the app.
        example:
          type: string
          description: Example of what this placeholder renders as.
          example: Alex
      required:
      - name
      - displayName
      - example
    EmailTemplateListDto:
      type: object
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/EmailTemplateDto'
        count:
          type: number
          description: Number of templates returned.
      required:
      - templates
      - count
    SendEmailDto:
      type: object
      properties:
        templateId:
          type: string
          description: Template to send. Create one first with createEmailTemplate.
        recordId:
          type: string
          description: Record to send to, e.g. a contact. Its email field supplies the recipient address and its values fill the template placeholders.
        integrationId:
          type: string
          description: Mailbox to send from. Defaults to the caller’s first connected mailbox.
      required:
      - templateId
      - recordId
    SendEmailCampaignDto:
      type: object
      properties:
        templateId:
          type: string
          description: Template sent to every recipient.
        recordIds:
          description: Records to send to, e.g. contacts. Each one receives its own copy with placeholders filled from that record.
          maxItems: 1000
          type: array
          items:
            type: string
        integrationId:
          type: string
          description: Mailbox to send from. Defaults to the caller’s first connected mailbox.
        displayName:
          type: string
          description: Name for this campaign in the app’s activity views. Defaults to the template title.
        sendWindow:
          description: Restrict delivery to certain hours and days. Messages outside the window wait until it reopens.
          allOf:
          - $ref: '#/components/schemas/EmailSendWindowDto'
        unsubscribeLink:
          type: boolean
          description: End each email with an unsubscribe link (good for newsletters). A recipient who clicks it is marked as opted out (`email_opt_out`) and gets no further campaign emails. Off by default.
      required:
      - templateId
      - recordIds
    EmailTemplateDto:
      type: object
      properties:
        templateId:
          type: string
          description: Template identifier.
        title:
          type: string
          description: Internal name used to find the template.
        subject:
          type: string
          description: Subject line. May contain `{{field_api_name}}` placeholders that are filled per recipient.
        body:
          type: string
          description: HTML body. May contain `{{field_api_name}}` placeholders that are filled per recipient.
        tableId:
          type: string
          description: Object whose records this template is written for, e.g. the contacts object. Placeholders resolve against this object’s fields.
        cc:
          description: Addresses copied on every send.
          type: array
          items:
            type: string
        bcc:
          description: Addresses blind-copied on every send.
          type: array
          items:
            type: string
      required:
      - templateId
      - title
      - subject
      - body
    EmailCampaignDto:
      type: object
      properties:
        campaignId:
          type: string
          description: Campaign identifier. Pass to getEmailCampaign to check progress or cancelEmailCampaign to stop it.
        status:
          type: string
          description: 'Progress of the campaign as a whole: `pending` or `running` while it is being handed over, `waiting_timer` while it waits, then `completed`, `failed` or `cancelled`. Sending is asynchronous, so a fresh campaign starts as `pending`. Keep polling until it is `completed`, `failed` or `cancelled`.'
        recipientCount:
          type: number
          description: How many records the campaign was started for.
        pollUrl:
          type: string
          description: Relative URL to poll for progress.
          example: /openapi/email/campaigns/run_123
      required:
      - campaignId
      - status
      - recipientCount
      - pollUrl
    UpdateEmailTemplateDto:
      type: object
      properties:
        title:
          type: string
          description: New internal name for the template.
        subject:
          type: string
          description: Replacement subject line.
        body:
          type: string
          description: Replacement HTML body.
        cc:
          description: Replacement list of copied addresses.
          type: array
          items:
            type: string
        bcc:
          description: Replacement list of blind-copied addresses.
          type: array
          items:
            type: string
    EmailTemplateVariableListDto:
      type: object
      properties:
        variables:
          description: Placeholders that can be used in a template aimed at this object.
          type: array
          items:
            $ref: '#/components/schemas/EmailTemplateVariableDto'
      required:
      - variables
    CreateEmailTemplateDto:
      type: object
      properties:
        title:
          type: string
          description: Internal name used to find the template later.
          example: Q3 follow-up
        subject:
          type: string
          description: Subject line. Use `{{field_api_name}}` to insert a value from each recipient’s record — call listEmailTemplateVariables to see which names are valid.
          example: Following up, {{first_name}}
        body:
          type: string
          description: HTML body. Supports the same `{{field_api_name}}` placeholders as the subject. An unknown placeholder renders as empty text.
          example: <p>Hi {{first_name}}, do you have 15 minutes this week?</p>
        tableId:
          type: string
          description: Object whose records this template will be sent to, e.g. the contacts object. Determines which `{{placeholders}}` are valid.
        cc:
          description: Addresses to copy on every send.
          type: array
          items:
            type: string
        bcc:
          description: Addresses to blind-copy on every send.
          type: array
          items:
            type: string
      required:
      - title
      - subject
      - body
      - tableId
    EmailMailboxDto:
      type: object
      properties:
        integrationId:
          type: string
          description: Identifier of the connected mailbox. Pass this as `integrationId` when sending.
        email:
          type: string
          description: Address that email will be sent from.
        provider:
          type: string
          enum:
          - Google
          - Microsoft
          description: Mailbox provider backing this account.
        accountLabel:
          type: string
          description: Human-friendly name for the mailbox.
        ownerName:
          type: string
          description: Full name of the teammate who connected the mailbox.
        shared:
          type: boolean
          description: True when the mailbox is shared with the workspace rather than owned privately by one person.
      required:
      - integrationId
      - email
      - provider
      - accountLabel
      - shared
    EmailSendWindowDto:
      type: object
      properties:
        timezone:
          type: string
          description: IANA timezone the window is expressed in.
          example: Europe/Oslo
        startTime:
          type: string
          description: Earliest local send time, 24-hour `HH:MM`.
          example: 09:00
        endTime:
          type: string
          description: Latest local send time, 24-hour `HH:MM`.
          example: '17:00'
        weekdays:
          description: Days the window applies to, 0 = Sunday through 6 = Saturday. Defaults to every day.
          example:
          - 1
          - 2
          - 3
          - 4
          - 5
          type: array
          items:
            type: number
      required:
      - timezone
      - startTime
      - endTime
    EmailMailboxListDto:
      type: object
      properties:
        mailboxes:
          description: Connected mailboxes.
          type: array
          items:
            $ref: '#/components/schemas/EmailMailboxDto'
        defaultIntegrationId:
          type: string
          description: Mailbox used when a send request omits `integrationId`. Absent when no mailbox is connected.
      required:
      - mailboxes
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key