Installation

PREREQUISITES

• Oracle Database 11gR2 or later
• Oracle Application Express 5.0 or later (just for the apex packages)

(some modification of the code may be required to run this on earlier versions, but it should be feasible)

STEP 1: Get your Mailgun account

Sign up here.

STEP 2: Set up schema

You can install the API in any schema that has the following grants:

    grant create table to myschema;
    grant create job to myschema;
    grant create procedure to myschema;
    grant create type to myschema;

    grant execute on dbms_aq to myschema;
    grant execute on dbms_aqadm to myschema;
    grant execute on dbms_job to myschema;
    grant execute on dbms_scheduler to myschema;
    grant execute on utl_http to myschema;

To run these grants you can use this script if you wish.

The package also uses the following Apex packages, which are usually granted to public already anyway: apex_json, and apex_util (for url_encode).

STEP 3: Set up https connectivity to Mailgun server

Your Oracle database server needs to be able to connect to the Mailgun API via Secure HTTP. There are two methods I can suggest to do this:

1. Oracle wallet
2. Reverse proxy

Method 1: Oracle Wallet

1. Create Network ACL for https://api.mailgun.net (see example below)
2. Add the mailgun https certificate to your Oracle wallet (for more help, refer to this article)

NETWORK ACL example (method 1)

Oracle 12cR1 and later:

  begin
    dbms_network_acl_admin.append_host_ace(
      host       => 'api.mailgun.net',
      lower_port => 443,
      upper_port => 443,
      ace        => xs$ace_type(
                      privilege_list => xs$name_list('connect'),
                      principal_name => 'YOURSCHEMA', -- put your schema here
                      principal_type => xs_acl.ptype_db)
      ); 
  end;
  /

Oracle 11gR2 and earlier:

  begin
    dbms_network_acl_admin.create_acl (
      acl          => 'mailgun.xml', 
      description  => 'Mailgun API',
      principal    => 'YOURSCHEMA', -- put your schema here
      is_grant     => true, 
      privilege    => 'connect');
    dbms_network_acl_admin.assign_acl (
      acl         => 'mailgun.xml',
      host        => 'api.mailgun.net', 
      lower_port  => 443);
    commit;
  end;
  /

Method 2: Reverse Proxy

Uses the method described here

1. Set up a reverse proxy on your server to https://api.mailgun.net (see apache example below)
2. Create Network ACL for http://api.mydomain.com (see example below)

Note: I've used api.mydomain.com in this example, but you could choose anything as long as you've set up the DNS to point to your server.

Reverse proxy example for Apache

<VirtualHost *:80>
  ServerName api.mydomain.com
  SSLProxyEngine on
  ProxyPass /mailgun https://api.mailgun.net
  ProxyPassReverse /mailgun https://api.mailgun.net
  ProxyRequests Off
</VirtualHost>

NETWORK ACL example (method 2)

Oracle 12cR1 and later:

  begin
    dbms_network_acl_admin.append_host_ace(
      host       => 'api.mydomain.com',
      lower_port => 80,
      upper_port => 80,
      ace        => xs$ace_type(
                      privilege_list => xs$name_list('connect'),
                      principal_name => 'YOURSCHEMA', -- put your schema here
                      principal_type => xs_acl.ptype_db)
      ); 
  end;
  /

Oracle 11gR2 and earlier:

  begin
    dbms_network_acl_admin.create_acl (
      acl          => 'mailgun.xml', 
      description  => 'Mailgun API',
      principal    => 'YOURSCHEMA', -- put your schema here
      is_grant     => true, 
      privilege    => 'connect');
    dbms_network_acl_admin.assign_acl (
      acl         => 'mailgun.xml',
      host        => 'api.mydomain.com', 
      lower_port  => 80);
    commit;
  end;
  /

STEP 4: Download

Download the latest release.

STEP 5: Uninstall prior version (if applicable)

If your schema has an older version of the mailgun API installed, uninstall it using:

@uninstall.sql

WARNING: this will drop all old email logs and any emails waiting in the queue to be processed.

STEP 6: Install the API

If you have Logger installed, run this to create the mailgun objects in your schema, create the queue and scheduler jobs:

@install_with_logger.sql

Alternatively, if you don't have Logger installed, run this instead:

@install.sql

STEP 7: Setup your mailgun parameters

Run init to set your mailgun parameters:

begin
  mailgun_pkg.init
    (p_public_api_key  => '...your PUBLIC Mailgun API key...'
    ,p_private_api_key => '...your SECRET Mailgun API key...'
    ,p_my_domain       => '...your domain...');
end;

If you are using Method 1 (Oracle Wallet) Run this to set your wallet path and password:

begin
  mailgun_pkg.init
    (p_wallet_path     => '...your wallet path...'
    ,p_wallet_password => '...your wallet password...');
end;

If you are using Method 2 (Reverse Proxy) Run this to change from the default to point to your API url, and use http:, e.g.:

begin
  mailgun_pkg.init
    (p_api_url => 'http://api.mydomain.com/mailgun/v3/');
end;

STEP 8: Test the API

You may adapt and use the supplied test script if you wish.