Connect Email API

The Connect Email API is an optional module that exposes a REST endpoint for sending emails through the sendEmail processor.

The module deploys a flow named connect-email-api with a single endpoint.

The endpoint accepts a JSON payload to send an email through the sendEmail processor. The request payload supports standard email fields such as sender (from), recipients (to, cc, bcc), replyTo, subject, and body (plainTextBody or htmlBody), where to and subject are required fields.

  • Endpoint: POST /email/send

  • Authentication: include the credential type for your service account (for example, apiKey)

  • Request body: use the JSON payload expected by the sendEmail processor

The Email API uses the sendEmail processor and expects the exact JSON payload required by that processor.

For example, this request calls the Email API with the default credential type apiKey:

curl https://api.env-connect-mvp-ingress.local/gridos/rs/connect-email-api/email/send \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --header 'apiKey: <your API key>' \
  --data '{
  "to": [
    "to@example.com"
  ],
  "subject": "Test",
  "plainTextBody": "Hello world!"
}'

To fetch the API key to test the request, use the following command:

+

kubectl -n <CONNECT_NAMESPACE> get secret connect-email-api-sa -o jsonpath='{.data.apiKey}' | base64 -d

Change Email API Credential Type

You cannot change the credential type of an existing Connect service account in place. If the Connect Email API is already installed and you want to switch to a different credential type such as Basic Authentication, you must remove the existing Email API deployment resources and then redeploy them with the new credential type.

To change the credential type after the Connect Email API has already been installed:

  1. Delete the existing ConnectServiceAccount custom resource named connect-email-api.

    # command for deleting existing CR of type ConnectServiceAccount with the name 'connect-email-api'
kubectl delete csa connect-email-api

  2. Create or update a values override to change the credential type.

    1. For Basic authentication, use the override below:

      # Set credentialsType to BasicAuthentication
emailApi:
  connectServiceAccount:
    credentialsType: BasicAuthentication

    2. For OIDC, use the override below:

        # change credentialType to oidc and provide claims validation script
  connectServiceAccount:
    credentialsType: OIDC
    jwtClaimsMatchJsoniqScript: |
      #input.sub = "subject"

    3. For mTLS, use:

      # change credentialType to mTLS
emailApi:
  connectServiceAccount:
    credentialsType: mTLS

  3. Reapply your Helm or Helmfile deployment so the Deployment Operator recreates the Email API resources with the new credential type.

sendEmail SMTP Configuration

The sendEmail processor requires flow server SMTP configuration. Set these properties in your flow server runtime configuration.

This SMTP configuration is required not only for the Connect Email API, but also for any customer flow that uses the sendEmail processor.

flowserver:
  config:
    application.yml:
      mc:
        flow-server:
          processor:
            email:
              smtp:
                host: "smtp.example.com"
                port: 587
                tls: true
                auth: "PLAIN"
              client:
                host: "connect-flowserver.example.com"
                username: "smtp-user"
                password: "smtp-password"
                truststoreCertPem: |-
                  -----BEGIN CERTIFICATE-----
                  ...
                  -----END CERTIFICATE-----
                defaultConnectionTimeoutMillis: 5000
                defaultReceiveTimeoutMillis: 10000
              message:
                defaultFrom: "noreply@example.com"

The following table lists the required Email API properties and their configuration details.

Property Description Legal values Default value

mc.flow-server.processor.email.smtp.host

SMTP server host that receives outbound mail.

Valid DNS name or IP address.

localhost

mc.flow-server.processor.email.smtp.port

SMTP server port used for the transport connection.

Integer in the valid TCP port range (1-65535).

25

mc.flow-server.processor.email.smtp.tls

Enables TLS for SMTP transport.

true or false.

true

mc.flow-server.processor.email.smtp.auth

SMTP authentication mechanism used when logging in to the SMTP server.

Mechanism name supported by your SMTP server/runtime (commonly PLAIN or LOGIN).

PLAIN

mc.flow-server.processor.email.client.host

Client host identity sent by the SMTP client.

Valid DNS name or IP address resolvable by the SMTP server.

localhost

mc.flow-server.processor.email.client.username

Username for SMTP authentication.

Non-empty string recognized by the SMTP server.

changeMe

mc.flow-server.processor.email.client.password

Password/secret paired with client.username.

Non-empty string/secret recognized by the SMTP server.

changeMe

mc.flow-server.processor.email.client.truststoreCertPem

PEM-encoded certificate chain used to trust the SMTP server certificate (for private CA/self-signed setups).

Valid PEM-encoded X.509 certificate content. Do not require for public CA trust.

Not set

mc.flow-server.processor.email.client.defaultConnectionTimeoutMillis

Default timeout for establishing the SMTP connection.

Non-negative integer (milliseconds).

5000

mc.flow-server.processor.email.client.defaultReceiveTimeoutMillis

Default timeout for receiving SMTP server responses.

Non-negative integer (milliseconds).

10000

mc.flow-server.processor.email.message.defaultFrom

Fallback sender address when the request does not provide from.

Valid email address.

utilihive-operations@greenbird.com

Replace all default values with environment-specific SMTP details before you deploy Connect Email API or run customer flows that use sendEmail in production.