Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
protogrid:api_endpoints [2021-09-15 21:13] – [/api/v2/apps/<app_name>/protos] druprotogrid:api_endpoints [2021-12-20 15:38] (current) – [/api/v2/apps/<app_name>/protos/<proto_key>/card-keys] dru
Line 143: Line 143:
     * Example: limit=15     * Example: limit=15
     * Default value: 10     * Default value: 10
-  * descending: If set to true the results will be in descending order.+  * descending: If set to true the results will be in descending order. If set to true start_key and end_key must be exchanged.
     * Example: descending=true     * Example: descending=true
     * Default value: False     * Default value: False
Line 152: Line 152:
  
          
-Noteyou may only use either keys or start_key and end_key.+Please note: 
 +  * You may only use either "keysor "start_keyand "end_key". 
 +  * Key values must be cut off after 300 characters (e. g. string values and sortstrings) because these values are also cut off in the view index.
  
 Details: For more details about the URL parameters see the [[http://docs.couchdb.org/en/stable/api/ddoc/views.html|CouchDB documentation]]. Details: For more details about the URL parameters see the [[http://docs.couchdb.org/en/stable/api/ddoc/views.html|CouchDB documentation]].
Line 178: Line 180:
     "next_card_key": "key",     "next_card_key": "key",
     "rows": [     "rows": [
-      {"key": "example_document_key", "shortname": "example_shortname"},+      {"key": "example_document_key"},
       {…}       {…}
     ]     ]
Line 365: Line 367:
     "next_card_key": "NextProtoKey"     "next_card_key": "NextProtoKey"
     "protos": [     "protos": [
-      {"key": "ExampleProtoKey", "shortname": {"en": "Proto: Example Proto"}}+      {"key": "ExampleProtoKey"}
     ]     ]
   }   }
Line 446: Line 448:
   "result": [   "result": [
     "card_keys":[     "card_keys":[
 +      "ExampleProtoKey",
 +      "ExampleSortstring",
       "ExampleCardKey"       "ExampleCardKey"
     ],     ],
Line 454: Line 458:
  
 ==== /api/v2/apps/<app_name>/mailsend ==== ==== /api/v2/apps/<app_name>/mailsend ====
-[POST] Send an email using the provided data+[POST] Send an email
  
-The following JSON data fields or URL parameters can be used: +To be able to use this endpoint, the SMTP mail server of your organization must first be configured as the designated mail relay server in your Environment. If this has not been done yetplease contact [[protogrid-customer-support@ategra.ch|Protogrid Support]].
-  * to: TO address (multiple addresses separated by comma) +
-  * cc: CC address (multiple addresses separated by comma) +
-  * bcc: BCC address (multiple addresses separated by comma) +
-  * replyto: ReplyTo address +
-  * subject: Subject in plain text +
-  * body: Body text in plain text format (URL encoded) +
-  * bodyhtml: Body text in HTML format (URL encoded). If both body and bodyhtml are specififedonly bodyhtml will be used+
  
-Combinations of JSON data fields and URL parameters are allowed, whereas JSON data fields take precendence over URL parameters+Protogrid will fist try to establish a TLS session to the specified mail relay server and authenticate using the supplied credentials. If TLS is not available it will try to connect using SSL. Finally if SSL is not available the function tries to connect using unsecured SMTP protocol.
  
-The mail will be sent according to the currently logged in user (mail address specified in user profileand the fields "SMTP Server Hostname", "SMTP Server Port" and "SMTP Server Password").+The mail will be sent according to the currently logged in user (mail address specified in user profile and the field "SMTP Server Password" if requested by the mailserver).
  
-The function will fist try to establish a TLS session to the specified mail server and authenticate using the supplied credentials. If TLS is not available it will try to connect using SSL. Finally if SSL is not available the function tries to connect using unsecured SMTP protocol.+The following JSON data fields can be used: 
 +  * to: TO addresses (Array of Strings, mandatory) 
 +  * cc: CC addresses (Array of Strings) 
 +  * bcc: BCC addresses (Array of Strings) 
 +  * reply_to: ReplyTo addresses (Array of Strings) 
 +  * from: From address if other than logged in user (String) 
 +  * subject: Subject (String, mandatory) 
 +  * body_text_plain: Body text in plain text format (String) 
 +  * body_text_html: Body text in HTML format (String) 
 +  * inline_images: Images for embedded display in HTML body using "cid" references (Array of Objects) 
 +  * attachments: Documents to attach to the email (Array of Objects)
  
-The returned result will include success message or details about the particular error. +Attachments and inline images must already reside inside Protogrid, each attached to CardThe logged in user must have read access to this Card(s). Attachments and inline images are specified using an Object with the following structure
- +<code javascript> 
- +
-Example client-side jQuery request using URL parameters+    "card_id": "<ID of the Card on which the attachment or image resides>", 
-<code javascript > +    "file_name": "<Name of the file as it is listed in the Card specified above>" 
-$.post(+}
-    url: "https://example.protogrid.com/api/v2/apps/example/mailsend?to=user1@example.com&cc=user2@example.com&bcc=user3@example.com&replyto=user4@example.com&subject=example&bodyhtml=%3Chtml%3E%0A%3Cbody%3E%0A%0A%3Ch1%3EMy%20First%20Heading%3C%2Fh1%3E%0A%3Cp%3EMy%20first%20paragraph.%3C%2Fp%3E%0A%0A%3C%2Fbody%3E%0A%3C%2Fhtml%3E" +
-}).done(function (response) { +
-    alert("Data: " + JSON.stringify(response)); +
-});+
 </code> </code>
  
 +By default, users can send a mail to up to 10 recipients. This limit can be increased via the roles assigned to the users using the field "Allowed Number of Recipients per Mail Sent" on each Role Definition. However, a mail never can be sent to more than 500 recipients.
  
-Example client-side jQuery request using JSON data fields:+The returned result will include a success message or details about the particular error. 
 + 
 +Example client-side jQuery request:
 <code javascript> <code javascript>
 $.post({ $.post({
     url: "https://example.protogrid.com/api/v2/apps/example/mailsend",     url: "https://example.protogrid.com/api/v2/apps/example/mailsend",
     data: JSON.stringify({     data: JSON.stringify({
- "to": "user1@example.com", +        "to": ["Tester 1️⃣ <test1@ategra.ch>", "Tester 2️⃣ <test2@ategra.ch>"]
- "cc": "user2@example.com", +        "cc": ["Tester 3️⃣ <test3@ategra.ch>", "Tester 4️⃣ <test4@ategra.ch>"]
- "bcc": "user3@example.com", +        "bcc": ["Tester 5️⃣ <test5@ategra.ch>", "Tester 6️⃣ <test6@ategra.ch>"]
- "replyto": "user4@example.com", +        "reply_to": ["Tester 7️⃣ <test7@ategra.ch>", "Tester 8️⃣ <test8@ategra.ch>"], 
- "subject": "Test", +        "from": "Tester 0️⃣ <test0@ategra.ch>", 
- "body": "This%20is%20a%20testmessage", +        "subject": "Test Email with Emojis 👍", 
- }),+        "body_text_plain": "This is a test message in plain text 😎.", 
 +        "body_text_html": "This is a <b>test</b> message 🤖.<br><br>Please check if the message is displayed correctly using several different mail clients or tools like Mailtrap (<a href='https://mailtrap.io'>link</a>).<br><br><img src='cid:logo.png'></img>", 
 +        "inline_images":
 +            {"card_id": "ffc3a027-2fed-45f8-8aa8-adec18a90439", "file_name": "logo.png"
 +        ], 
 +        "attachments":
 +            {"card_id": "ffc3a027-2fed-45f8-8aa8-adec18a90439", "file_name": "Protogrid_Quickstart_Tutorial.pdf"
 +        ] 
 +    }),
     contentType: 'application/json; charset=utf-8'     contentType: 'application/json; charset=utf-8'
 }).done(function (response) { }).done(function (response) {
Line 502: Line 516:
 </code> </code>
  
 +As a response you receive a JSON with the following structure:
 +  * errors [Array]: Contains information if no single email could be sent, otherwise it is empty.
 +  * messages [Array]: Contains information if Protogrid could not establish the connection to the mail server with the most secure transport encryption, otherwise it is empty.
 +  * result [Object]: Contains information regarding individual recipients to whom the email could not be delivered. If the email could be delivered to all recipients equals to { "success": true }.
  
-Example result:+Example response:
 <code javascript> <code javascript>
 { {
-   "errors" : [], +    "errors": [], 
-   "protogrid_environment_version" : "2.1.3", +    "messages": 
-   "result": {"success": true}+    [ 
 +        "Couldn't send the mail using a secure TlS communication channelTrying SSL instead.", 
 +        "Couldn't send the mail an SSL communication channel. Trying without encryption." 
 +    ], 
 +    "result": 
 +    { 
 +        "external@recipient.ch": 
 +        [ 
 +            554, 
 +            "5.7.1 <external@recipient.ch>: Relay access denied" 
 +        ] 
 +    }
 } }
 </code> </code>
Print/export