Email Payments API

DadeCore Email Payments API

The DadeCore Email Payments API allows RESTful access to the flexible email payments parser.

The overview provides general details on how the API works, while the resources section outlines each of the resource endpoints.

Overview

• URLs
• Authentication
• Content Type
• Versioning
• Pagination
• Status Codes

URLs

Throughout this document, relative URLs are used in the examples, since the API may be access through different hostnames, e.g. to allow access to the staging environment vs. the production environment.

The actual API implementation uses absolute URLs.

Authentication

All requests to the API require authentication via an access token which must be included in the HTTP request as a token Authorization header.

Authorization: Token token="<TOKEN>"

Content Type

On POST and PATCH requests, the API accepts JSON-formatted request bodies.

Content-Type: application/json

Fields that are not required may be omitted from the request when creating or updating resources. Unsupported fields will be ignored.

Versioning

All requests to the API should include an Accept header to indicate the requested API version.

Accept: application/vnd.dade.core.v1+json

Status Codes

The API makes use of standard HTTP response status codes to indicate success and failure states.

• 200 OK — success
• 201 Created — e.g. a new resource has been created
  • the Location response header indicates the new resource URL
• 401 Unauthorized — e.g. an invalid access token
  • the WWW-Authenticate header indicates the required authentication method
• 403 Forbidden — e.g. the token is valid but not for the given resource
• 422 Unprocessable Entity — e.g. validation errors

Resources

• Root
• Messages

Root

GET /api/email_payments

Returns the API root, which includes the endpoints for the resources. API clients should use this response to lookup the resource URLs instead of hard-coding them into the client.

Example Request

GET /api/email_payments

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.dade.core.v1+json; charset=utf-8

{
  "messages_url": "/api/email_payments/messages"
}

Messages

POST /api/email_payments/messages

Creates a new email payments messages and kicks off the parsing process.

Request Fields

• email — required the RFC 822/2822 email source

Example Request

POST /api/email_payments/messages
Authorization: Token token="f8e6be413cb498ec14132261e8b2d040
Content-Type: application/json

{
  {"email":"From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Payment Request\r\n\r\nBody of the message.\r\n"}
}

Example Response

HTTP/1.1 201 Created
Location: /api/email_payments/messages/52c0e567-ec62-4a02-bbc7-c65544631bbc

GET /api/email_payments/messages/{id}

Returns the status of an email payments message.

Response Fields

• status — one of received or parsed

Example Request

GET /api/email_payments/messages/52c0e567-ec62-4a02-bbc7-c65544631bbc

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.dade.core.v1+json; charset=utf-8

{
  "status": "received"
}