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 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_output to myschema;
    grant execute on dbms_scheduler to myschema;
    grant execute on dbms_utility 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_debug, apex_json, and apex_util.

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)

  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)

  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

STEP 6: Enter your mailgun parameters

Edit the following constants in mailgun_pkg.pkb:

• g_public_api_key - required for validating email addresses
• g_private_api_key - required for sending emails
• g_my_domain - required for sending emails

If you are using Method 1 (Oracle Wallet), edit the following:

• g_wallet_path - your wallet path
• g_wallet_password - your wallet password

If you are using Method 2 (Reverse Proxy), edit the following:

• g_api_url - change from the default to point to your API url, and use http:, e.g.

    g_api_url constant varchar2(200) := 'http://api.mydomain.com/mailgun/v3/';
  

STEP 7: Install the API

Run the following script to create the mailgun objects in your schema, the queue and scheduler job:

@install.sql

Note: if you get compilation errors like "PLS-00322: declaration of a constant 'x' must contain an initialization assignment", it's probably because you forgot to edit the package body as per step 6 above.

STEP 8: Test the API

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