A client API to the MailGun Email RESTful API.
You can sign up for a free account at:
https://signup.mailgun.com/new/signup
And the latest API documentation is available at:
https://documentation.mailgun.com/en/latest/
To access direct calls to the service, you will want to use the
`MailgunEx.Api` module. When making requests, you can provide
several `opts`, all of which can be defaulted using `Mix.Config`.
Here is an example of how to configure this library
config :mailgun_ex,
base: "https://api.mailgun.net/v3",
mode: :live,
domain: "namedb.org",
api_key: "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
http_opts: %{
timeout: 5000,
}
The configs use a library called [Deferred Config](https://hex.pm/packages/deferred_config)
so that you can use environment variables that will be loaded at runtime, versus
compiled into the release.
Here's an example of how to use the system variables
config :mailgun_ex,
base: "https://api.mailgun.net/v3",
mode: {:system, "MAILGUN_MODE", :live, {String, :to_atom}},
domain: {:system, "MAILGUN_DOMAIN", "defaultname.com"} ,
api_key: {:system, "MAILGUN_API_KEY"},
http_opts: %{
timeout: 5000,
}
Our default `mix test` tests will use [Bypass](https://hex.pm/packages/bypass)
as the `base` service URL so that we will not hit your production MailGun
account during testing.
Here is an outline of all the configurations you can set.
* `:base` - The base URL which defaults to `https://api.mailgun.net/v3`
* `:mode` - Defaults to `:live`, but can be set to `:simulate` for testing, or `:ignore` for dev
* `:domain` - The domain making the request (e.g. namedb.org)
* `:api_key` - Your mailgun API key, which looks like `key-3ax6xnjp29jd6fds4gc373sgvjxteol0`
* `:http_opts` - A passthrough map of options to send to HTTP request, more details below
This client library uses [HTTPoison](https://hex.pm/packages/httpoison)
for all HTTP communication, and we will pass through any `:http_opts` you provide,
which we have shown below.
* `:timeout` - timeout to establish a connection, in milliseconds. Default is 8000
* `:recv_timeout` - timeout used when receiving a connection. Default is 5000
* `:stream_to` - a PID to stream the response to
* `:async` - if given :once, will only stream one message at a time, requires call to stream_next
* `:proxy` - a proxy to be used for the request; it can be a regular url or a {Host, Port} tuple
* `:proxy_auth` - proxy authentication {User, Password} tuple
* `:ssl` - SSL options supported by the ssl erlang module
* `:follow_redirect` - a boolean that causes redirects to be followed
* `:max_redirect` - an integer denoting the maximum number of redirects to follow
* `:params` - an enumerable consisting of two-item tuples that will be appended to the url as query string parameters
If these are out of date, please push a Pull-Request to [mailgun_ex](https://github.com/work-samples/mailgun_ex)
"""
@doc """
Issues an HTTP request with the given method to the given url_opts.
Args:
* `method` - HTTP method as an atom (`:get`, `:head`, `:post`, `:put`, `:delete`, etc.)
* `opts` - A keyword list of options to help create the URL, provide the body and/or query params
The options above can be defaulted using `Mix.Config` configurations,
as documented above.
This function returns `{<status_code>, response}` if the request is successful, and
`{:error, reason}` otherwise.
## Installation
```elixir
@deps [
mailgun_ex: "~> 0.2.5"
]
```
## Examples
MailgunEx.request(:get, resource: "domains")
## License
MIT