This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Mailjet API client for Crystal

Mailjet is an email platform for teams to send transactional & marketing emails. It is a GDPR compliant and ISO 27001 certified Email Service Provider.

Disclaimer

This is the unofficial Crystal shard for Mailjet. The majority of the API is covered, but some parts still need to be added.

Requirements

To use the Mailjet API client, you will need a free Mailjet account.

Installation

1. Add the dependency to your shard.yml:

dependencies:
  mailjet:
    github: wout/mailjet.cr

2. Run shards install

Usage

Include the shard

require "mailjet"

Configure your crendentials

Mailjet.configure do |settings|
  settings.api_key = "your-api-key"
  settings.secret_key = "your-secret-key"
  settings.default_from = "noreply@email.com"
end

Send your first email

response = Mailjet::SendV3_1.message({
  "From": {
    "Email": "from@email.com",
    "Name":  "Me",
  },
  "To": [
    {
      "Email": "to@email.com",
      "Name":  "You",
    },
  ],
  "Subject":  "My first Mailjet Email!",
  "TextPart": "Greetings from Mailjet!",
  "HTMLPart": <<-HTML
    <h3>
      Dear passenger 1, welcome to
      <a href='https://www.mailjet.com/'>Mailjet</a>!
    </h3>
    <br />
    May the delivery force be with you!
  HTML
})

puts response.status
# => "success"

Send multiple messages

response = Mailjet::SendV3_1.messages([
  {...},
  {...}
])

puts response.first.status
# => "success"

Retrieve sent messages

Now, let’s view the status of the sent message and its configuration specifics.

message = Mailjet::Message.find(576460754655154659)
puts message.status
# => "opened"

View message history

You can track important events linked to the sent emails, for example whether the recipient opened the message, or clicked on a link within.

events = Mailjet::Messagehistory.all(576460754655154659)
puts events.first.event_type
# => "sent"
puts events.last.event_type
# => "opened"

Retrieve Statistics

The Mailjet API also has a variety of resources that help retrieve aggregated statistics for key performance indicators like opens, clicks, unsubscribes, etc.

Let's take a look at just one of those resources to give you a sample of the data you can read - we’ll retrieve total aggregated statistics for your API key.

counters = Mailjet::Statcounters.by_api_key({
  counter_timing:     "event",
  counter_resolution: "hour",
  from_ts:            Time.local.at_beginning_of_day.to_unix,
  to_ts:              Time.local.to_unix,
})
puts counters.first.event_opened_count
# => 28

Temporarily use other settings

Mailjet.temp_config(api_version: Mailjet::Api::V3_1) do
  # ... do something ...
end

Documentation

• Shard API Docs

To-do

Most of the API is covered, but the following endpoints are not:

• [ ] All Message Events
• [ ] Bulk contact management and CSV import
• [ ] Parse
• [ ] Settings
• [ ] SMS
• [ ] Statistics (only statcounters is done)
• [ ] Webhook

Contributing

1. Fork it (https://github.com/wout/mailjet.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'feat: add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• wout - creator and maintainer