NAME

OpenAPIClient::Role - a Moose role for the MailBaby Email Delivery and Management Service API

Send emails fast and with confidence through our easy to use REST API interface.

Overview

This is the API interface to the Mail Baby Mail services provided by InterServer. To use this service you must have an account with us at my.interserver.net.

Mail Orders

Every sending account in MailBaby is backed by a Mail Order — a provisioned sending credential with a numeric id and a corresponding SMTP username (mb<id>). Most calls accept an optional id parameter; when omitted the API automatically selects the first active order on your account. Use GET /mail to list all orders, and GET /mail/{id} to inspect a single order including its current SMTP password.

Sending Email

Three sending methods are available depending on your use-case: | Endpoint | Best for | |----------|----------| | POST /mail/send | Simple single-recipient messages | | POST /mail/advsend | Multiple recipients, CC/BCC, attachments, named contacts | | POST /mail/rawsend | Pre-built RFC 822 messages (e.g. DKIM-signed payloads) |

After a successful send each endpoint returns a GenericResponse whose text field contains the transaction ID assigned by the relay. This ID can later be matched against entries in GET /mail/log via the mailid query parameter.

Filtering & Logs

GET /mail/log provides paginated access to every message accepted by the relay for your account. Combine any of the query parameters to narrow results — e.g. from, to, subject, messageId, origin, mx, startDate/endDate, and delivered.

Blocking

Two independent mechanisms exist for suppressing unwanted email:

Block lists (GET /mail/blocks, POST /mail/blocks/delete) — addresses flagged by the system spam filters (LOCAL_BL_RCPT / MBTRAP rules in rspamd, and suspicious subjects).
Deny rules (GET /mail/rules, POST /mail/rules, DELETE /mail/rules/{ruleId}) — custom rules you configure to reject specific senders, domains, destination addresses, or subject-line prefixes before a message is even attempted.

Authentication

In order to use most of the API calls you must pass credentials from the my.interserver.net site. We support several different authentication methods but the preferred method is to use the API Key which you can get from the Account Security page. Pass your key in the X-API-KEY HTTP request header for every protected call.

VERSION

Automatically generated by the OpenAPI Generator project:

API version: 1.4.0
Package version: 1.0.0
Generator version: 7.21.0
Build package: org.openapitools.codegen.languages.PerlClientCodegen For more information, please visit https://www.mail.baby/contact/

A note on Moose

This role is the only component of the library that uses Moose. See OpenAPIClient::ApiFactory for non-Moosey usage.

SYNOPSIS

The Perl Generator in the OpenAPI Generator project builds a library of Perl modules to interact with a web service defined by a OpenAPI Specification. See below for how to build the library.

This module provides an interface to the generated library. All the classes, objects, and methods (well, not quite *all*, see below) are flattened into this role.

    package MyApp;
    use Moose;
    with 'OpenAPIClient::Role';

    package main;

    my $api = MyApp->new({ tokens => $tokens });

    my $pet = $api->get_pet_by_id(pet_id => $pet_id);

Structure of the library

The library consists of a set of API classes, one for each endpoint. These APIs implement the method calls available on each endpoint.

Additionally, there is a set of "object" classes, which represent the objects returned by and sent to the methods on the endpoints.

An API factory class is provided, which builds instances of each endpoint API.

This Moose role flattens all the methods from the endpoint APIs onto the consuming class. It also provides methods to retrieve the endpoint API objects, and the API factory object, should you need it.

For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.

Configuring authentication

In the normal case, the OpenAPI Spec will describe what parameters are required and where to put them. You just need to supply the tokens.

my $tokens = {
    # basic
    username => $username,
    password => $password,

    # oauth
    access_token => $oauth_token,

    # keys
    $some_key => { token => $token,
                   prefix => $prefix,
                   in => $in,             # 'head||query',
                   },

    $another => { token => $token,
                  prefix => $prefix,
                  in => $in,              # 'head||query',
                  },
    ...,

    };

    my $api = MyApp->new({ tokens => $tokens });

Note these are all optional, as are prefix and in, and depend on the API you are accessing. Usually prefix and in will be determined by the code generator from the spec and you will not need to set them at run time. If not, in will default to 'head' and prefix to the empty string.

The tokens will be placed in a LOpenAPIClient::Configuration instance as follows, but you don't need to know about this.

$cfg->{username}

String. The username for basic auth.
$cfg->{password}

String. The password for basic auth.

$cfg->{api_key}

Hashref. Keyed on the name of each key (there can be multiple tokens).

      $cfg->{api_key} = {
              secretKey => 'aaaabbbbccccdddd',
              anotherKey => '1111222233334444',
              };

$cfg->{api_key_prefix}

Hashref. Keyed on the name of each key (there can be multiple tokens). Note not all api keys require a prefix.

      $cfg->{api_key_prefix} = {
              secretKey => 'string',
              anotherKey => 'same or some other string',
              };

$cfg->{access_token}

String. The OAuth access token.

METHODS

`base_url`

The generated code has the base_url already set as a default value. This method returns the current value of base_url.

`api_factory`

Returns an API factory object. You probably won't need to call this directly.

    $self->api_factory('Pet'); # returns a OpenAPIClient::PetApi instance

    $self->pet_api;            # the same

MISSING METHODS

Most of the methods on the API are delegated to individual endpoint API objects (e.g. Pet API, Store API, User API etc). Where different endpoint APIs use the same method name (e.g. new()), these methods can't be delegated. So you need to call $api->pet_api->new().

In principle, every API is susceptible to the presence of a few, random, undelegatable method names. In practice, because of the way method names are constructed, it's unlikely in general that any methods will be undelegatable, except for:

    new()
    class_documentation()
    method_documentation()

To call these methods, you need to get a handle on the relevant object, either by calling $api->foo_api or by retrieving an object, e.g. $api->get_pet_by_id(pet_id => $pet_id). They are class methods, so you could also call them on class names.

BUILDING YOUR LIBRARY

See the homepage https://openapi-generator.tech for full details. But briefly, clone the git repository, build the codegen codebase, set up your build config file, then run the API build script. You will need git, Java 7 or 8 and Apache maven 3.0.3 or better already installed.

The config file should specify the project name for the generated library:

    {"moduleName":"WWW::MyProjectName"}

Your library files will be built under WWW::MyProjectName.

      $ git clone https://github.com/openapitools/openapi-generator
      $ cd openapi-generator
      $ mvn package
      $ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i [URL or file path to JSON OpenAPI API spec] \
-g perl \
-c /path/to/config/file.json \
-o /path/to/output/folder

Bang, all done. Run the autodoc script in the bin directory to see the API you just built.

AUTOMATIC DOCUMENTATION

You can print out a summary of the generated API by running the included autodoc script in the bin directory of your generated library. A few output formats are supported:

      Usage: autodoc [OPTION]

-w           wide format (default)
-n           narrow format
-p           POD format
-H           HTML format
-m           Markdown format
-h           print this help message
-c           your application class

The -c option allows you to load and inspect your own application. A dummy namespace is used if you don't supply your own class.

DOCUMENTATION FROM THE OpenAPI Spec

Additional documentation for each class and method may be provided by the OpenAPI spec. If so, this is available via the class_documentation() and method_documentation() methods on each generated object class, and the method_documentation() method on the endpoint API classes:

    my $cmdoc = $api->pet_api->method_documentation->{$method_name};

    my $odoc = $api->get_pet_by_id->(pet_id => $pet_id)->class_documentation;
    my $omdoc = $api->get_pet_by_id->(pet_id => $pet_id)->method_documentation->{method_name};

Each of these calls returns a hashref with various useful pieces of information.

Installation Prerequisites

Use cpanm to install the module dependencies:

cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
cpanm --quiet --no-interactive Class::Accessor Test::Exception Test::More Log::Any LWP::UserAgent URI::Query Module::Runtime DateTime Module::Find Moose::Role JSON

LOAD THE MODULES

To load the API packages:

use OpenAPIClient::BlockingApi;
use OpenAPIClient::HistoryApi;
use OpenAPIClient::SendingApi;
use OpenAPIClient::ServicesApi;
use OpenAPIClient::StatusApi;

To load the models:

use OpenAPIClient::Object::DateOrTimestamp;
use OpenAPIClient::Object::DenyRuleNew;
use OpenAPIClient::Object::DenyRuleRecord;
use OpenAPIClient::Object::EmailAddressName;
use OpenAPIClient::Object::EmailAddressNames;
use OpenAPIClient::Object::EmailAddressParam;
use OpenAPIClient::Object::EmailAddressTypes;
use OpenAPIClient::Object::EmailAddressesTypes;
use OpenAPIClient::Object::ErrorMessage;
use OpenAPIClient::Object::GenericResponse;
use OpenAPIClient::Object::MailAttachment;
use OpenAPIClient::Object::MailBlockClickHouse;
use OpenAPIClient::Object::MailBlockRspamd;
use OpenAPIClient::Object::MailBlocks;
use OpenAPIClient::Object::MailLog;
use OpenAPIClient::Object::MailLogEntry;
use OpenAPIClient::Object::MailOrder;
use OpenAPIClient::Object::MailOrderDetail;
use OpenAPIClient::Object::MailStatsType;
use OpenAPIClient::Object::MailStatsVolume;
use OpenAPIClient::Object::SendMail;
use OpenAPIClient::Object::SendMailAdv;
use OpenAPIClient::Object::SendMailRaw;
use OpenAPIClient::Object::SendMailTo;

GETTING STARTED

Put the Perl SDK under the 'lib' folder in your project directory, then run the following

#!/usr/bin/perl
use lib 'lib';
use strict;
use warnings;
# load the API package
use OpenAPIClient::BlockingApi;
use OpenAPIClient::HistoryApi;
use OpenAPIClient::SendingApi;
use OpenAPIClient::ServicesApi;
use OpenAPIClient::StatusApi;

# load the models
use OpenAPIClient::Object::DateOrTimestamp;
use OpenAPIClient::Object::DenyRuleNew;
use OpenAPIClient::Object::DenyRuleRecord;
use OpenAPIClient::Object::EmailAddressName;
use OpenAPIClient::Object::EmailAddressNames;
use OpenAPIClient::Object::EmailAddressParam;
use OpenAPIClient::Object::EmailAddressTypes;
use OpenAPIClient::Object::EmailAddressesTypes;
use OpenAPIClient::Object::ErrorMessage;
use OpenAPIClient::Object::GenericResponse;
use OpenAPIClient::Object::MailAttachment;
use OpenAPIClient::Object::MailBlockClickHouse;
use OpenAPIClient::Object::MailBlockRspamd;
use OpenAPIClient::Object::MailBlocks;
use OpenAPIClient::Object::MailLog;
use OpenAPIClient::Object::MailLogEntry;
use OpenAPIClient::Object::MailOrder;
use OpenAPIClient::Object::MailOrderDetail;
use OpenAPIClient::Object::MailStatsType;
use OpenAPIClient::Object::MailStatsVolume;
use OpenAPIClient::Object::SendMail;
use OpenAPIClient::Object::SendMailAdv;
use OpenAPIClient::Object::SendMailRaw;
use OpenAPIClient::Object::SendMailTo;

# for displaying the API response data
use Data::Dumper;


my $api_instance = OpenAPIClient::BlockingApi->new(
    # Configure API key authorization: apiKeyAuth
    api_key => {'X-API-KEY' => 'YOUR_API_KEY'},
    # uncomment below to setup prefix (e.g. Bearer) for API key, if needed
    #api_key_prefix => {'X-API-KEY' => 'Bearer'},
);

my $type = "type_example"; # string | The matching strategy for this rule.  `email` blocks an exact sender address, `domain` blocks all senders at a domain, `destination` blocks an exact recipient address, and `startswith` blocks any sender whose local-part begins with the given prefix.
my $data = "data_example"; # string | The value to match against, interpreted according to `type`: a full email address for `email`/`destination`, a domain name for `domain`, or an alphanumeric prefix string for `startswith`.
my $user = "user_example"; # string | Optional SMTP username of the mail order to associate this rule with (e.g. `mb20682`).  If omitted the first active order is used.  Valid usernames are the `username` values returned by `GET /mail`.

eval {
    my $result = $api_instance->add_rule(type => $type, data => $data, user => $user);
    print Dumper($result);
};
if ($@) {
    warn "Exception when calling BlockingApi->add_rule: $@\n";
}

DOCUMENTATION FOR API ENDPOINTS

All URIs are relative to https://api.mailbaby.net

Class	Method	HTTP request	Description
BlockingApi	add_rule	POST /mail/rules	Creates a new email deny rule
BlockingApi	delete_rule	DELETE /mail/rules/{ruleId}	Removes a deny mail rule
BlockingApi	delist_block	POST /mail/blocks/delete	Removes an email address from the block lists
BlockingApi	get_mail_blocks	GET /mail/blocks	Displays a list of blocked email addresses
BlockingApi	get_rules	GET /mail/rules	Displays a listing of deny email rules
HistoryApi	get_stats	GET /mail/stats	Account usage statistics
HistoryApi	view_mail_log	GET /mail/log	Displays the mail log
SendingApi	raw_mail	POST /mail/rawsend	Sends a raw RFC 822 email
SendingApi	send_adv_mail	POST /mail/advsend	Sends an Email with Advanced Options
SendingApi	send_mail	POST /mail/send	Sends an Email
ServicesApi	get_mail_order_by_id	GET /mail/{id}	Displays details for a single mail order
ServicesApi	get_mail_orders	GET /mail	Displays a list of mail service orders
StatusApi	ping_server	GET /ping	Checks if the server is running

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.openapi-generator		.openapi-generator
bin		bin
docs		docs
lib/OpenAPIClient		lib/OpenAPIClient
t		t
.gitignore		.gitignore
.openapi-generator-ignore		.openapi-generator-ignore
.travis.yml		.travis.yml
.whitesource		.whitesource
README.md		README.md
cpanfile		cpanfile
git_push.sh		git_push.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NAME

Overview

Mail Orders

Sending Email

Filtering & Logs

Blocking

Authentication

VERSION

A note on Moose

SYNOPSIS

Structure of the library

Configuring authentication

METHODS

`base_url`

`api_factory`

MISSING METHODS

BUILDING YOUR LIBRARY

AUTOMATIC DOCUMENTATION

DOCUMENTATION FROM THE OpenAPI Spec

Installation Prerequisites

LOAD THE MODULES

GETTING STARTED

DOCUMENTATION FOR API ENDPOINTS

DOCUMENTATION FOR MODELS

DOCUMENTATION FOR AUTHORIZATION

apiKeyAuth

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

NAME

Overview

Mail Orders

Sending Email

Filtering & Logs

Blocking

Authentication

VERSION

A note on Moose

SYNOPSIS

Structure of the library

Configuring authentication

METHODS

base_url

api_factory

MISSING METHODS

BUILDING YOUR LIBRARY

AUTOMATIC DOCUMENTATION

DOCUMENTATION FROM THE OpenAPI Spec

Installation Prerequisites

LOAD THE MODULES

GETTING STARTED

DOCUMENTATION FOR API ENDPOINTS

DOCUMENTATION FOR MODELS

DOCUMENTATION FOR AUTHORIZATION

apiKeyAuth

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`base_url`

`api_factory`

Packages