Emails

Emails are an important part of any billing system. People receive receipts for purchases, administrators receive notices of payment, subscribers receive renewal notices, etc. This functionality is powered by ReceivePay's powerful email trigger system. You can create emails and attach them to any one of many "system triggers". When this trigger is tripped, an email will be sent just as you have configured it to be.

These triggers are identical to the triggers used when sending Post notifications for recurring charges:

• Charge (system name: "charge")
• New Recurring (system name: "recurring_new")
• Recurring Charge (system name: "recurring_charge")
• Recurring Expiration (system name: "recurring_expire")
• Recurring Cancellation (system name: "recurring_cancel")
• Recurring to Expire in a Week (system name: "recurring_expiring_in_week")
• Recurring to Expire in a Month (system name: "recurring_expiring_in_month")
• Recurring to Autocharge in a Week (system name: "recurring_autorecur_in_week")
• Recurring to Autocharge in a Month (system name: "recurring_autorecur_in_month")
• New Customer (system name: "new_customer")

Variables

Depending on the trigger, there are optional variables that can be placed in the email_subject and email_body in the form of [[VARIABLE_NAME]]. They will be dynamically replaced upon sending the email.

To see what variables are available for each system trigger, make a call to GetEmailVariables.

Formatting Dates in Emails

Date variables are often available in emails for things like the Next Charge Date, Order Date, etc. You are able to specify the format for these dates. For example, while the date variable may be "2010-09-19", you can print this as:

• September 19, 2010
• Sep 19, 2010
• 2010.09.19
• 19-Sep-2010
• etc.

Formatting is done by passing a parameter with the variable. For Example: [[NEXT_CHARGE_DATE|"M d, Y"]]. The second parameter (in quotation marks) tells the application how to display the dates. You can specify any date format using either of PHP's date() and strftime() formatting styles.

Object Data

The following data can be sent in the NewEmail and UpdateEmail methods.

Variable	Type	Required	Format/Example
trigger_id	string	yes	The system name of the email trigger (e.g. "charge", "new_customer")
email_subject	email_subject	yes	The subject of the email being sent, may include dynamically-generated variables.
email_body	string	yes	The body of the email, may include dynamically-generated variables.
is_html	int	yes	Set to "1" to send the email with proper HTML headers. The email_body should be in HTML format.
from_name	string	yes	The name of the sender.
plan_id	int		Only send the email when the action involves a plan of this type. Can also be "0" for All Plans (but must involve a plan), or "-1" for No Plans. Leave blank or don't include as a parameter to have it send for any plan or non-plan.
to_address	email or string	yes	The email address to send the email to. To send to the current customer, enter "customer". To send to the email attached to your client account, set to "client".
bcc_address	email or string	yes	The email address to send a Blind Carbon Copy of the email to. To send to the email attached to your client account, set to "client".

Method: NewEmail

Create a new system email. Should include all required parameters in Object Data and whichever optional parameters necessary.

Response data:

• response_code - "600" upon success.
• response_text - A verbose description of the response_code.
• email_id - The ID of the email created.

Method: UpdateEmail

Update a system email.

Request data:

• email_id - The system ID of the email to update.
• Any of the variables in the Object Data.

Response data:

• response_code - "601" upon success.
• response_text - A verbose description of the response_code.

Method: DeleteEmail

Delete an email from the system.

Request data:

• email_id - The system ID of the email to delete.

Response data:

• response_code - "602" upon success.
• response_text - A verbose description of the response_code.

Method: GetEmail

Get a specific email by its ID.

Request data:

• email_id - The system ID of the email to retrieve.

Response data:

• A email node with all data available in the format of the Object Data.

Method: GetEmails

Returns emails, with optional filters. If a request is made without any filters, the latest created 100 active emails are returned.

Optional filters:

• email_id
• plan_id
• to_address
• email_subject
• deleted - Set to "1" to retrieve deleted emails. Default: "0" (only active emails).
• offset - Retrieval will begin after offset # of records. Useful for pagination. Default: 0.
• limit - The total number of records to retrieve, beginning at the offset. Maximum: 100. Default: 100.

Response data:

• results - Number of records in this response
• total_results - Total # of records to retrieve. Use offset to gather all records over multiple iterated requests.
• emails
  • A email node for each returned recurring charge
    • All data available for the email, as per the Object Data.

Method: GetEmailVariables

Retrieve a list of all available dynamic variables for a particular email trigger. This is useful when creating a new email.

Request data:

• trigger - The system name of the trigger being requested.

Response data:

• variables
  • A variable node for each variable.