Skip to main content

Emailer

In order to use Devii's built-in Emailer the following steps must be followed in order:

  • Set up email API key
  • Configure at least one email type, which can be reusable
  • Create email rule that will reference an email type

The Emailer requires Jinja2 syntax in specific areas and supports it as an option in others. For detailed usage, please refer to jinja2 documentation

Set up Email API key​

Currently, our system is configured to utilize the SendGrid API. We are planning to integrate additional APIs in the future to expand functionality. If you require an API, you can obtain one from the following link: SendGrid API.

note

The email API key must be set up prior to configuring any additional email settings and can only be set to one API key at a time.

To configure your email API key, use the roles_pbac endpoint as shown in the example below:

GraphQLJSON Response
mutation($i:String!){
  set_email_apikey(apikey:$i){
    apikey
  }
}
variables
{
    "i": "SG.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" 
}
{
  "data": {
    "set_email_apikey": {
      "apikey": "SG.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
  }
}

Create Email Type​


Email Type Input​

The create_email_type mutation sets up the email's template, subject, recipients, sender, queries, and optional fields. Each field is described below:

email_type: ID! (required) Symbolic name for the email type, defined by the user. It should consist of letters, numbers, and underscores for better compatibility. Lowercase and snake_case are preferred.

template: String! (required) HTML document text written in Jinja2 syntax.

subject: String! (required) Jinja2-templated string used to define the subject line. Template substitutions can refer to documented variables or functions.

recipients: [String]! (required) List of strings to define the recipients. May be Jinja2 templated.

sender: String! (required) The email address set as the sender. This field may also be Jinja2-templated.

queries: [email_queryInput] (optional) GraphQL queries run to get additional information from the tenant database for the email template.

options: email_optionsInput (optional) Options for the emailer itself. Currently supported properties are 'cc' and 'bcc', both of which must be arrays of email addresses or Jinja2 template strings referring to email address values. These addresses will be added to the CC and BCC recipients of an email, respectively.


Email query Input​

Describes a GraphQL query run to get additional information from the tenant database for the email template.

query: String! (required) GraphQL query text. Variables must be specified as 'filter', 'ordering', 'limit', and 'offset' as described below.

filter: String (optional) Filter expression for the query. May be Jinja2 templated.

ordering: [String] (optional) Ordering applied to query. Specified as for any Devii GraphQL query.

limit: Int (optional) Limit, as with any Devii GraphQL query.

offset: Int (optional) Offset, as with any Devii GraphQL query.

outvar: String! (required) Output variable to assign the results of this query in the email template. The results will be available under this name within the template, and may be referenced using Jinja2 syntax.


Email Options Input​

Options for the emailer itself. Currently supported properties are 'cc' and 'bcc', both of which must be arrays of email addresses or Jinja2 template strings referring to email address values. These addresses will be added to the CC and BCC recipients of an email, respectively.

cc: [String] (optional) List of email addresses to be added to the CC recipients. May be Jinja2 templated.

bcc: [String] (optional) List of email addresses to be added to the BCC recipients. May be Jinja2 templated.


Email Type New User​

Example: The following example will send an email to a new user added to the devii_users table when the email rule is triggered, you can click to see the corresponding email rule Email Rule for New User that is created later in this document.

GraphQLJSON Response
mutation($i:email_typesInput){
  create_email_type(input:$i){
    email_type
    template
    subject
    recipients
    sender
  }
}
variables
{
  "i": {"email_type": "welcome_email",
        "recipients": "[\"{{records[\\\"new\\\"][\\\"email\\\"]}}\"]",
        "sender": "sender@example.com",
        "subject": "Welcome to Our Service!",
        "template": "<html><body><h1>Welcome, {{records[\"new\"][\"name\"]}}!</h1><p>Thank you for registering.</p></body></html>"
  }  
}
 
{
  "data": {
    "create_email_type": {
      "email_type": "welcome_email",
      "recipients": "[\"{{records[\\\"new\\\"][\\\"email\\\"]}}\"]",
      "sender": "sender@example.com",
      "subject": "Welcome to Our Service!",
      "template": "<html><body><h1>Welcome, {{records[\"new\"][\"name\"]}}!</h1><p>Thank you for registering.</p></body></html>"
    }
  }
}

Email Type New List Added​

The following example will send an email to the recipient and the cc'd email of all lists with the related items in that list, a rule will need to be created that will trigger this email type, you can click to see the corresponding email rule Email Rule for New List that is created later in this document.

GraphQLJSON Response
mutation query_email($i: email_typesInput){
    create_email_type(input: $i){
        email_type
        queries{
            query
        }
        recipients
        sender
        subject
        options{
            cc
        }
        queries{
            query
            outvar
        }
        template
    }
}
variables
{
    "i": {
        "email_type": "new_list_added",
        "recipients": [
                    "someone@example.com"
                ],
        "options": 
            {
                "cc": ["someoneelse@example.com"]
            },
        "queries": [
            {
                "outvar": "outvar",
                "query": "query get_items{ list { listname item_collection { itemname } } }",
                "filter": null,
               "ordering": null,
               "limit": null,
               "offset": null
            }
        ],
        "sender": "sender@example.com",
        "subject": "Hello from email testing",
        "template": "<html><head><title>List of Items</title></head><body><h1>Items List</h1>{% for list in outvar %}<h2>{{ list.listname }}</h2><ul>{% if list.item_collection %}{% for item in list.item_collection %}<li>{{ item.itemname }}</li>{% endfor %}{% else %}<p>No items available</p>{% endif %}</ul>{% endfor %}</body></html>"
    }
}
{
    "data": {
        "create_email_type": {
            "email_type": "new_list_added",
            "options": {
                "cc": [
                    "someoneesle@example.com"
                ]
            },
            "queries": [
                {
                    "outvar": "outvar",
                    "query": "query get_items{ list { listname item_collection { itemname } } }"
                }
            ],
            "recipients": [
                "someone@example.com"
            ],
            "sender": "sender@example.com",
            "subject": "Hello from email testing",
            "template": "<html><head><title>List of Items</title></head><body><h1>Items List</h1>{% for list in outvar %}<h2>{{ list.listname }}</h2><ul>{% if list.item_collection %}{% for item in list.item_collection %}<li>{{ item.itemname }}</li>{% endfor %}{% else %}<p>No items available</p>{% endif %}</ul>{% endfor %}</body></html>"
        }
    }
}

Create Email rules​

This step is required to automatically trigger an email when the rule is activated.

operations: [String]! (required) Specify the applicable database operations such as insert, update, delete, or upload.

targets: [String]! (required) Define the table` to which the rule applies. When a mutation occurs on the specified table, the corresponding email will be sent.

email_type: String! (required) The email type to use to send this email. Must be pre-configured as above..

query_roleid: Int! (required) The role id that will execute any queries associated with the email type.

name: String! (required) Provide a unique name for the email rule.


Email Rule for New User​

The following example is an email rule that will trigger when a new user is added to the 'devii_users' table, this is the rule for the Email Type New User.

GraphQLJSON Response
mutation($i:email_ruleInput){
  create_email_rule(input:$i){
    operations
    targets
    email_type
    query_roleid
    name
  }
}
variables
{
  "i": {
        "email_type": "welcome_email",
        "name": "new_user_email",
        "operations": [
          "insert"
        ],
        "query_roleid": 9999,
        "targets": [
          "devii_users"
        ]
  }
}

{
  "data": {
    "create_email_rule": {
        "email_type": "welcome_email",
        "name": "new_user_email",
        "operations": [
          "insert"
        ],
        "query_roleid": 9999,
        "ruleid": "98",
        "targets": [
          "devii_users"
        ]
    }
  }
}


Email Rule for New List Added​

This email rule will trigger the email type Email Type New List Added.

GraphQLJSON Response
mutation($i:email_ruleInput){
  create_email_rule(input:$i){
    operations
    targets
    email_type
    query_roleid
    name
  }
}
variables
{
  "i": {
        "email_type": "new_list_added",
        "name": "add_list.",
        "operations": [
          "insert"
        ],
        "query_roleid": 9999,
        "targets": [
          "list"
        ]
  }
}

{
  "data": {
    "create_email_rule": {
        "email_type": "new_list_added",
        "name": "add_list",
        "operations": [
          "insert"
        ],
        "query_roleid": 9999,
        "ruleid": "99",
        "targets": [
          "list"
        ]
    }
  }
}