docusealco/docuseal · error · Submissions::CreateFromSubmitters::BaseError

Recipient emails should differ

Error message

Recipient emails should differ

What it means

Submissions::CreateFromSubmitters raises BaseError 'Recipient emails should differ' (lib/submissions/create_from_submitters.rb:86) only when the template preference validate_unique_submitters is exactly true. It compares the number of non-nil submitter emails against their uniq size; any duplicated email among the created submitters fails the whole submission create.

Source

Thrown at lib/submissions/create_from_submitters.rb:86

          is_order_sent = submitters_order == 'random' ||
                          (template_submitter['order'] || submitter_attrs[:index] || index).zero?

          build_submitter(submission:, attrs: submitter_attrs,
                          uuid:, is_order_sent:, user:, params:,
                          preferences: preferences.merge(submission_preferences))
        end

        maybe_set_dynamic_documents(submission)
        maybe_set_template_fields(submission, attrs[:submitters], with_template:, new_fields:)

        if submission.submitters.size > template.submitters.size
          raise BaseError, 'Defined more signing parties than in template'
        end

        if template.preferences['validate_unique_submitters'] == true
          submission_emails = submission.submitters.filter_map(&:email)

          raise BaseError, 'Recipient emails should differ' if submission_emails.uniq.size != submission_emails.size
        end

        next if submission.submitters.blank?

        maybe_add_invite_submitters(submission, template, attrs[:submitters])

        assign_submitters_is_viewer(submission)

        submission.template = nil unless with_template

        submission.tap(&:save!)
      end

      maybe_enqueue_expire_at(submissions)

      submissions
    end

View on GitHub (pinned to 004a22c1c8)

Solutions

1. Give each party a distinct email address, or merge the person's roles into one submitter entry with roles: ['Role A', 'Role B'] so only one submitter is created.
2. If the same mailbox must receive both, use an alias (user+role@domain) so the strings differ.
3. Turn off template.preferences['validate_unique_submitters'] in the template editor if reuse is legitimately allowed by your workflow.
4. Rescue CreateFromSubmitters::BaseError and return 422 with the message so the client can correct recipients.

Example fix

# before
{ submitters: [
  { role: 'Director', email: 'jane@corp.com' },
  { role: 'Secretary', email: 'jane@corp.com' }
] }

# after (one party, merged roles)
{ submitters: [
  { roles: %w[Director Secretary], email: 'jane@corp.com' }
] }

# Pre-validate uniqueness when the template enforces it
def unique_emails?(template, submitters_attrs)
  return true unless template.preferences['validate_unique_submitters'] == true

  emails = Array(submitters_attrs).flat_map { |a| Array(a[:submitters]) }.filter_map { |s| s[:email].to_s.downcase.squish }
  emails.uniq.size == emails.size
end

begin
  Submissions::CreateFromSubmitters.call(template:, user:, submissions_attrs:, source:, submitters_order:)
rescue Submissions::CreateFromSubmitters::BaseError => e
  render json: { error: e.message }, status: :unprocessable_entity
end

When it happens

Trigger: POST /api/submissions with two or more submitters entries carrying the same email (case differences count as equal only if normalized the same — Submissions.normalize_email runs first); the same person assigned to two template parties on a template with validate_unique_submitters: true.

Common situations: One signer holding multiple roles in a workflow (director + secretary); test payloads reusing one test email for every party; templates where the preference was enabled after integrations went live.

Related errors

• Invalid submitter params
• Defined more signing parties than in template
• file param is missing
• Invalid #{type} value
• Invalid value, url, base64 or text < 60 chars is expected: #

AI-assisted analysis of docusealco/docuseal@004a22c1c8 (2026-08-21). Data as JSON: /api/errors/c2d2fd0533c566e4. Report an issue: GitHub.