Send an Email

This API is used to send an Email to one or more users using an Email Template.

Request#

Send an email using a template by Id

POST/api/email/send/{emailTemplateId}

OpenAPI Spec

Request Parameters#

emailTemplateIdUUIDrequired

The Id of the Email Template to use to generate the Email from.

Request Body#

applicationIdUUIDoptionalAvailable since 1.28.0

An optional application Id, when provided the application object will be available in the email template for variable replacement.

bccAddressesArray<String>optional

A list of email addresses to BCC when sending the Email.

ccAddressesArray<String>optional

A list of email addresses to CC when sending the Email.

preferredLanguagesArray<String>Available since 1.28.0

An ordered list of locale strings to utilize when localizing the email template for address provided in the toAddresses. See Locales.

requestDataObjectoptional

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.

toAddressesArrayoptionalAvailable since 1.28.0

A 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.addressStringrequired

The email address for the user. Using the toAddresses is optional, but when providing one or more entries, this field is required.

toAddresses.displayStringoptional

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.

userIdsArray<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#

anonymousResultsMap<String,Object>Available since 1.28.0

This 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].parseErrorsMap<String,String>Available since 1.28.0

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].renderErrorsMap<String,String>Available since 1.28.0

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.

resultsMap<UUID,Object>

This is a Mapping between the User Ids that had errors and the errors that were encountered.

results[userId].parseErrorsMap<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].renderErrorsMap<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----"
      }
    }
  }
}