# API - Integration with other services

Email This Issue provides two types of API components that makes it possible to integrate it with other addons or external services.

## REST API <a href="#api-integrationwithotherservices-restapi" id="api-integrationwithotherservices-restapi"></a>

### Send emails <a href="#api-integrationwithotherservices-sendemails" id="api-integrationwithotherservices-sendemails"></a>

The REST API is a RESTFul service method that will send emails.&#x20;

|                 |                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Parameter       | Value                                                                                                                                                              |
| REST path       | `$JIRA_BASE_URL/rest/jeti/1.0/email`                                                                                                                               |
| Request Method  | POST                                                                                                                                                               |
| Request Headers | Content-Type:application/json                                                                                                                                      |
| Authentication  | <p>What Jira REST API offers</p><p>See details in the <a href="https://docs.atlassian.com/software/jira/docs/api/REST/latest/">documentation</a>.</p>              |
| Request Body    | Email parameters in JSON                                                                                                                                           |
| Response        | <ul><li><code>200</code>: if email is composed and sent successfully</li><li><code>500</code>: if an error occured while composing and sending the email</li></ul> |

#### Request Body Json <a href="#api-integrationwithotherservices-requestbodyjson" id="api-integrationwithotherservices-requestbodyjson"></a>

Request Body must be a well formatted Json object with the following structure.

**Request Body Json**

```
{
"issue":"BD-1",
"fromName":"fromapi",
"fromAddress":"fromapi@fromapi.com", 
"to":["joe@foocompany.com","admin","g:jira-administrators","r:10000"],
"cc":["mary@anothercompany.com", "o:lead", "o:watchers"],
"bcc":[],
"emailSubject":"This is the email's subject as if the user entered it",
"emailBody":"This is the email body",
"addAttachments":"ALL",
"emailTemplate":"Acknowledge Issue",
"emailOptions":
  {
  "addToWatchers":"true",
  "replyToMe":"true",
  "mailAsMe":"false",
  "addComments":"true",
  "suppressCommentEvent":"true", 
  "emailFormat":"text",
  "commentVisibility":"g:jira-administrators",
  "richHtml":"false"
  },
"payload":{"pay1":"val1"}
} 
```

Fields in the Json object are the following:

{% hint style="warning" %}
**Important**: Only the issue field is mandatory.
{% endhint %}

<table><thead><tr><th width="150">Field</th><th width="193.52264585658708">Definition</th><th>Example</th></tr></thead><tbody><tr><td><code>issue</code></td><td>Numeric ID of the issue, or Issue Key</td><td>10000 or TEST-1</td></tr><tr><td><code>fromName</code></td><td>Senders name can be specified </td><td>John Doe</td></tr><tr><td><code>fromAddress</code></td><td>Senders email address can be specified. Ensure that the provided address is one from which email sending is authorized.</td><td></td></tr><tr><td><code>to,cc,bcc</code></td><td><p>Array of recipients:</p><ul><li>email addresses</li><li>Jira user names</li><li>Jira participants with prefix <strong>"o:"</strong></li><li>group names with prefix <strong>"g:"</strong></li><li>project role IDs with prefix <strong>"r:"</strong></li><li>custom field IDs with prefix <strong>"cf:"</strong></li></ul><p><br></p></td><td><p>Participant examples:</p><ul><li>o:me - current user</li><li>o:reporter - issue reporter</li><li>o:assignee - issue assignee</li><li>o:watchers - issue watchers</li><li>o:lead - project lead</li></ul><p>Group examples:</p><ul><li>g:jira-administrators</li></ul><p>Role examples:</p><ul><li>r:10000, where 10000 is the numeric ID of the role</li></ul><p>Custom Field examples:</p><ul><li>cf:customfield_10010</li></ul></td></tr><tr><td><code>emailSubject</code></td><td>Email Subject</td><td><br></td></tr><tr><td><code>emailBody</code></td><td>Email Body</td><td><br></td></tr><tr><td><code>addAttachments</code></td><td><p>Specifies how to select issue attachments to be added to the email</p><p><br></p><p><br></p></td><td><p> Value is one of:</p><ul><li>ALL: all issue attachments</li><li>NONE: none of the attachments</li><li>LATEST: newest version of all attachment</li><li>ADDED_LAST: most recently added attachments</li></ul></td></tr><tr><td><code>emailTemplate</code></td><td><p>Email template ID or name, email will be generated using this template.</p><p>If not given, the template selected in the issue's Context will be used.</p></td><td><br></td></tr><tr><td><code>emailOptions</code></td><td><p>Email options to control various aspects of the email.</p><ul><li>addToWatchers: if true, JETI will add email user recipients as watchers of the issue</li><li>replyToMe: if true, JETI will set the current user's email address as the Reply-To header in the email</li><li>mailAsMe: if true, JETI will set the current user's email address as the From Address in the email</li><li>addComments: if true, JETI will add the comments to the ougoing email (if the used template renders comments).</li><li>suppressComment: if true, JETI will not fire an Issue Commented event</li><li>commentVisibility: if provided, JETI will secure the comment it adds to the issue.<br>g:&#x3C;group name> - group restriction<br>r:&#x3C;role ID> - role restriction<br>internal - internal comment<br>all - visible to all (with browse permission)<br>none - no comment added</li><li>richHtml: if true, JETI will interpret emailBody as a HTML content</li></ul><p><br></p></td><td><pre><code>"emailOptions":
  {
  "addToWatchers":"true",
  "replyToMe":"true",
  "mailAsMe":"false",
  "addComments":"true",
  "suppressCommentEvent":"true", 
  "emailFormat":"text",
  "commentVisibility":"g:jira-administrators",
  "richHtml":"false"
  }
</code></pre></td></tr><tr><td><code>payload</code></td><td><p>Key-Value map of values that will be added to the Velocity Context used to generate email body.</p><p>Email template may refer to these values and may render them in the email.</p></td><td><br></td></tr></tbody></table>

### Request Statistics <a href="#api-integrationwithotherservices-requeststatistics" id="api-integrationwithotherservices-requeststatistics"></a>

The REST API is a RESTFul service method that will return the number of email items from the audit log.&#x20;

<table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Value</td></tr><tr><td>REST path</td><td><code>$JIRA_BASE_URL/rest/jeti/1.0/email/stat</code></td></tr><tr><td>Request Method</td><td>GET</td></tr><tr><td>Request Headers</td><td><code>Content-Type:application/json</code></td></tr><tr><td>Authentication</td><td><p>What Jira REST API offers</p><p>See details in the </p></td></tr><tr><td>Query Parameters</td><td><pre><code>issueKey - Key of the issue whose email audit log is queried
issueId - Id of the issue whose email audit log is queried
mailHandlerId - ID of the Email This Issue Mail Handler to limit the query to incoming emails processed by this handler
type - Type of the email items to query (either of OUTGOING, INCOMING_ISSUE, INCOMING_COMMENT)
</code></pre></td></tr><tr><td>Response Codes</td><td><ul><li>200: if email is composed and sent successfully</li><li>500: if an error occurred while composing and sending the email</li><li>401: if the calling user account is not authorized to request the details</li></ul></td></tr><tr><td>Response Data</td><td>Number of mail items matching the query</td></tr><tr><td>Example</td><td><code>http://JIRA_URL/rest/jeti/1.0/email/stat?issueKey=&#x3C;issue key></code></td></tr></tbody></table>

### Request Email Items from the Audit Log <a href="#api-integrationwithotherservices-requestemailitemsfromtheauditlog" id="api-integrationwithotherservices-requestemailitemsfromtheauditlog"></a>

The REST API is a RESTFul service method that will return email items from the audit log matching the query parameters.&#x20;

<table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Value</td></tr><tr><td>REST path</td><td><code>$JIRA_BASE_URL/rest/jeti/1.0/email/query</code></td></tr><tr><td>Request Method</td><td>GET</td></tr><tr><td>Request Headers</td><td><code>Content-Type:application/json</code></td></tr><tr><td>Authentication</td><td><p>What Jira REST API offers</p><p>See details in the <a href="https://docs.atlassian.com/software/jira/docs/api/REST/latest/">documentation</a>.</p></td></tr><tr><td>Authorization</td><td>Only those users may query the email items who are authorized to view them in the issue.</td></tr><tr><td>Query Parameters</td><td><pre><code>issueKey - Key of the issue whose email audit log is queried
issueId - Id of the issue whose email audit log is queried
limit- Limit the number of email items to return (max 1000)
type - Type of the email items to query (either of OUTGOING, INCOMING_ISSUE, INCOMING_COMMENT)
from - Date emails were sent or processed after (required format is dd/MM/yyyy)
to - Date emails were sent or processed before (required format is dd/MM/yyyy)
source - Trigger of the outgoing email (either of OPERATION, BULK, EVENT, WORKFLOW, AUTOREPLY, TEST, API, PREVIEW)
</code></pre></td></tr><tr><td>Response Codes</td><td><ul><li><code>200</code>: if email is composed and sent successfully</li><li><code>500</code>: if an error occurred while composing and sending the email</li><li><code>401</code>: if the calling user account is not authorized to request the details </li></ul></td></tr><tr><td>Response Data</td><td>JSON Array of email items matching the query</td></tr><tr><td>Example</td><td><code>http://JIRA_URL/rest/jeti/1.0/email/query?issueKey=&#x3C;issue key></code></td></tr></tbody></table>

#### Response structure <a href="#api-integrationwithotherservices-responsestructure" id="api-integrationwithotherservices-responsestructure"></a>

```
[
{
"issueId": 22900,
"subject": "(IT-349) Új request by customer \"Hello WORLD\"",
"body": <email body>,
"to": <to recipients>,
"cc":<cc recipients>,
"from": <sender email address>,
"format": <email format>,
"actorUserKey": <user key>,
"type": <type of email item>,
"source": <trigger of the email>,
"date": <date and time the email was sent or processed>
},]
```

### Queue Statistics  <a href="#api-integrationwithotherservices-queuestatisticssince9.0.0green" id="api-integrationwithotherservices-queuestatisticssince9.0.0green"></a>

<mark style="color:green;">SINCE 9.0.0</mark>

#### Incoming Queue Statistics <a href="#api-integrationwithotherservices-incomingqueuestatistics" id="api-integrationwithotherservices-incomingqueuestatistics"></a>

<table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody><tr><td>REST path</td><td><code>$JIRA_BASE_URL/rest/jeti/1.0/incomingMailQueue/statistic</code></td></tr><tr><td>Request Method</td><td>GET</td></tr><tr><td>Request Headers</td><td><code>Content-Type:application/json</code></td></tr><tr><td>Authentication</td><td><p>What Jira REST API offers</p><p>See details in the <a href="https://docs.atlassian.com/software/jira/docs/api/REST/latest/">documentation</a>.</p></td></tr><tr><td>Response Codes</td><td><ul><li><code>200</code>: if email is composed and sent successfully</li><li><code>500</code>: if an error occurred while composing and sending the email</li><li><code>401</code>: if the calling user account is not authorized to request the details</li></ul></td></tr><tr><td>Response Data</td><td><p>Returns statistics of the incoming mail queue.</p><pre><code>{
"new":&#x3C;number of items with status NEW>,
"failed":&#x3C;number of items with status FAILED>,
"skipped":&#x3C;number of items with status SKIPPED>,
"processing":&#x3C;number of items with status PROCESSING>
}
</code></pre></td></tr></tbody></table>

#### Outgoing Queue Statistics <a href="#api-integrationwithotherservices-outgoingqueuestatistics" id="api-integrationwithotherservices-outgoingqueuestatistics"></a>

<table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody><tr><td>REST path</td><td><code>$JIRA_BASE_URL/rest/jeti/1.0/outgoingMailQueue/statistic</code></td></tr><tr><td>Request Method</td><td>GET</td></tr><tr><td>Request Headers</td><td><code>Content-Type:application/json</code></td></tr><tr><td>Authentication</td><td><p>What Jira REST API offers</p><p>See details in the <a href="https://docs.atlassian.com/software/jira/docs/api/REST/latest/">documentation</a>.</p></td></tr><tr><td>Response Codes</td><td><ul><li><code>200</code>: if email is composed and sent successfully</li><li><code>500</code>: if an error occurred while composing and sending the email</li><li><code>401</code>: if the calling user account is not authorized to request the details</li></ul></td></tr><tr><td>Response Data</td><td><p>Returns statistics of the outgoing mail queue</p><pre><code>{
"active":&#x3C;number of items with status ACTIVE>,
"error":&#x3C;number of items with status ERROR>
}
</code></pre></td></tr></tbody></table>

#### Mail Generation Queue <a href="#api-integrationwithotherservices-mailgenerationqueue" id="api-integrationwithotherservices-mailgenerationqueue"></a>

<table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody><tr><td>REST path</td><td><code>$JIRA_BASE_URL/rest/jeti/1.0/mailGenerationQueue/statistic</code></td></tr><tr><td>Request Method</td><td>GET</td></tr><tr><td>Request Headers</td><td><code>Content-Type:application/json</code></td></tr><tr><td>Authentication</td><td><p>What Jira REST API offers</p><p>See details in the <a href="https://docs.atlassian.com/software/jira/docs/api/REST/latest/">documentation</a>.</p></td></tr><tr><td>Response Codes</td><td><ul><li><code>200</code>: if email is composed and sent successfully</li><li><code>500</code>: if an error occurred while composing and sending the email</li><li><code>401</code>: if the calling user account is not authorized to request the details</li></ul></td></tr><tr><td>Response Data</td><td><p>Returns statistics of the mail generation queue.</p><pre><code>{
"totalQueued":&#x3C;total number of events that was ever queued>,
"totalCompleted":&#x3C;total number of events completed>,
"currentlyOnQueue":&#x3C;total number of events currently on queue>,
"activeWorkerThreads":&#x3C;total number of active worker threads>,
"maxWorkerThreads":&#x3C;max number of worker threads>,
"avgTimeInQueue":&#x3C;average amount of time (ms) events spend on the queue>,
"maxQueueSize":&#x3C;maximum number of events on the queue>
}
</code></pre></td></tr></tbody></table>

## OSGi Component API <a href="#api-integrationwithotherservices-osgicomponentapi" id="api-integrationwithotherservices-osgicomponentapi"></a>

In case, your Jira add-on wants to use Jira Email This Issue's email capabilities, you can build an integration between your add-on and Email This Issue. In order to do that you have to import the OSGi component Email This Issue publishes and call its methods.

<table><thead><tr><th width="150">API</th><th>Explanation</th></tr></thead><tbody><tr><td>Component interface</td><td><pre><code>com.metainf.jira.plugin.emailissue.api.EmailService
</code></pre></td></tr><tr><td>Component method</td><td><p><br></p><pre><code>void sendEmail(com.metainf.jira.plugin.emailissue.api.EmailDefinitionApi emailDefinition) throws Exception
</code></pre><p><br></p></td></tr><tr><td>Component method</td><td><p><br></p><pre><code>Collection&#x3C;EmailLog> queryEmailLog(com.metainf.jira.plugin.emailissue.api.EmailLogQuery emailLogQuery) throws Exception
</code></pre><p><br></p></td></tr></tbody></table>

#### Email Parameters <a href="#api-integrationwithotherservices-emailparameters" id="api-integrationwithotherservices-emailparameters"></a>

```
public class EmailDefinitionApi {
    private String issue;

    private List<String> to; //user keys and email addresses
    private List<String> cc; //user keys and email addresses
    private List<String> bcc; //user keys and email addresses
    private com.metainf.jira.plugin.emailissue.action.EmailOptions emailOptions;
    private String emailBody; //email body (will be injected in the template)
    private String emailSubject; //email subject (will be injected in the subject part of the template)

    private List<String> attachments; //issue attachment IDs
    private String addAttachments;
    private String emailTemplate; //name or ID of the Email template to use
    private Map<String, Object> payload; //arbitrary values that are injected into the Velocity Context in the template
}

public class EmailOptions {
	private boolean addToWatchers; //add recipient users to watchers, default: false
  	private boolean replyToMe; //set the current user as the reply-to address, default: false
  	private boolean mailAsMe; //set the sender address to the current user's email address, default: false
  	private String emailFormat; //email format "text" or "html"
  	private String emailPriority; //HIGH, NORMAL, LOW
}

public class EmailLogQuery {
	private Long issueId;
	private String issueKey;
	private String type; //EmailType
	private String source;
	private int top;
	private Date from;
	private Date to;
}
```

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/integrations/api-integration-with-other-services.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.