Welcome to SFSE. This is a really broad topic and can go many different directions. Let start with a few terminology things:
- An Email Template an is an email model consisting of HTML, CSS & AMPScript defined with content placeholders that can vary in the Email Definition
- The Email Definition can be based on a template or contain raw HTML CSS and AMPScript. These can be deployed as a Test Send or via the Guided Send process.
- The Email Send Definition is also known as a User-Initiated Send. A Send Definition is the combination of an Email Definition and a predefined audience (List, Filter or Data Extension). These can be deployed manually, scheduled in an Automation or executed via API.
- A Triggered Send is an Email Definition configured to accept an audience payload and executed via API call only.
Here are how the terminology above maps to the SOAP API Objects:
- Email Send Definition is a EmailSendDefinition Object, sent using the Perform method
- Email Definition is an Email Object and can be created using a Create method
- Triggered Send is a TriggeredSend Object that references a TriggeredSendDefinition Object. These are executing using the Create method on the TriggeredSend Object. TriggeredSends are always queued in the platform and then sent one at a time.
In the scenario you described, it sounds like a Triggered Send is the best option. Here's what you need to do:
In the SFMC Platform
(Technically you can do all of these things with the API, but I would not recommend it.)
- Create an Email Definition (or Email Template + Email Definition).
- Create a Triggered Send Data Extension based on the Trigger Data Extension Template (to hold the payload sent from your API call). This is not to be confused with an Email Template.
- Create a Triggered Send Definition in Interactions that references your Email Definition. Make sure it's logging the payloads to the Data Extension you defined in Step 2.
- Publish the Trigger
In your development environment
- Using the API, create an API request on the TriggeredSend object, referencing your Triggered Send Definition by
CustomerKey(aka External Key).
Here's a sample SOAP envelope:
<CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI"> <Objects xsi:type="TriggeredSend"> <Client> <ID><!-- YOUR ACCOUNT'S MID --></ID> </Client> <PartnerKey xsi:nil="true"/> <ObjectID xsi:nil="true"/> <TriggeredSendDefinition> <PartnerKey xsi:nil="true"/> <ObjectID xsi:nil="true"/> <CustomerKey><!-- CUSTOMER/EXTERNAL KEY FROM TSD --></CustomerKey> </TriggeredSendDefinition> <Subscribers> <PartnerKey xsi:nil="true"/> <ObjectID xsi:nil="true"/> <EmailAddress>email@example.com</EmailAddress> <SubscriberKey>firstname.lastname@example.org</SubscriberKey> <Attributes> <Name>FirstName</Name> <Value><![CDATA[John]]></Value> </Attributes> <!-- MORE ATTRIBUTES NODES HERE --> <!-- THESE WILL BE WRITTEN TO TS DATA EXTENSION IF NAMES MATCH COLUMNS --> </Subscribers> </Objects> </CreateRequest>