DocumentationExperience Cloud KCS

AEM as a Cloud Service: SendGrid API Email Delivery Issue When Using Custom OSGi Service

Last update: June 27, 2026

This article provides steps to resolve issues with sending email via the SendGrid API from a custom OSGi service in Adobe Experience Manager as a Cloud Service.

Description description

Environment

Adobe Experience Manager (AEM) as a Cloud Service (all versions)
Issue/Symptoms

Attempts to send email using a custom OSGi service that integrates with the SendGrid REST API (https://api.sendgrid.com/v3/mail/send) fail to deliver messages. The issue occurs after deploying code through Cloud Manager and executing a workflow process that invokes the SendGrid email service.

  • Custom OSGi configuration interface created using @ObjectClassDefinition.
  • Configuration file added at /apps/csuf-cloud/osgiconfig/config (For example: com.csuf.cloud.core.config.SendGridConfiguration.cfg.json).
  • API key configured using a Cloud Manager secret (SENDGRID_API_KEY).
  • from_email set to a valid sender address.
  • Custom workflow process triggers the SendGrid email service.
  • No explicit error message provided, but emails aren’t delivered as expected.

Resolution resolution

  1. Verify SendGrid API Key Usage

    • Ensure that the value for the API key in your OSGi configuration is set to the Cloud Manager secret containing the SendGrid API key.

    • When authenticating with the SendGrid API, always use the literal string apikey as the username, regardless of the actual API key value created in SendGrid.

    • Example configuration:

      code language-none 
      "smtp.user": "apikey",
"api_key": "<Cloud Manager secret reference>"

  2. Check OSGi Configuration Deployment

    • Confirm that the OSGi configuration file is correctly deployed to /apps/<project>/osgiconfig/config and is picked up by AEM.
    • Validate that the configuration values (API key, sender email) are correct and not empty.

  3. Validate Cloud Manager Secret Reference

    • Ensure that the Cloud Manager secret (SENDGRID_API_KEY) is properly referenced in your configuration and available at runtime.

  4. Test Email Delivery

    • Trigger the workflow process from the AEM Author environment and monitor for successful email delivery.
    • Check AEM and SendGrid logs for any errors or rejected requests.

Cause

The SendGrid API requires the username to be set as apikey for authentication, regardless of the actual API key value. Incorrect configuration of the username or API key can prevent successful email delivery.

recommendation-more-help
experience-cloud-kcs-help-kbarticles