Send an Email API
On this page
This API is used to send an Email to one or more users using an Email Template.
Request#
OpenAPI Spec
Path Parameters#
emailTemplateIdThe Id of the Email Template to use to generate the Email from.
Request Body#
applicationIdAn optional application Id, when provided the application object will be available in the email template for variable replacement.
bccAddressesA list of email addresses to BCC when sending the Email.
ccAddressesA list of email addresses to CC when sending the Email.
preferredLanguagesAn ordered list of locale strings to utilize when localizing the email template for address provided in the toAddresses. See Locales.
requestDataAn optional JSON object that is passed to the Email Template during rendering. The variables in the JSON object will be accessible to the FreeMarker templates of the Email Template.
toAddressesA list of email addresses to send the Email to. It is not required that a user exist in FusionAuth with this email address, this may be useful when sending invitations to users that do not yet exist in FusionAuth.
This field may be used in addition to, or as an alternative to the userIds field.
toAddresses.address The email address for the user. Using the toAddresses is optional, but when providing one or more entries, this field is required.
toAddresses.display An optional display name that can be used to construct the to address.
For example, in this example string Erlich Bachman<bachman@piedpiper.com>, Erlich Bachman is the display name and bachman@piedpiper.com is the address.
userIdsThe list of User Ids to send the Email to.
This field may be used in addition to, or as an alternative to the toAddresses field.
Prior to version 1.28.0, this field was required.
{
"bccAddresses": [
"jared@piedpiper.com"
],
"ccAddresses": [
"james@bond.com"
],
"requestData": {
"message": "Thank you for purchasing the answer to the universe. We appreciate your business",
"paymentAmount": 42
},
"toAddresses": [
{
"address": "accounting@piedpiper.com",
"display": "Piped Piper Accounting"
},
{
"address": "sales@piedpiper.com"
}
],
"userIds": [
"ce485a91-906f-4615-af75-81d37dc71e90"
]
}Response#
Response Codes| Code | Description |
|---|---|
| 202 | The request was successful. The response will contain a JSON body. If the JSON body is empty the template was rendered correctly and queued to be sent for all user Ids provided. If one or more failed the response will contain errors in the response format documented below. |
| 400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
Response Body#
anonymousResultsThis is a Mapping between the email address that had errors and the errors that were encountered. This mapping is used for errors that occur when using the toAddresses field on the send request.
anonymousResults[email].parseErrors Contains any parse errors that occurred while parsing the Email Template parts. The key of the Map is the field that failed (i.e. from) and the value is the error message.
anonymousResults[email].renderErrors Contains any template errors that occurred while executing the Email Template parts. The key of the Map is the field that failed (i.e. from) and the value is the error message.
resultsThis is a Mapping between the User Ids that had errors and the errors that were encountered.
results[userId].parseErrors Contains any parse errors that occurred while parsing the Email Template parts. The key of the Map is the field that failed (i.e. from) and the value is the error message.
results[userId].renderErrors Contains any template errors that occurred while executing the Email Template parts. The key of the Map is the field that failed (i.e. from) and the value is the error message.
{
"results": {
"00000000-0000-0001-0000-000000000000": {
"renderErrors": {
"html": "freemarker.core.InvalidReferenceException: The following has evaluated to null or missing:\n==> requestData.not [in nameless template at line 1, column 3]\n\n----\nTip: It's the step after the last dot that caused this error, not those before it.\n----\nTip: If the failing expression is known to be legally refer to something that's sometimes null or missing, either specify a default value like myOptionalVar!myDefault, or use [#if myOptionalVar??]when-present[#else]when-missing[/#if]. (These only cover the last step of the expression; to cover the whole expression, use parenthesis: (myOptionalVar.foo)!myDefault, (myOptionalVar.foo)??\n----\n\n----\nFTL stack trace (\"~\" means nesting-related):\n\t- Failed at: ${requestData.not.here} [in nameless template at line 1, column 1]\n----"
}
}
}
}Related
Learn about the APIs for creating, retrieving, updating and deleting email templates as well as sending emails to users.
API documentation for the FusionAuth Create an Email Template API.
API documentation for the FusionAuth Delete an Email Template API.
API documentation for the FusionAuth Preview an Email Template API.