Configuration with cliamrc.js

This section describe the .cliamrc.js file structure.

> Table of contents

• Resume properties
• Properties details
  • sandbox
  • variables
  • placeholders
  • transporters
• Examples

> Resume properties

Property	Type	Properties	Description	Default
sandbox	boolean	/	Enable / disable sandbox mode	false
[variables]	object	domain: string [addresses:object]	TLD From and Reply-to default addresses	/ /
[placeholders]	object	[company: object] [theme: object]	Values who's can be used as placeholders in Cliam default templates	/
transporters	object[]	id: string [provider]: string auth: object options: object templates: object	Unique id of the transporter Name of the web api provider Credentials as API key or username/pwd for SMTP Options according to the mode Mapping between transaction event and templateId	/

> Properties details

sandbox

The sandbox property enable / disable a sandbox environment, and define the specifc addresses used in this mode. This option is not required, and sandbox is disabled by default.

{
  "sandbox": true|false
}

When the sandbox is active, some providers does'nt distribute really the mail, but returns a success or an error message as they would in a real situation.

Some remarks about sandbox mode:

• Mailgun sandbox mode requires that the domain must be sandboxXXX_YOUR_SANDBOX_DOMAIN_ID_XXX.mailgun.org.
• Postmark open test@blackhole.postmarkapp.com as target address for your tests, and some other stub addresses if you want to test bouncing.
• Sparkpost open @sparkpostbox.com as target domain for your tests.
• Mailersend doesn't expose any sandbox
• Mandril play with test api keys instead of separated environment
• Actually the only way to test SMTP is to define test credentials directly in cliamrc.json.

variables

ℹ️ This property is optional.

{
  "variables": {
    "domain": "https://www.john-doe.com",
    "addresses": {
      "from": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "replyTo": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }
  }
}

When you put addresses in cliamrc.js, you don't have to do it anymore during your queries, but obviously you can override on fly.

placeholders

If you want to use the templates exposed by Cliam, fill in the optional placeholders property.

ℹ️ All fields are required.

{
  "placeholders": {
    "url": "https://www.john-doe.com",
    "company": "John Doe Incorporated",
    "location": {
      "street": "Casino street",
      "num": "7",
      "zip": "10001",
      "city": "New-York",
      "country": "USA"
    },
    "email": "contact@john-doe.com",
    "phone": "+18666148152",
    "socials": [
      { "name": "github", "url": "https://github.com/john-doe/" }
    ],
    "theme": {
      "logo": "https://www.john-doe.com/img/design/logo.png",
      "primaryColor": "5bd1d7",
      "secondaryColor": "348498",
      "tertiaryColor": "004d61",
      "quaternaryColor": "ff502f"
    }
  }
}

In this use case, all fields are required.

Property socials should be an array of objects for wich each entry name must be one of following supported social networks:

type SocialNetwork = 'github' | 'facebook' | 'twitter' | 'linkedin' | 'youtube' | 'instagram' | 'pinterest'

transporters

The transporters property is required and can take all the transporters you want to use in your project, using api or smtp.

Web API

If you work with a web API provider, your transporter should look like this:

    {
      "id": "unique-id-sendgrid-api",
      "provider": "sendgrid",
      "auth": {
        "apiKey": "API_KEY"
      },
      "templates": {
          "default": "d-321bb40f548e4db8a628b4d6464ebacc",
          "event.subscribe": "d-321bb40f548e4db8a628b4d6464ebacc",
          "user.welcome": "d-321bb40f548e4db8a628b4d6464ebacc",
          ...
        }
    },

Property provider is required if you want to send emails using a web API. In this case, must be one of following supported providers:

type Transporter = 'sparkpost' | 'sendgrid' | 'mailgun' | 'mailjet' | 'mandrill' | 'amazon-ses' | 'mailersend' | 'sendinblue' | 'postmark' | 'brevo';

Property auth.apiKey is obviously required. auth.apiSecret - is required by Mailjet only.

Property templates is a map between transactional events and templates references from the provider. The key can be one of the default ones, but as well a custom. In this last case, you just need to map correctly your custom event with the template id of your provider.

👉 See supported transactions for more information about transactions and available default keys.

SMTP server

If you work with a SMTP server, your mode should look like this:

{
      "id": "unique-id-hosted-smtp",
      "auth": {
        "username": "USERNAME",
        "password": "PASSWORD"
      },
      "options": {
        "host": "mail.host.com",
        "port": 587,
        "secure": true
      }
    }

All properties are required.