Defining Status Codes - api

Question

I am building a wrapper for a 3rd party api (email suite) inside of a web application, accessible internally and via an own api. The methods take, for example, an email-address and a subscription list as a parameter and return a result code.
So basically I want to:
Define status codes to display different states of success/failure.
For example successes:
new contact created
new contact created AND optin mail sent
new contact created AND coupon sent
existing contact subscribed
existing contact subscribed AND coupon sent
and so on..
All of these cases are basically the category 2xx OK, but have to trigger different user feedback messages, that's why I'm unhappy with using the HTTP status codes. Using pure HTTP status codes doesn't give feedback detailed enough and defining a) additional status codes or b) completely custom status codes feels so random.
So, what is the best practice to go here?
This answer suggests that I should always use the standard HTTP status codes and if they do not apply, my design is wrong. How would I distinguish the difference, without using additional logic and api calls on the client side?

Answer 1

The purpose of HTTP status codes is to convey the status of the HTTP operation - was it successful, unauthorized, pending, misconfigured, whatever. In all your described cases, the requested operation was successful - everything went as planned. So the most likely status code is 200 OK or 201 CREATED for ALL those cases.
Additional domain-specific statuses should not be forcefully hammered into HTTP statuses. Just return an additional field in your response. For example:
POST http://www.example.com/users
{
name : "The User",
email : "email#theuser.com"
}
Response would contain:
201 CREATED
{
status : "Optin mail sent",
timestamp : "...",
...
}
This keeps a cleaner separation of concerns and improves extensibility.

Answer 2

How would I distinguish the difference, without using additional logic and api calls on the client side?
Use meaningful response bodies. The status code is just that. You don't want to create a new HTTP status code for each new combination of results.
So for your first three scenarios:
HTTP/1.1 201 Created
...
{
contact_created: "true",
optin_mail_sent: "true",
coupon_sent: "true",
}
You need some display logic on the client side any way (e.g. from 254 ContactYesOptInNoCouponYes to the appropriate notifications), so the response body seems the most sensible and extensible way possible.