This project has been deprecated
Thin wrapper for the Email API to handle basic GET and POST operations for email entries.
- Installation
- Configuration
- Methods
- Error Handling
- Logging
- Development
- Publishing
- Changelog
- License
- Contributing
- Security Issues
Ensure you have the credentials configured with bundler, then add the following to your Gemfile:
source 'https://<domain-of-our-private-gem-server>/' do
gem 'certify_email'
end
Add the following to your Gemfile to bring in the gem from GitHub:
gem 'certify_email', git: 'git@github.com:USSBA/certify_email.git', branch: 'develop'
This will pull the head of the develop branch in as a gem. If there are updates to the gem repository, you will need to run bundle update certify_email
to get them.
- Clone this repository
- Add it to the Gemfile with the path:
gem 'certify_email', path: '<path-to-the-gem-on-your-system>'
Within the host application, set the Certify Email API URL in config/initializers
, you probably also want to include a email.yml
under config
to be able to specify the URL based on your environment.
CertifyEmail.configure do |config|
config.api_key = "your_api_key"
config.api_url = "http://localhost:3000"
config.api_version = 1
config.excon_timeout = 5
end
The api_key
is currently unused, but we anticipate adding in an API Gateway layer in the future.
Refer to the Email API for more complete documentation and detailed examples of method responses.
Method | Description |
---|---|
CertifyEmail::Email.send_email( recipient: 'foo@bar.com', message: 'This is a message', template: 'basic_template', subject: 'This is a subject' ) |
Send a request to the Email API for a given email address with the send method. This method requires that the address, a message, and the template used to format the email be passed in as parameters. Currently the only available template is basic_template |
The Gem handles a few basic errors including:
- Bad Request - Raised when API returns the HTTP status code 400
- NotFound - Raised when API returns the HTTP status code 404
- InternalServerError - Raised when API returns the HTTP status code 500
- ServiceUnavailable - Raised when API returns the HTTP status code 503
Otherwise the gem will return more specific errors from the API. Refer to the API Docs for details around the specific error.
A typical error will look something like this:
{:body=>{"message"=>"Invalid parameters provided"}, :status=>404}
Along with returning status error messages for API connection issues, the gem will also log connection errors. The default behavior for this is to use the built in Ruby Logger
and honor standard log level protocols. The default log level is set to debug
and will output to STDOUT
. This can also be configured by the gem user to use the gem consumer application's logger, including the app's environment specific log level.
# example implementation for a Rails app
CertifyEmail.configure do |config|
config.logger = Rails.logger
config.log_level = Rails.configuration.log_level
end
After checking out the repo, run bundle install
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
Use bin/console
to access the pry console and add the API URL to the gem's config to be able to correctly test commands:
CertifyEmail.configuration.api_url="http://localhost:3001"
While working in the console, you can run reload!
to reload any code in the gem so that you do not have to restart the console. This should not reset the manual edits to the configuration
as noted above.
To release a new version:
- Bump the version in lib/*/version.rb
- Merge into
master
(optional) - Push a tag to GitHub in the form:
X.Y.Z
orX.Y.Z.pre.myPreReleaseTag
At this point, our CI process will kick-off, run the tests, and push the built gem into our Private Gem server.
Refer to the changelog for details on API updates. CHANGELOG
Certify Email is licensed permissively under the Apache License v2.0. A copy of that license is distributed with this software.
We welcome contributions. Please read CONTRIBUTING for how to contribute.
We strive for a welcoming and inclusive environment for the Certify Email project.
Please follow this guidelines in all interactions:
- Be Respectful: use welcoming and inclusive language.
- Assume best intentions: seek to understand other's opinions.
Please do not submit an issue on GitHub for a security vulnerability. Please contact the development team through the Certify Help Desk at help@certify.sba.gov.
Be sure to include all the pertinent information.
The agency reserves the right to change this policy at any time.