Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/interserver/mailbaby-client-perl

MailBaby API Perl Client
https://github.com/interserver/mailbaby-client-perl

Last synced: about 2 months ago
JSON representation

MailBaby API Perl Client

Awesome Lists containing this project

README 

          
# 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](https://en.wikipedia.org/wiki/Representational_state_transfer) API interface.**



# Overview



This is the API interface to the [Mail Baby](https://mail.baby/) Mail services provided by [InterServer](https://www.interserver.net). To use this service you must have an account with us at [my.interserver.net](https://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`).  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](https://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](https://my.interserver.net/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](https://openapi-generator.tech) 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/](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 L 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](https://metacpan.org/pod/distribution/App-cpanminus/bin/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:

```perl

use OpenAPIClient::BlockingApi;

use OpenAPIClient::HistoryApi;

use OpenAPIClient::SendingApi;

use OpenAPIClient::ServicesApi;

use OpenAPIClient::StatusApi;



```



To load the models:

```perl

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

```perl

#!/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**](docs/BlockingApi.md#add_rule) | **POST** /mail/rules | Creates a new email deny rule

*BlockingApi* | [**delete_rule**](docs/BlockingApi.md#delete_rule) | **DELETE** /mail/rules/{ruleId} | Removes a deny mail rule

*BlockingApi* | [**delist_block**](docs/BlockingApi.md#delist_block) | **POST** /mail/blocks/delete | Removes an email address from the block lists

*BlockingApi* | [**get_mail_blocks**](docs/BlockingApi.md#get_mail_blocks) | **GET** /mail/blocks | Displays a list of blocked email addresses

*BlockingApi* | [**get_rules**](docs/BlockingApi.md#get_rules) | **GET** /mail/rules | Displays a listing of deny email rules

*HistoryApi* | [**get_stats**](docs/HistoryApi.md#get_stats) | **GET** /mail/stats | Account usage statistics

*HistoryApi* | [**view_mail_log**](docs/HistoryApi.md#view_mail_log) | **GET** /mail/log | Displays the mail log

*SendingApi* | [**raw_mail**](docs/SendingApi.md#raw_mail) | **POST** /mail/rawsend | Sends a raw RFC 822 email

*SendingApi* | [**send_adv_mail**](docs/SendingApi.md#send_adv_mail) | **POST** /mail/advsend | Sends an Email with Advanced Options

*SendingApi* | [**send_mail**](docs/SendingApi.md#send_mail) | **POST** /mail/send | Sends an Email

*ServicesApi* | [**get_mail_order_by_id**](docs/ServicesApi.md#get_mail_order_by_id) | **GET** /mail/{id} | Displays details for a single mail order

*ServicesApi* | [**get_mail_orders**](docs/ServicesApi.md#get_mail_orders) | **GET** /mail | Displays a list of mail service orders

*StatusApi* | [**ping_server**](docs/StatusApi.md#ping_server) | **GET** /ping | Checks if the server is running



# DOCUMENTATION FOR MODELS

 - [OpenAPIClient::Object::DateOrTimestamp](docs/DateOrTimestamp.md)

 - [OpenAPIClient::Object::DenyRuleNew](docs/DenyRuleNew.md)

 - [OpenAPIClient::Object::DenyRuleRecord](docs/DenyRuleRecord.md)

 - [OpenAPIClient::Object::EmailAddressName](docs/EmailAddressName.md)

 - [OpenAPIClient::Object::EmailAddressNames](docs/EmailAddressNames.md)

 - [OpenAPIClient::Object::EmailAddressParam](docs/EmailAddressParam.md)

 - [OpenAPIClient::Object::EmailAddressTypes](docs/EmailAddressTypes.md)

 - [OpenAPIClient::Object::EmailAddressesTypes](docs/EmailAddressesTypes.md)

 - [OpenAPIClient::Object::ErrorMessage](docs/ErrorMessage.md)

 - [OpenAPIClient::Object::GenericResponse](docs/GenericResponse.md)

 - [OpenAPIClient::Object::MailAttachment](docs/MailAttachment.md)

 - [OpenAPIClient::Object::MailBlockClickHouse](docs/MailBlockClickHouse.md)

 - [OpenAPIClient::Object::MailBlockRspamd](docs/MailBlockRspamd.md)

 - [OpenAPIClient::Object::MailBlocks](docs/MailBlocks.md)

 - [OpenAPIClient::Object::MailLog](docs/MailLog.md)

 - [OpenAPIClient::Object::MailLogEntry](docs/MailLogEntry.md)

 - [OpenAPIClient::Object::MailOrder](docs/MailOrder.md)

 - [OpenAPIClient::Object::MailOrderDetail](docs/MailOrderDetail.md)

 - [OpenAPIClient::Object::MailStatsType](docs/MailStatsType.md)

 - [OpenAPIClient::Object::MailStatsVolume](docs/MailStatsVolume.md)

 - [OpenAPIClient::Object::SendMail](docs/SendMail.md)

 - [OpenAPIClient::Object::SendMailAdv](docs/SendMailAdv.md)

 - [OpenAPIClient::Object::SendMailRaw](docs/SendMailRaw.md)

 - [OpenAPIClient::Object::SendMailTo](docs/SendMailTo.md)



# DOCUMENTATION FOR AUTHORIZATION



Authentication schemes defined for the API:

## apiKeyAuth



- **Type**: API key

- **API key parameter name**: X-API-KEY

- **Location**: HTTP header