# 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>