API - Integration with other services

SINCE VERSION 6.3.0.9/7.0.9

This is an old documentation

This documentation page is valid upto version 7.0.28 of Email This Issue.

For 7.1 and later versions, the documentation is in a new location.

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

REST API

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

{
"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	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	"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.

OSGi Component

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	com.metainf.jira.plugin.emailissue.api.EmailService
Component method	void sendEmail(EmailDefinitionApi emailDefinition) throws Exception
Email parameters	com.metainf.jira.plugin.emailissue.api.EmailDefinitionApi

Email Parameters

public class EmailDefinitionApi {
    private String issue;

    private List<String> to;
    private List<String> cc;
    private List<String> bcc;
    private EmailOptions emailOptions;
    private String emailBody;
    private String emailSubject;

    private List<String> attachments;
    private String addAttachments;
    private String emailTemplate;
    private Map<String, Object> payload;
}