Email Service Integration - MailChimp - Transactional email¶
Target Audience: Developers, Stakeholders
Creating your MailChimp account¶
In order to get started with sending your first email through MailChimp, a MailChimp account naturally has to be created. You can create a free MailChimp account here.
Once you have created your MailChimp account, navigate to Profile => Settings => Details, and change your "Email builder" from New Builder to Classic Builder. This will be required in a later step.
Fetching your API key¶
In order for the email sending to be possible, an API Key is required. While it is tempting to create a MailChimp API key, this is not the correct one, and we are rather interested in a Mandrill API key, which is an add-on built by Mailchimp.
In order to obtain your Mandrill API key, perform the following steps:
- From within Mailchimp, navigate to Profile => Extras => API keys => Create A Mandrill API Key.
- Click Create API Key. Save this API key somewhere, as it will be needed later.
Once you have created and saved your API key somewhere safe, you can proceed to the next step.
Configuring your sending domain¶
Having the MailChimp account created and the Mandrill API key fetched, we can now move on to configuring your sending domain. This is a process that validates that you, in fact, own the domain that you say you do, and allow email's to be sent from that given domain.
In order to configure your sending domain, perform the following steps:
- From within Mandrill, navigate to Settings => Domains => Sending Domains.
- Enter your domain, and hit Add. If you wish to send e-mail from "no-reply@organisation.com", the value here should in other words be "organisation.com".
- Follow the on-screen guide provided by Mandrill to verify your domain, and validate both DKIM and DMARC.
Configuring your first email template¶
Now that you have the required accounts and credentials, and verified that you in fact own your own domain, the fun can begin.
From within MailChimp, navigate to Content => Email templates => Create template, and get started with your first template, designing it however you wish.
After you have your design in-place, the name of the email template must correspond to the correct email event, and will otherwise not be used. To get a better idea of what the naming convention looks like, we refer to the following table:
| Event | Template name | Template slug |
|---|---|---|
| OrderClosed | Order closed | order-closed |
| PaymentSuccess | Payment success | payment-success |
| PaymentFailure | Payment failure | payment-failure |
| PaymentUserAgreementInvalidState | Payment user agreement invalid state | payment-user-agreement-invalid-state |
| PaymentUserProductDeactivated | Payment user product deactivated | payment-user-product-deactivated |
| PaymentUserProductRenewed | Payment user product renewed | payment-user-product-renewed |
| UserProductCancelled | User product cancelled | user-product-cancelled |
| NewAccountCreatedFromKis | New account created from KIS | new-account-created-from-kis |
| NewAccountRegistered | New account registered | new-account-registered |
| NewCheckoutAccountRegistered | New checkout account registered | new-checkout-account-registered |
| AccountActivatedForExistingCustomer | Account activated for existing customer | account-activated-for-existing-customer |
| AccountRequestedEmailChange | Account requested email change | account-requested-email-change |
| ConfirmationEmailRequested | Confirmation email requested | confirmation-email-requested |
| AccountRequestedPasswordReset | Account requested password reset | account-requested-password-reset |
| AccountPasswordResetComplete | Account password reset complete | account-password-reset-complete |
| GiftOrderClosed | Gift order closed | gift-order-closed |
| VoucherCreated | Voucher created | voucher-created |
| VoucherRedeemed | Voucher redeemed | voucher-redeemed |
| TransitionedToRetentionCampaign | Transitioned to retention campaign | transitioned-to-retention-campaign |
| PendingSubscriptionValidationChange | Pending subscription validation change | pending-subscription-validation-change |
| PaymentRetry | Payment retry | payment-retry |
| PaymentRetrySuccessful | Payment retry successful | payment-retry-successful |
| PaymentAgreementAboutToExpire | Payment agreement about to expire | payment-agreement-about-to-expire |
| PackageDowngrade | Package downgrade | package-downgrade |
| PackageChangeCompleted | Package change completed | package-change-completed |
| PackageUpgrade | Package upgrade | package-upgrade |
| AccountCreatedWithPasswordReset | Account created with password reset | account-created-with-password-reset |
If you have renamed an existing template, or a specific template does not seem to be working as it should, it is possible the template slug has gotten out of sync, and if so, must be manually adjusted. In order to manually adjust a template slug, navigate to Mandrill => Outbound => Templates => Edit, and verify the "Template slug" against the table above.
Once you have created or updated an email template, find the dropdown menu next to the "Edit" button of the template, hit "Send to Mandrill", and the template is all set. Modified templates will not be automatically sent to Mandrill, and as such, the old revision will be used until it is sent.
Sending your first email¶
Once you have gotten this far, you're almost through the finishing line!
Now, all that remains, is to simply contact our support. Information that must be included in this request are:
- Your Mandrill API Key
- Your MailChimp datacenter. This can be found by logging into your MailChimp account and looking at the URL. The datacenter should look something like "us18".
- Your sender email address (the email address that your email's should originate from)
Once your support request has been sent and we have had time to process it, you can start sending your first emails from MailChimp!
Tags¶
In order to display dynamic content within your email templates, we recommend the usage of tags.