Send an Email
This API is used to send an Email to one or more users using an Email Template.
Request#
OpenAPI Spec
Request Parameters#
emailTemplateId UUID required The Id of the Email Template to use to generate the Email from.
Request Body#
applicationId UUID optional Available since 1.28.0An optional application Id, when provided the application object will be available in the email template for variable replacement.
bccAddresses Array<String> optional A list of email addresses to BCC when sending the Email.
ccAddresses Array<String> optional A list of email addresses to CC when sending the Email.
preferredLanguages Array<String> Available since 1.28.0An ordered list of locale strings to utilize when localizing the email template for address provided in the toAddresses. See Locales.
requestData Object optional An 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.
toAddresses Array optional Available since 1.28.0A 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 String required The email address for the user. Using the toAddresses is optional, but when providing one or more entries, this field is required.
toAddresses.display String optional 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.
userIds Array<UUID> optional The 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.
Example Request JSON
{
"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#
anonymousResults Map<String,Object> Available since 1.28.0This 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 Map<String,String> Available since 1.28.0Contains 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 Map<String,String> Available since 1.28.0Contains 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 Map<UUID,Object> This is a Mapping between the User Ids that had errors and the errors that were encountered.
results[userId].parseErrors Map<String,String> 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 Map<String,String> 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.
Example Response JSON
{
"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----"
}
}
}
}