Required Info
In order for JEMH to process a mail, it needs to use a Profile. Until now Profiles are tied to mailboxes, allowing arbitrary external use of those profiles may trigger unexpected scenarios, therefore:
Profiles will need to explicitly opt-in to API use
Lists of profiles via REST will only show those that have opted-in.
All REST API's require an authenticated user
Changes in JEMH 5.0 (Jira 10+)
In JEMH 5.0, JEMH will not process mail directly through the API, but will store this mail in a nominated folder (JIRA_SHARED_HOME/import/mail/nnn) that is configured as a source for a Jira mail handler. This addresses scalability problems, and removes a source of denial of service.
API
URLS must follow this pattern
create POST /urlOfRestResource
read GET /urlOfRestResource[/id]
update PUT /urlOfRestResource/id
delete DELETE /urlOfRestResource/id
URL | Method | Response | ||||||||||
.../rest/jemh/latest/public/profile/list | GET | List of JSON profile objects that identify Profile NAME and ID. Requires authenticated user (base 64 headers?) Request:
Response:
| ||||||||||
/rest/jemh/latest/public/mailbox/deliver | POST | Request Using an email like:
A CURL command would be of format (NOTE: initially application/x-www-form-urlencoded was supported, since 1.6.15, multipart/form-data is also supported):
URLEncoding the content (shown above) eg through services like http://www.url-encode-decode.com/ and replacing .... with the result:
RESPONSE format:
Example Response:
|
Example script to deliver a mail
The script below will use the first param as the profileID, update the url as applicable, the response will be launched in a browser
Code Block |
---|
#!/bin/bash if [[ $# -eq 0 ]] ; then echo "Usage: send <profileid>" exit 1 fi EML=`cat multipart-alternative.txt` curl -v -u admin:admin -H "Content-Type: application/x-www-form-urlencoded" --data "profileId=$1" --data-urlencode "email=$EML" -X POST http://localhost:2990/jira/rest/jemh/latest/public/mailbox/deliver > out.html firefox out.html & |
Worked JAVA Examples
JDK11 HttpClient
excerptstarter code:
Code Block |
---|
import java.io.File;
import java.io.FileInputStream;
import java.io.FilenameFilter;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
import java.util.stream.Collectors;
...
public static final String FORM_PARAM_PROFILE_ID = "profileId";
public static final String HEADER_AUTHORIZATION = "Authorization";
public static final String HEADER_CONTENT_TYPE = "Content-Type";
public static final String FORM_URLENCODED = "application/x-www-form-urlencoded";
// baseurl
String baseUrl = ComponentAccessor.getApplicationProperties().getString(APKeys.JIRA_BASEURL);
Assert.assertNotNull(baseUrl);
String targetUrl = baseUrl + "/rest/jemh/latest/public/mailbox/deliver";
Map<String,String> urlParameters=new HashMap<>();
urlParameters.put("profileId", ""+profile.getProfileId());
urlParameters.put("email", emailStr);
String urlEncoded = urlParameters.entrySet()
.stream()
.map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
.collect(Collectors.joining("&"));
HttpRequest.BodyPublisher encodedParams = HttpRequest.BodyPublishers.ofString(urlEncoded);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.version(HttpClient.Version.HTTP_1_1)
.uri(new URI(targetUrl))
.POST(encodedParams)
.header(HEADER_CONTENT_TYPE, FORM_URLENCODED)
.header(HEADER_AUTHORIZATION, "Basic " + Base64.getEncoder().encodeToString("admin:admin".getBytes())).build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Assert.assertTrue("Connection was not authenticated", response.statusCode()!=401); |
Example Test Case
Code Block | ||
---|---|---|
| ||
package com.javahollic.jira.emh.publicapi; import java.io.BufferedReader; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.net.MalformedURLException; import java.net.URL; import java.net.URLConnection; import org.apache.commons.codec.binary.Base64; import org.apache.commons.httpclient.HttpClient; import org.apache.commons.httpclient.HttpStatus; import org.apache.commons.httpclient.methods.PostMethod; import org.apache.commons.io.IOUtils; import org.junit.Assert; import org.junit.Test; public class TestPost { @Test public void testPost() throws IOException { InputStream is = getClass().getClassLoader().getResourceAsStream("plaintextEmail.txt"); Assert.assertNotNull(is); String emailStr=IOUtils.toString(is,"UTF-8"); String name = "admin"; String password = "admin"; String authString = name + ":" + password; System.out.println("auth string: " + authString); byte[] authEncBytes = Base64.encodeBase64(authString.getBytes()); String authStringEnc = new String(authEncBytes); System.out.println("Base64 encoded auth string: " + authStringEnc); HttpClient client = new HttpClient(); client.getParams().setParameter("http.useragent", "Test Client"); BufferedReader br = null; PostMethod method = new PostMethod("http://dev-jira:8080/rest/jemh/latest/public/mailbox/deliver"); method.addParameter("profileId", "1"); method.addParameter("email", emailStr); method.addRequestHeader("Authorization", "Basic " + authStringEnc); try { int returnCode = client.executeMethod(method); if (returnCode == HttpStatus.SC_NOT_IMPLEMENTED) { System.err.println("The Post method is not implemented by this URI"); // still consume the response body System.err.println("\n"+method.getResponseBodyAsString()); } else { String response=IOUtils.toString(method.getResponseBodyAsStream()); System.out.println("\n-------------------------\n"+response+"\n-------------------------\n"); } } catch (Exception e) { System.err.println(e); } finally { method.releaseConnection(); if (br != null) try { br.close(); } catch (Exception fe) { } } } @Test public void testGet() { try { String webPage = "http://dev-jira:8080/rest/jemh/latest/public/profile/list"; String name = "admin"; String password = "admin"; String authString = name + ":" + password; System.out.println("auth string: " + authString); byte[] authEncBytes = Base64.encodeBase64(authString.getBytes()); String authStringEnc = new String(authEncBytes); System.out.println("Base64 encoded auth string: " + authStringEnc); URL url = new URL(webPage); URLConnection urlConnection = url.openConnection(); urlConnection.setRequestProperty("Authorization", "Basic " + authStringEnc); InputStream is = urlConnection.getInputStream(); InputStreamReader isr = new InputStreamReader(is); int numCharsRead; char[] charArray = new char[1024]; StringBuffer sb = new StringBuffer(); while ((numCharsRead = isr.read(charArray)) > 0) { sb.append(charArray, 0, numCharsRead); } String result = sb.toString(); System.out.println("*** BEGIN ***"); System.out.println(result); System.out.println("*** END ***"); } catch (MalformedURLException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } } } |
Related articles
Filter by label (Content by label) | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Page Properties | ||
---|---|---|
| ||
|