Crate mailjet_client

A client for Mailjet’s API using reqwest and tracing.

Description

This library crate includes an implementation written in Rust for a client of Mailjet’s API. As of today, there is no official Rust client released by the company behind Mailjet. Though there exist a few Rust clients out in , none of them include some of the features that I needed, so here it goes another client implementation in Rust!

Main Features

• Tracing support via Tracing: the library code includes tracing calls using Tracing’s API.
• Usage of Reqwest as internal HTTP client: Reqwest is my crate of choice for this use-case scenarios. The crate Reqwest-tracing is also added to enable tracing support for the internal HTTP client.
• High level of test coverage and support for CI. Given that I aim to include this crate into another service that needs a high level of reliavility, not including a proper set of tests was a non-go.

Caveats

Offering a full client implementation is not my initial plan, so don’t expect a full 1:1 Rust implementation of the existing API clients provided by Mailjet. This project is open-sourced, so if you need to cover some missing endpoint of Mailjet’s API, feel free to open a new Issue describing your needs. Either if you plan to develop it by yourself, or you need somebody else to do it, it will be good to know that there’s interest on adding such missing feature to the client.

Library Structure

The library includes a module that implements the logic to send and receive HTTP requests to the external REST API. Depending on the target endpoint of that API, the request body parameters and the response object will vary. The library’s code attempts to abstract such thing as much as possible using traits. Visit the documentation page for the module crate::data_objects to read a full explanation. In brief, two main objects are distinguish:

Response Objects

Responses object vary depending on the used endpoint. Whilst endpoints that implement the API v3.1 include a lot of information about errors that might ocurred; endpoints that implement the API v3.0 only include a brief error code when errors ocurred. Aside from that, the returned objects as the payload of the response vary quite a lot.

To offer a client as homogeneous as possible, all the client’s member functions return a trait object: crate::data_objects::ResponseObject. Then, structs implement a particular response object, and you’ll need to cast from the trait object to a particular object based on the endpoint that you are using.

Request Objects

The same applies to request objects: client’s member function expect a trait object that implements the trait crate::data_objects::RequestObject. Then, is the client’s implementation who should cast such thing to the particular object expected by the external endpoint.

Usage

The current client only supports sending emails, either using Mailjet’s API v3 or v3.1.

To start sending emails, instantiate the client crate::MailjetClient either directly using crate::MailjetClient::new or (best choice) using the object crate::MailjetClientBuilder, which eases the construction of a new client.

At a bare minimum, you have to provide your API credentials to the client. Check crate::MailjetClient::new’s doc to get more details about those credentials. The rest of parameters are optional.

let client = MailjetClientBuilder::new(api_user, api_key)
    .build()
    .expect("Failed to build a new Mailjet client");

The builder object implements a fluent interface so add as many attributes as you wish to the builder object, and once your done with it, call .build() to complete the process.

Then, composed a new email using either crate::data_objects::SimpleMessage (for API v3.0) or crate::data_objects::SendEmailParams (for API v3.1) and call the send method:

let message = //...;

let response = client.send_email(&message).await?;

Do you need more examples? Visit the examples folder to get a detailed view of the usage of this crate.

Re-exports

pub use data_objects::Response;

Modules

data_objects

This module includes all the object definitions need to interact with the external API data objects.

Structs

MailjetClient

This object implements a client for Mailjet’s REST API.

MailjetClientBuilder

A builder object for MailjetClient.

Enums

ApiVersion

Enum to select the API version of Mailjet’s REST API.

ClientError

Error types returned by the client.