Donor Tools

Emails - Donor Tools User Guide

Acknowledgement Emails API

You can use Emails to send thank-you acknowledgements via Donor Tools built-in email system.

Emails is a REST resource supporting the HTTP verbs GET, POST, PUT, and DELETE. All requests are scoped by organization, and must be authenticated and passed via SSL (HTTPS port 443).

Email Data Structure

You can view the data structure and available fields for an Email resource by requesting a new Email.

Each email should reference at least one donation. Pass the donation ids through the "donation-ids" parameter.

Request

GET /donations/:donation_id/emails/new.(xml|json)

Response

Status: 200 OK 
<?xml version="1.0" encoding="UTF-8"?>
<email>
  <body nil="true"></body>
  <cc nil="true"></cc>
  <created-at type="datetime" nil="true"></created-at>
  <from>info@donortools.com</from>
  <mailing-id type="integer" nil="true"></mailing-id>
  <meta nil="true"></meta>
  <organization-id type="integer">10001</organization-id>
  <persona-id type="integer">10008</persona-id>
  <sent-at type="datetime" nil="true"></sent-at>
  <sent-on type="date" nil="true"></sent-on>
  <subject>Thank you from Demos International</subject>
  <to>Stephen.C.Mitchell@spambob.com</to>
  <updated-at type="datetime" nil="true"></updated-at>
  <user-id type="integer">10001</user-id>
  <donation-ids type="array">
    <donation-id type="integer">2215551</donation-id>
  </donation-ids>
</email>

Listing Emails

Request

GET /personas/:persona_id/emails.(xml|json)

Response

Status: 200 OK 
<?xml version="1.0" encoding="UTF-8"?>
<emails type="array" current_page="1" per_page="30" total_entries="2">
  <email>
    ...
  </email>
</emails>

Get a Specified Email by Id

Request

GET /emails/1.(xml|json)

Response

Status: 200 OK 
<?xml version="1.0" encoding="UTF-8"?>
<email>
  ...
</email>

Create an Email

Before creating an email, look at the available attributes by requesting "/donations/:donation_id/emails/new.(xml|json)" (above).

Request

POST /donations/:donation_id/emails.(xml|json) 
<?xml version="1.0" encoding="UTF-8"?>
<email>
  <to>Stephen.C.Mitchell@spambob.com</to>
  <from>you@example.com</from>
  <subject>Thank you from Demos International</subject>
  <body>Dear {{ donor.salutation }},
  Thanks for your donation of {{ donation.describe }}</body>
</email>

Response

Status: 201 CREATED 
<?xml version="1.0" encoding="UTF-8"?>
<email>
  <to>Stephen.C.Mitchell@spambob.com</to>
  <from>you@example.com</from>
  <subject>Thank you from Demos International</subject>
  <body>Thanks for your donation of {{ donation.describe }}</body>
  <body-merged>Dear Stephen,
    Thanks for your donation of $50.00 for
    General Support received on Jan 10, 2012
  </body-merged>
</email>

Required Attributes

The following attributes are required for every email:

  • Donation Id (passed through the “donation-ids” node)
  • Body

Body

The body is the text that will be sent to the recipient. You can use mail merge fields to insert the donor’s name and other information into the email. The body will be merged when the email is saved, and the saved body will be accessible via the “body-merged” field.

Delivery

By default, the email will be created and saved as a draft. It will not be delivered. To deliver the email, simply add “deliver=true” to the URL query string, like so:

Request

POST /donations/123/emails.xml?deliver=true

This will cause the email to be saved and delivered at the same time.