COM Service API

Overview

The COM (Communications) service manages email and notification delivery for the HERCULES SGI system:

Email Management - Create, send, and track emails
Template Support - Email templates with parameter substitution
Attachments - Support for file attachments
Recipients - Multiple recipient types (To, CC, BCC)
Status Tracking - Monitor email delivery status

Base URL: /emails

Authentication

The COM service is primarily used by other SGI services for sending notifications. Direct access may be restricted to system administrators and authorized applications.

Emails

List Emails

curl -X GET "http://localhost:4280/emails?q=subject=like='Research%'" \
  -H "Authorization: Bearer {token}"

Returns a paginated list of emails.

string

RSQL filter query (e.g., subject=like='Grant%';sent==true)

string

Sort specification (e.g., createdDate,desc)

page

integer

default:"0"

Page number (zero-based)

size

integer

default:"10"

Items per page

content

array

Array of Email objects

Show Email object

long

Email identifier

subject

string

Email subject

content

string

Email body (HTML or plain text)

contentType

string

Content type (HTML, TEXT)

sent

boolean

Whether email has been sent

createdDate

datetime

Creation timestamp

sentDate

datetime

Sent timestamp

recipients

array

List of recipients

attachments

array

List of attachments

params

array

Template parameters

Get Email by ID

curl -X GET "http://localhost:4280/emails/123" \
  -H "Authorization: Bearer {token}"

long

required

Email identifier

Returns complete email details including recipients, attachments, and parameters.

Create Email

curl -X POST "http://localhost:4280/emails" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Grant Application Approved",
    "content": "<p>Your application has been approved.</p>",
    "contentType": "HTML",
    "recipients": [
      {
        "address": "[email protected]",
        "name": "Dr. Jane Smith",
        "type": "TO"
      }
    ],
    "attachments": [],
    "params": [
      {
        "name": "APPLICATION_ID",
        "value": "APP-2024-001"
      }
    ]
  }'

Request Body:

subject

string

required

Email subject line

content

string

required

Email body content (HTML or plain text)

contentType

string

default:"HTML"

Content type: HTML or TEXT

recipients

array

required

Array of recipient objects

Show Recipient object

address

string

required

Email address

name

string

Recipient name

type

string

required

Recipient type: TO, CC, or BCC

attachments

array

Array of attachment objects

Show Attachment object

name

string

required

File name

content

string

required

Base64-encoded file content

contentType

string

MIME type (e.g., application/pdf)

params

array

Template parameters for variable substitution

Show Parameter object

name

string

required

Parameter name

value

string

required

Parameter value

Response: Returns the created Email object with HTTP 201 status.

Update Email

curl -X PUT "http://localhost:4280/emails/123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated Subject",
    "content": "Updated content",
    "recipients": [...]
  }'

Updates an existing email. Note: Only unsent emails can be updated.

long

required

Email identifier

Delete Email

curl -X DELETE "http://localhost:4280/emails/123" \
  -H "Authorization: Bearer {token}"

Deletes an email record.

long

required

Email identifier

Response: HTTP 204 No Content

Send Email

curl -X GET "http://localhost:4280/emails/123/send" \
  -H "Authorization: Bearer {token}"

Sends a previously created email.

long

required

Email identifier

Response:

status

string

Sending status: SUCCESS, FAILED, or PENDING

message

string

Status message or error description

timestamp

datetime

Timestamp of the send operation

{
  "status": "SUCCESS",
  "message": "Email sent successfully",
  "timestamp": "2024-03-05T10:30:00Z"
}

Email Templates

The COM service supports template-based emails with parameter substitution.

Using Templates

Templates are managed separately through the EmailTplController. To use a template:

Create an email referencing a template
Provide parameters that match template variables
The service will substitute parameters in the template content

{
  "templateRef": "GRANT_APPROVAL",
  "recipients": [
    {
      "address": "[email protected]",
      "type": "TO"
    }
  ],
  "params": [
    {
      "name": "RESEARCHER_NAME",
      "value": "Dr. Jane Smith"
    },
    {
      "name": "GRANT_TITLE",
      "value": "Novel Cancer Research"
    },
    {
      "name": "AMOUNT",
      "value": "€50,000"
    }
  ]
}

Common Use Cases

Sending Notification Email

const email = {
  subject: 'Application Status Update',
  content: '<p>Your application status has changed to: <strong>Approved</strong></p>',
  contentType: 'HTML',
  recipients: [
    {
      address: '[email protected]',
      name: 'John Doe',
      type: 'TO'
    }
  ],
  params: [
    { name: 'APPLICATION_ID', value: 'APP-2024-001' },
    { name: 'NEW_STATUS', value: 'Approved' }
  ]
};

// Create email
const response = await fetch('http://localhost:4280/emails', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(email)
});

const created = await response.json();

// Send email
const sendResponse = await fetch(`http://localhost:4280/emails/${created.id}/send`, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const status = await sendResponse.json();
console.log('Send status:', status);

Sending Email with Attachment

import base64
import requests

# Read PDF file and encode
with open('document.pdf', 'rb') as f:
    pdf_content = base64.b64encode(f.read()).decode('utf-8')

email = {
    'subject': 'Grant Agreement Document',
    'content': 'Please find attached your grant agreement.',
    'contentType': 'TEXT',
    'recipients': [
        {
            'address': '[email protected]',
            'type': 'TO'
        }
    ],
    'attachments': [
        {
            'name': 'grant-agreement.pdf',
            'content': pdf_content,
            'contentType': 'application/pdf'
        }
    ]
}

# Create and send
response = requests.post(
    'http://localhost:4280/emails',
    json=email,
    headers={'Authorization': f'Bearer {token}'}
)

email_id = response.json()['id']

# Send it
send_response = requests.get(
    f'http://localhost:4280/emails/{email_id}/send',
    headers={'Authorization': f'Bearer {token}'}
)

print(send_response.json())

Error Handling

Common Error Responses

400 Bad Request

Invalid email data (missing required fields, invalid email addresses)

404 Not Found

Email with specified ID does not exist

409 Conflict

Cannot modify email that has already been sent

500 Internal Server Error

Email sending failed due to SMTP server error

Validation Rules

Email addresses must be valid format
At least one TO recipient is required
Subject cannot be empty
Content cannot be empty
Attachment content must be valid Base64
Template parameters must match template requirements

Best Practices

Test emails first - Use test email addresses during development
Validate recipients - Ensure email addresses are valid before creating emails
Use templates - Leverage templates for consistent formatting and easier maintenance
Monitor status - Check send status after sending to handle failures
Handle attachments carefully - Large attachments may cause timeouts or failures
Limit recipients - Avoid sending to too many recipients in a single email

Configuration

The COM service requires SMTP server configuration (typically done by system administrators):

SMTP host and port
Authentication credentials
SSL/TLS settings
Default sender address
Email templates location

Services

Authentication

Overview

Authentication

Emails

List Emails

Get Email by ID

Create Email

Update Email

Delete Email

Send Email

Email Templates

Using Templates

Common Use Cases

Sending Notification Email

Sending Email with Attachment

Error Handling

Common Error Responses

Validation Rules

Best Practices

Configuration

Build docs developers (and LLMs) love

Services

Authentication

​Overview

​Authentication

​Emails

​List Emails

​Get Email by ID

​Create Email

​Update Email

​Delete Email

​Send Email

​Email Templates

​Using Templates

​Common Use Cases

​Sending Notification Email

​Sending Email with Attachment

​Error Handling

​Common Error Responses

​Validation Rules

​Best Practices

​Configuration

Build docs developers (and LLMs) love

Overview

Authentication

Emails

List Emails

Get Email by ID

Create Email

Update Email

Delete Email

Send Email

Email Templates

Using Templates

Common Use Cases

Sending Notification Email

Sending Email with Attachment

Error Handling

Common Error Responses

Validation Rules

Best Practices

Configuration