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

Table of Contents

REST API

Send emails

The REST API is a RESTFul service method that will send emails.

Parameter	Value
REST path	$JIRA_BASE_URL/rest/jeti/1.0/email
Request Method	POST
Request Headers	Content-Type:application/json
Authentication	What Jira REST API offers See details in the documentation
Request Body	Email parameters in JSON
Response	200: if email is composed and sent successfully 500: if an error occured while composing and sending the email

Request Body Json

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

Request Body Json

Code Block

collapse

language	js
title	Request Body Json
	true

{
"issue":"BD-1", 
"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 is explained below.

Field

Mandatory

Explanation

Example

issue

Numberic ID of the issue, or Issue Key

10000 or TEST-1

to,cc,bcc

Array of recipients:

email addresses
Jira user names
Jira participants with prefix "o:"
group names with prefix "g:"
project role IDs with prefix "r:"
custom field IDs with prefix "cf:"

Participant examples:

o:me - current user
o:reporter - issue reporter
o:assignee - issue assignee
o:watchers - issue watchers
o:lead - project lead

Group examples:

g:jira-administrators

Role exmaples:

r:10000, where 10000 is the numeric ID of the role

Custom Field examples:

cf:customfield_10010

emailSubject

Email Subject

emailBody

Email Body

addAttachments

Specifies how to select issue attachments to be added to the email

Value is one of:

ALL: all issue attachments
NONE: none of the attachments
LATEST: newest version of all attachment
- - ADDED_LAST: most recently added attachments

emailTemplate

Email template ID or name, email will be generated using this template.

If not given, the template selected in the issue's Context will be used.

emailOptions

Email options to control various aspects of the email.

addToWatchers: if true, JETI will add email user recipients as watchers of the issue
replyToMe: if true, JETI will set the current user's email address as the Reply-To header in the email
mailAsMe: if true, JETI will set the current user's email address as the From Address in the email
addComments: if true, JETI will add a comment to the issue.
suppressComment: if true, JETI will not fire an Issue Commented event
commentVisibility: if provided, JETI will secure the comment it adds to the issue.
richHtml: if true, JETI will interpret emailBody as a HTML content

Code Block

"emailOptions":
  {
  "addToWatchers":"true",
  "replyToMe":"true",
  "mailAsMe":"false",
  "addComments":"true",
  "suppressCommentEvent":"true", 
  "emailFormat":"text",
  "commentVisibility":"g:jira-administrators",
  "richHtml":"false"
  }

payload

Key-Value map of values that will be added to the Velocity Context used to generate email body.

Email template may refer to these values and may render them in the email.

Request Statistics

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

Parameter

Value

REST path

$JIRA_BASE_URL/rest/jeti/1.0/email/stat

Request Method

GET

Request Headers

Content-Type:application/json

Authentication

What Jira REST API offers

See details in the documentation

Query Parameters

Code Block
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)

Response Codes

200: if email is composed and sent successfully
500: if an error occured while composing and sending the email
401: if the calling user account is not authorized to request the details

Response Data

Number of mail items matching the query

Example

http://JIRA_URL/rest/jeti/1.0/email/stat?issueKey=<issue key>

Request Email Items from the Audit Log

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

Parameter

Value

REST path

$JIRA_BASE_URL/rest/jeti/1.0/email/query

Request Method

GET

Request Headers

Content-Type:application/json

Authentication

What Jira REST API offers

See details in the documentation

Authorization

Only those users may query the email items who are authorized to view them in the issue

Query Parameters

Code Block
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)

Response Codes

200: if email is composed and sent successfully
500: if an error occured while composing and sending the email
401: if the calling user account is not authorized to request the details

Response Data

JSON Array of email items matching the query

Example

http://JIRA_URL/rest/jeti/1.0/email/stat?issueKey=<issue key>

Response structure

Code Block

[
{
"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
Status
colour Green
title since 9.0.0

Incoming Queue Statistics

Parameter

Value

REST path

$JIRA_BASE_URL/rest/jeti/1.0/incomingMailQueue/statistic

Request Method

GET

Request Headers

Content-Type:application/json

Authentication

What Jira REST API offers

See details in the documentation

Response Codes

200: if email is composed and sent successfully
500: if an error occured while composing and sending the email
401: if the calling user account is not authorized to request the details

Response Data

Returns statistics of the incoming mail queue

Code Block

language	json

{
"new":<number of items with status NEW>,
"failed":<number of items with status FAILED>,
"skipped":<number of items with status SKIPPED>,
"processing":<number of items with status PROCESSING>
}

Outgoing Queue Statistics

Parameter

Value

REST path

$JIRA_BASE_URL/rest/jeti/1.0/outgoingMailQueue/statistic

Request Method

GET

Request Headers

Content-Type:application/json

Authentication

What Jira REST API offers

See details in the documentation

Response Codes

200: if email is composed and sent successfully
500: if an error occured while composing and sending the email
401: if the calling user account is not authorized to request the details

Response Data

Returns statistics of the outgoing mail queue

Code Block

language	json

{
"active":<number of items with status ACTIVE>,
"error":<number of items with status ERROR>
}

Mail Generation Queue

Parameter

Value

REST path

$JIRA_BASE_URL/rest/jeti/1.0/mailGenerationQueue/statistic

Request Method

GET

Request Headers

Content-Type:application/json

Authentication

What Jira REST API offers

See details in the documentation

Response Codes

200: if email is composed and sent successfully
500: if an error occured while composing and sending the email
401: if the calling user account is not authorized to request the details

Response Data

Returns statistics of the mail generation queue

Code Block

language	json

{
"totalQueued":<total number of events that was ever queued>,
"totalCompleted":<total number of events completed>,
"currentlyOnQueue":<total number of events currently on queue>,
"activeWorkerThreads":<total number of active worker threads>,
"maxWorkerThreads":<max number of worker threads>,
"avgTimeInQueue":<average amount of time (ms) events spend on the queue>,
"maxQueueSize":<maximum number of events on the queue>
}

OSGi Component API

In case, your Jira add-on want to use JETI's email capabilities, you can build an integration between your add-on and Email This Issue.

Simply import the OSGi component Email This Issue publishes and call its methods.

API

Explanation

Component interface

Code Block
com.metainf.jira.plugin.emailissue.api.EmailService

Component method

Code Block

language	java

void sendEmail(com.metainf.jira.plugin.emailissue.api.EmailDefinitionApi emailDefinition) throws Exception

Component method

Code Block

language	java

Collection<EmailLog> queryEmailLog(com.metainf.jira.plugin.emailissue.api.EmailLogQuery emailLogQuery) throws Exception

Email Parameters

Code Block

language	java

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;
}

...

Versions Compared

Old Version 14

New Version 15

Key

REST API

Send emails

Request Body Json

Request Body Json

Request Statistics

Request Email Items from the Audit Log

Response structure

Queue Statistics
Status
colour Green
title since 9.0.0

Incoming Queue Statistics

Outgoing Queue Statistics

Mail Generation Queue

OSGi Component API

Email Parameters

Page Comparison

Versions Compared

Old Version 14

New Version 15

Key

REST API

Send emails

Request Body Json

Request Body Json

Request Statistics

Request Email Items from the Audit Log

Response structure

Queue Statistics StatuscolourGreentitlesince 9.0.0

Incoming Queue Statistics

Outgoing Queue Statistics

Mail Generation Queue

OSGi Component API

Email Parameters

Queue Statistics
Status
colour Green
title since 9.0.0